{"openapi":"3.1.0","info":{"title":"Hoookd API","version":"1.0.0","summary":"Scan a website and read how well it works for AI models and agents.","description":"Hoookd scans a website and reports how well AI crawlers can reach it, how well a model can read it, and how well an agent can act on it.\n\nA scan runs in the background. Start one, read its status until it is \"completed\", then read its findings and their fixes.\n\nEvery finding is either \"verified\" (read directly from the site) or an \"estimate\" (from a sample or a model's reading). The two are always returned in separate arrays.\n\nReading is open to anyone who holds a scan id, the same as the shareable report. A scan started without an account is shown as a preview: the scores and the top three findings.\n\nThe API only reads a site and proposes fixes. It never changes a site."},"servers":[{"url":"https://app.hoookd.space"}],"security":[{},{"apiKey":[]}],"tags":[{"name":"Scans","description":"Start a scan and read its status and scores."},{"name":"Findings","description":"What a scan found, and what to do about it."},{"name":"AI visibility","description":"What AI models say about the product. Estimates."},{"name":"Exports","description":"The whole report as a file."}],"paths":{"/api/v1/scans":{"post":{"operationId":"startScan","tags":["Scans"],"summary":"Start a scan of a website","description":"Starts a scan and returns its id. With an API key the scan belongs to the key's owner, who gets the full report. Without one the scan is anonymous: limited by IP address and shown as a preview.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","maxLength":2048,"description":"The address of the site. \"example.com\" is read as https://example.com/.","examples":["https://example.com"]},"ai_visibility":{"type":"boolean","default":false,"description":"Also ask AI models about the product once the checks have run. Costs money per run, so it is honoured only with an API key or a session."}}}}}},"responses":{"202":{"description":"The scan was queued.","headers":{"Location":{"description":"Where to read the scan.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["scan_id"],"properties":{"scan_id":{"type":"string","format":"uuid"}}}}}},"400":{"description":"The body is not valid, or the address cannot be scanned: it is not a web address, or it points to a private network.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A scan of this site is already running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many scans in the last hour, by this caller or of this site. The message says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The scan could not be queued. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/scans/{id}":{"get":{"operationId":"getScan","tags":["Scans"],"summary":"Read the status, the scores and a summary of a scan","description":"While the scan runs, \"status\" and \"progress\" change. Once \"status\" is \"completed\", \"scores\" and \"summary\" are set. Poll every few seconds: a scan takes one to five minutes.","parameters":[{"name":"id","in":"path","required":true,"description":"The id of a scan, as returned when the scan was started.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The scan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scan"}}}},"404":{"description":"No scan has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/scans/{id}/findings":{"get":{"operationId":"listFindings","tags":["Findings"],"summary":"List the findings of a finished scan","description":"Quick wins first: findings are ordered by severity divided by effort. Verified findings and estimates come in separate arrays.","parameters":[{"name":"id","in":"path","required":true,"description":"The id of a scan, as returned when the scan was started.","schema":{"type":"string","format":"uuid"}},{"name":"category","in":"query","schema":{"type":"string","enum":["access","readability","structured_data","actionability","trust"]}},{"name":"severity","in":"query","schema":{"type":"string","enum":["critical","high","medium","low"]}},{"name":"confidence","in":"query","schema":{"type":"string","enum":["verified","estimate"]}}],"responses":{"200":{"description":"The findings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Findings"}}}},"400":{"description":"A filter has a value that is not one of those listed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No scan has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The scan has not finished, or it failed, so there is nothing to read yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/findings/{id}/fix":{"get":{"operationId":"getFix","tags":["Findings"],"summary":"Read what to do about one finding","description":"Every finding has an instruction. Where a file can be drafted (robots.txt, JSON-LD, llms.txt, a rewrite, a starter OpenAPI description, an MCP outline) the draft comes with it, made only from facts found on the site. A fact that was not found is marked TODO. When a draft could not be made, the reason is given and nothing is put in its place.","parameters":[{"name":"id","in":"path","required":true,"description":"The id of a finding, from the findings of a scan.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fix"}}}},"403":{"description":"The finding is not part of the preview of its report. Use an API key to read the full report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No finding has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/scans/{id}/rescan":{"post":{"operationId":"rescan","tags":["Scans"],"summary":"Scan the same address again and compare","description":"Starts a new scan of the same address. Its report says what changed: which findings are resolved, new and unchanged. A scan that a signed-in user started can be scanned again only by that user.","parameters":[{"name":"id","in":"path","required":true,"description":"The id of a scan, as returned when the scan was started.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"refresh_ai_visibility":{"type":"boolean","default":false,"description":"Ask the AI visibility questions again. Left false, the earlier answers are carried over, so that a change in the score reflects a change to the site."}}}}}},"responses":{"202":{"description":"The new scan was queued.","content":{"application/json":{"schema":{"type":"object","required":["scan_id","parent_scan_id"],"properties":{"scan_id":{"type":"string","format":"uuid"},"parent_scan_id":{"type":"string","format":"uuid"}}}}}},"400":{"description":"The body is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The scan belongs to someone else.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No scan has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The scan has not finished, or a scan of this site is already running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many scans in the last hour, by this caller or of this site. The message says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The scan could not be queued. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/scans/{id}/ai-visibility":{"get":{"operationId":"getAiVisibility","tags":["AI visibility"],"summary":"Read the questions, the answers and the score of AI visibility","description":"A dated sample, not a ranking: each answer is what one model said on one day. Every figure is an estimate. The answers are returned exactly as the models gave them.","parameters":[{"name":"id","in":"path","required":true,"description":"The id of a scan, as returned when the scan was started.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"AI visibility of the scan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiVisibility"}}}},"404":{"description":"No scan has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"runAiVisibility","tags":["AI visibility"],"summary":"Put the questions to the models","description":"Runs AI visibility for a finished scan, with the questions written for it or with your own. Only the user who started the scan can. The run happens in the background: read the result with GET.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The id of a scan, as returned when the scan was started.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"questions":{"type":"object","additionalProperties":false,"required":["unbranded","branded"],"properties":{"unbranded":{"type":"array","maxItems":5,"items":{"type":"string","maxLength":300},"description":"Questions that must not name the product."},"branded":{"type":"array","maxItems":2,"items":{"type":"string","maxLength":300},"description":"Questions that name the product."}}},"refresh":{"type":"boolean","default":false,"description":"Needed to ask again when answers are already stored. Every question is charged again."}}}}}},"responses":{"202":{"description":"The run was queued.","content":{"application/json":{"schema":{"type":"object","required":["scan_id","status"],"properties":{"scan_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued"]}}}}}},"400":{"description":"The body is not valid, or a question cannot be asked. \"problems\" says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An API key or a session is needed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The scan was started by someone else, or without an account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No scan has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The scan has not finished, a run is under way, answers are already stored, or the site could not be read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The run could not be queued. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/report/{id}/report.json":{"get":{"operationId":"exportReportJson","tags":["Exports"],"summary":"The whole report as JSON","parameters":[{"name":"id","in":"path","required":true,"description":"The id of a scan, as returned when the scan was started.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"404":{"description":"No scan has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The scan has not finished, or it failed, so there is nothing to read yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/report/{id}/report.md":{"get":{"operationId":"exportReportMarkdown","tags":["Exports"],"summary":"The whole report as Markdown","description":"For a person to read, or to hand to a coding agent together with the site's code.","parameters":[{"name":"id","in":"path","required":true,"description":"The id of a scan, as returned when the scan was started.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The report.","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"No scan has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The scan has not finished, or it failed, so there is nothing to read yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from the account page, sent as \"Authorization: Bearer <key>\". The header \"x-api-key: <key>\" is accepted as well."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"A stable name for the problem."},"message":{"type":"string","description":"A sentence for a person."},"problems":{"type":"array","items":{"type":"string"},"description":"What is wrong with each question, for invalid questions."}}}}},"Scan":{"type":"object","required":["scan_id","status","input_url","start_url","created_at","progress"],"properties":{"scan_id":{"type":"string","format":"uuid"},"parent_scan_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"status":{"type":"string","enum":["queued","running","completed","failed"]},"input_url":{"type":"string"},"start_url":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"progress":{"type":"object","properties":{"stage":{"anyOf":[{"type":"string"},{"type":"null"}]},"done":{"anyOf":[{"type":"integer"},{"type":"null"}]},"total":{"anyOf":[{"type":"integer"},{"type":"null"}]},"label":{"type":"string","description":"The stage in words."},"categories":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]}}},"error":{"anyOf":[{"type":"string","description":"Why the scan failed."},{"type":"null"}]},"site":{"type":"object","properties":{"home_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"not_crawled":{"anyOf":[{"type":"object","description":"Set when the site could not be crawled, with the reason.","properties":{"reason":{"type":"string"},"detail":{"type":"string"}}},{"type":"null"}]}}},"pages":{"type":"array","items":{"type":"object","additionalProperties":true}},"report_url":{"anyOf":[{"type":"string","description":"Where the report is, once finished."},{"type":"null"}]},"scores":{"anyOf":[{"type":"object","properties":{"overall":{"anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}]},"not_scored_reason":{"anyOf":[{"type":"string","description":"Why there is no overall score: no category could be scored, or the homepage could not be fetched. Null when there is one."},{"type":"null"}]},"cap_applies":{"type":"boolean","description":"True when robots.txt blocks all six AI search bots and agents, which caps the overall score at 40."},"cap_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"label":{"type":"string"},"weight":{"type":"number"},"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"not_scored_reason":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","properties":{"access":{"type":"string","enum":["full","preview"],"description":"\"preview\": this caller gets the scores and the top three findings."},"findings":{"type":"object","properties":{"verified":{"type":"integer"},"estimates":{"type":"integer"}}},"not_checked":{"type":"integer"},"ai_visibility":{"type":"string"}}},{"type":"null"}]}}},"Finding":{"type":"object","required":["id","check_id","severity","confidence","title","detail","fix"],"properties":{"id":{"type":"string","format":"uuid","description":"Use it to read the fix."},"check_id":{"type":"string","examples":["A2"]},"category":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"confidence":{"type":"string","enum":["verified","estimate"]},"title":{"type":"string"},"detail":{"type":"string","description":"What is wrong."},"why_it_matters":{"type":"string"},"evidence":{"type":"array","description":"What was read on the site: a line, a tag, a header, a response.","items":{"type":"object","required":["kind","excerpt"],"properties":{"kind":{"type":"string"},"excerpt":{"type":"string"},"label":{"type":"string"},"url":{"type":"string"},"locator":{"type":"string"}}}},"page_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"effort":{"type":"integer","enum":[1,2,3],"description":"1 paste a file, 2 edit templates, 3 engineering work."},"priority":{"type":"number","description":"Severity weight divided by effort."},"optional":{"type":"boolean","description":"True for a check that is never scored."},"leading":{"type":"boolean","description":"True for the finding that caps the score."},"combines":{"anyOf":[{"type":"array","items":{"type":"string"},"description":"The checks this finding stands for, when several failed for one reason."},{"type":"null"}]},"fix":{"type":"object","required":["kind","instruction"],"properties":{"kind":{"type":"string","enum":["instruction","robots_txt","json_ld","llms_txt","rewrite","openapi_starter","mcp_outline"]},"instruction":{"type":"string"}}}}},"Findings":{"type":"object","required":["scan_id","access","verified","estimates"],"properties":{"scan_id":{"type":"string","format":"uuid"},"access":{"type":"string","enum":["full","preview"]},"preview":{"anyOf":[{"type":"object","description":"Set for a preview: what this caller is not shown.","properties":{"hidden_verified":{"type":"integer"},"hidden_estimates":{"type":"integer"},"message":{"type":"string"}}},{"type":"null"}]},"verified":{"type":"array","items":{"$ref":"#/components/schemas/Finding"},"description":"Read directly from the site."},"estimates":{"type":"array","items":{"$ref":"#/components/schemas/Finding"},"description":"From a sample or a model's reading. Can differ between scans."}}},"GeneratedFix":{"type":"object","required":["kind","title","usage","parts","todos","notes","generated_by"],"properties":{"kind":{"type":"string"},"title":{"type":"string"},"usage":{"type":"string","enum":["choose_one","all"],"description":"\"choose_one\": the parts are alternatives. \"all\": every part is needed."},"parts":{"type":"array","items":{"type":"object","required":["id","title","note","body","format"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"note":{"type":"string","description":"Where it goes, or what choosing it costs."},"body":{"type":"string","description":"The text to paste."},"format":{"type":"string","enum":["text","html","json","markdown"]}}}},"todos":{"type":"array","items":{"type":"string"},"description":"What the owner has to fill in. These facts were not found on the site."},"notes":{"type":"array","items":{"type":"string"}},"label":{"anyOf":[{"type":"string","description":"A warning that stays with the fix, such as \"Draft. Needs review by an engineer.\""},{"type":"null"}]},"generated_by":{"type":"string","description":"\"rules\", or the id of the model that wrote it."}}},"Fix":{"type":"object","required":["finding_id","scan_id","check_id","title","fix"],"properties":{"finding_id":{"type":"string","format":"uuid"},"scan_id":{"type":"string","format":"uuid"},"check_id":{"type":"string"},"title":{"type":"string"},"severity":{"type":"string"},"confidence":{"type":"string","enum":["verified","estimate"]},"effort":{"type":"integer","enum":[1,2,3]},"fix":{"type":"object","required":["kind","instruction","generated","not_generated_reason"],"properties":{"kind":{"type":"string"},"instruction":{"type":"string","description":"What to change, in words."},"generated":{"anyOf":[{"$ref":"#/components/schemas/GeneratedFix"},{"type":"null"}]},"not_generated_reason":{"anyOf":[{"type":"string","description":"Why there is no draft, when one could not be made."},{"type":"null"}]}}}}},"AiVisibility":{"type":"object","required":["scan_id","status","confidence","label","questions"],"properties":{"scan_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["not_started","not_checked","questions_ready","queued","running","completed"]},"confidence":{"type":"string","enum":["estimate"]},"label":{"type":"string","description":"What this is. It must stay with the numbers."},"reason":{"anyOf":[{"type":"string","description":"Why it was not checked."},{"type":"null"}]},"models":{"type":"array","items":{"type":"string"}},"asked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"score":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"questions":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"},"kind":{"type":"string","enum":["unbranded","branded"]},"text":{"type":"string"},"answers":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"model":{"type":"string"},"raw_text":{"anyOf":[{"type":"string","description":"The answer exactly as the model gave it."},{"type":"null"}]}}}}}}}}},"Report":{"type":"object","description":"The report model: scores with their arithmetic, findings, fixes, what was not checked, AI visibility and, for a re-scan, what changed.","required":["format","version","scan_id","score","categories","findings"],"properties":{"format":{"type":"string","enum":["hoookd-report"]},"version":{"type":"integer"},"scan_id":{"type":"string","format":"uuid"},"access":{"type":"string","enum":["full","preview"]},"score":{"type":"object","additionalProperties":true},"categories":{"type":"array","items":{"type":"object","additionalProperties":true}},"findings":{"type":"object","properties":{"verified":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"estimates":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}}}},"fixes":{"type":"array","items":{"type":"object","additionalProperties":true}},"comparison":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"not_checked":{"type":"array","items":{"type":"object","additionalProperties":true}},"ai_visibility":{"anyOf":[{"$ref":"#/components/schemas/AiVisibility"},{"type":"null"}]}}}}}}