{"openapi":"3.1.0","info":{"title":"Folio Agent API","version":"1.0.0","description":"Owner-private website checks and Astra search observations. GET reads saved data; explicit ensure requests may start paid work."},"servers":[{"url":"/api/v1"}],"paths":{"/seo":{"get":{"operationId":"folio_seo-reports","summary":"Saved SEO reports","description":"List saved DataForSEO reports; pass reportId to read an owned report. Never starts a lookup. Requires read permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"reportId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"folio_seo-lookup","summary":"Update search and backlinks","description":"One paid domain overview with two provider endpoints. Requires confirmSpend and a stable Idempotency-Key. Replays return saved pending or complete state without retrying provider work. Requires seo permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Keep this value for retries of the same logical request. Reusing it with a different body is an error.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["domain","confirmSpend"],"properties":{"domain":{"type":"string"},"confirmSpend":{"const":true}}},"example":{"domain":"example.com","confirmSpend":true}}}},"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/visibility/current":{"get":{"operationId":"folio_visibility-current","summary":"Current visibility","description":"Read saved open-web observations for one owned website. Never starts a task. See date filters and metric definitions below. Requires read permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"websiteId","in":"query","required":true,"schema":{"type":"string"},"description":"See visibility metric definitions."},{"name":"startDate","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive UTC date, YYYY-MM-DD"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive UTC date, YYYY-MM-DD"},{"name":"platform","in":"query","required":false,"schema":{"enum":["openai"]},"description":"See visibility metric definitions."},{"name":"sourceType","in":"query","required":false,"schema":{"enum":["all","owned","external"]},"description":"See visibility metric definitions."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"See visibility metric definitions."},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"See visibility metric definitions."}],"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/visibility/overview":{"get":{"operationId":"folio_visibility-overview","summary":"Visibility overview","description":"Read saved open-web observations for one owned website. Never starts a task. See date filters and metric definitions below. Requires read permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"websiteId","in":"query","required":true,"schema":{"type":"string"},"description":"See visibility metric definitions."},{"name":"startDate","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive UTC date, YYYY-MM-DD"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive UTC date, YYYY-MM-DD"},{"name":"platform","in":"query","required":false,"schema":{"enum":["openai"]},"description":"See visibility metric definitions."},{"name":"sourceType","in":"query","required":false,"schema":{"enum":["all","owned","external"]},"description":"See visibility metric definitions."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"See visibility metric definitions."},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"See visibility metric definitions."}],"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/visibility/citations":{"get":{"operationId":"folio_visibility-citations","summary":"Top cited URLs","description":"Read saved open-web observations for one owned website. Never starts a task. See date filters and metric definitions below. Requires read permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"websiteId","in":"query","required":true,"schema":{"type":"string"},"description":"See visibility metric definitions."},{"name":"startDate","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive UTC date, YYYY-MM-DD"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive UTC date, YYYY-MM-DD"},{"name":"platform","in":"query","required":false,"schema":{"enum":["openai"]},"description":"See visibility metric definitions."},{"name":"sourceType","in":"query","required":false,"schema":{"enum":["all","owned","external"]},"description":"See visibility metric definitions."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"See visibility metric definitions."},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"See visibility metric definitions."}],"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/visibility/prompts":{"get":{"operationId":"folio_visibility-prompts","summary":"Per-question visibility","description":"Read saved open-web observations for one owned website. Never starts a task. See date filters and metric definitions below. Requires read permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"websiteId","in":"query","required":true,"schema":{"type":"string"},"description":"See visibility metric definitions."},{"name":"startDate","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive UTC date, YYYY-MM-DD"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive UTC date, YYYY-MM-DD"},{"name":"platform","in":"query","required":false,"schema":{"enum":["openai"]},"description":"See visibility metric definitions."},{"name":"sourceType","in":"query","required":false,"schema":{"enum":["all","owned","external"]},"description":"See visibility metric definitions."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"See visibility metric definitions."},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"See visibility metric definitions."}],"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/visibility/recommendations":{"get":{"operationId":"folio_visibility-recommendations","summary":"Recommended next steps","description":"Read saved open-web observations for one owned website. Never starts a task. See date filters and metric definitions below. Requires read permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"websiteId","in":"query","required":true,"schema":{"type":"string"},"description":"See visibility metric definitions."},{"name":"startDate","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive UTC date, YYYY-MM-DD"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive UTC date, YYYY-MM-DD"},{"name":"platform","in":"query","required":false,"schema":{"enum":["openai"]},"description":"See visibility metric definitions."},{"name":"sourceType","in":"query","required":false,"schema":{"enum":["all","owned","external"]},"description":"See visibility metric definitions."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"See visibility metric definitions."},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"See visibility metric definitions."}],"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auth/status":{"get":{"operationId":"folio_auth","summary":"Check your key","description":"Confirm the key is valid and inspect its permissions. Requires read permission.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sites":{"get":{"operationId":"folio_sites","summary":"Find your websites","description":"List websites saved in the key owner’s workspace. Use the returned website ID for a page evaluation. Requires read permission.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/benchmark-cases":{"get":{"operationId":"folio_cases","summary":"Find your search questions","description":"List saved keyword cases. Each ID preserves its query, target, locale, and search configuration. Requires read permission.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observations":{"get":{"operationId":"folio_read","summary":"Read the latest saved result","description":"Read a matching result and its age. Missing or stale data does not start a task. Requires read permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"kind","in":"query","required":true,"schema":{"enum":["website","keyword"]}},{"name":"websiteId","in":"query","schema":{"type":"string"},"description":"Required for kind=website; omit for keyword."},{"name":"caseId","in":"query","schema":{"type":"string"},"description":"Required for kind=keyword; omit for website."},{"name":"useSeoTools","in":"query","schema":{"type":"boolean","default":false},"description":"Keyword-only: match the SEO-enabled harness when reading saved evidence."},{"name":"maxAgeSeconds","in":"query","schema":{"type":"integer","minimum":0,"maximum":604800,"default":86400}}],"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observations/ensure":{"post":{"operationId":"folio_ensure","summary":"Get a fresh observation","description":"Reuse a sufficiently recent result or matching active run; otherwise reserve and start one new evaluation. This request can incur usage charges. Requires evaluate permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Keep this value for retries of the same logical request. Reusing it with a different body is an error.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]{8,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["kind","websiteId"],"properties":{"kind":{"const":"website"},"websiteId":{"type":"string"},"maxAgeSeconds":{"type":"integer","minimum":0,"maximum":604800,"default":86400}}},{"type":"object","additionalProperties":false,"required":["kind","caseId"],"properties":{"kind":{"const":"keyword"},"caseId":{"type":"string"},"useSeoTools":{"type":"boolean","default":false,"description":"Authorize one sandbox SEO lookup. Requires seo scope and a public MCP endpoint."},"maxAgeSeconds":{"type":"integer","minimum":0,"maximum":604800,"default":86400}}}]},"example":{"kind":"keyword","caseId":"case_example","maxAgeSeconds":86400}}}},"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"202":{"description":"A matching task is active or a new task was started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runs/{kind}/{id}":{"get":{"operationId":"folio_run","summary":"Read a saved run","description":"Retrieve one private run’s status, result, and usage. This reads Folio’s saved state without contacting the model. Requires read permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"kind","in":"path","required":true,"schema":{"enum":["website","keyword"]}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"maxAgeSeconds","in":"query","schema":{"type":"integer","minimum":0,"maximum":604800,"default":86400}}],"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runs/{kind}/{id}/reconcile":{"post":{"operationId":"folio_reconcile","summary":"Refresh recorded progress","description":"Retrieve the existing remote task and save its returned progress. Creates no new task and submits no pending tool answers. A keyword deadline may request cancellation. Requires evaluate permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"kind","in":"path","required":true,"schema":{"enum":["website","keyword"]}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false},"example":{}}}},"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runs/{kind}/{id}/cancel":{"post":{"operationId":"folio_cancel","summary":"Request cancellation","description":"Request that existing work stop. Keep reading the saved run until its terminal outcome is confirmed; an acknowledgement alone is not completion. Requires evaluate permission.","security":[{"bearerAuth":[]}],"parameters":[{"name":"kind","in":"path","required":true,"schema":{"enum":["website","keyword"]}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false},"example":{}}}},"responses":{"200":{"description":"Saved result or completed action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired, or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or account access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owned record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting request or unresolved creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Expected application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request or evaluation allowance reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; inspect existing state before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Folio API key"}},"schemas":{"Observation":{"type":"object","required":["disposition","freshness","run"],"properties":{"disposition":{"enum":["saved","fresh_saved","existing_active","started","missing"]},"freshness":{"type":"object","required":["maxAgeSeconds","observedAt","ageSeconds","fresh"],"properties":{"maxAgeSeconds":{"type":"integer"},"observedAt":{"type":["string","null"],"format":"date-time"},"ageSeconds":{"type":["number","null"]},"fresh":{"type":"boolean"}}},"run":{"oneOf":[{"type":"null"},{"type":"object","required":["id","kind","status","pollUrl"],"properties":{"id":{"type":"string"},"kind":{"enum":["website","keyword"]},"status":{"enum":["queued","running","requires_action","completed","failed","cancelled"]},"model":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"observedAt":{"type":["string","null"],"format":"date-time"},"recovery":{"$ref":"#/components/schemas/Recovery"},"provenance":{"$ref":"#/components/schemas/Provenance"},"surface":{"type":"string"},"result":{"type":["object","null"],"description":"Website verification checks or keyword recommendations and returned citations."},"usage":{"type":["object","null"],"description":"Unknown usage remains null."},"error":{"type":["string","null"]},"pollUrl":{"type":"string"}}}]}}},"Recovery":{"oneOf":[{"type":"null"},{"type":"object","required":["runId","sessionId"],"properties":{"runId":{"type":"string"},"sessionId":{"type":["string","null"]}}}]},"Provenance":{"type":"object","required":["searchMode","harnessVersion","environmentFingerprint","allowedDomains","completedSearchCount"],"properties":{"searchMode":{"enum":["reviewed-domains","open-web",null]},"harnessVersion":{"type":"string"},"environmentFingerprint":{"type":["string","null"]},"allowedDomains":{"type":"array","items":{"type":"string"}},"completedSearchCount":{"type":["integer","null"],"minimum":0}}},"Error":{"type":"object","required":["error"],"properties":{"recovery":{"$ref":"#/components/schemas/Recovery","description":"Present when submission occurred but local receipt persistence is unconfirmed. Preserve these IDs; do not create replacement work."},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}