{"openapi":"3.1.0","info":{"title":"AIVIS Public API","version":"1.0.0","description":"Read-only access to the JSON-LD content AIVIS generates for your pages.\n\n**Authentication.** Create an API token on your profile page in AIVIS, then send it on every request:\n\n```\nAuthorization: Bearer aivis_…\n```\n\n**Typical flow for a CMS plugin.** Verify the token with `GET /me`, then fetch structured data per page with `GET /jsonld?url=<permalink>` and cache the result. Browsing (`/businesses` → `/businesses/{businessId}/chains` → `/chains/{chainId}/urls`) is for settings screens and status displays.\n\nAll list endpoints use cursor pagination: pass the previous response's `nextCursor` as `?cursor=` until it is `null`."},"servers":[{"url":"/api/public/v1"}],"tags":[{"name":"Content","description":"Read-only access to businesses, chains, URLs and JSON-LD."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API token from your AIVIS profile page (starts with `aivis_`)."}}},"security":[{"bearerAuth":[]}],"paths":{"/me":{"get":{"operationId":"getMe","summary":"Check the API token","description":"Returns the account the presented token belongs to. Use it as a connection test after the user pastes a token into your integration.","tags":["Content"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The token is valid.","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"tokenName":{"description":"Name of the API token used for this request.","type":"string"}},"required":["email","name","tokenName"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"The token's account is deactivated.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/businesses":{"get":{"operationId":"listBusinesses","summary":"List businesses","description":"All businesses of the token's account.","tags":["Content"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's `nextCursor`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 100, maximum 200.","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Paginated businesses.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"baseUrl":{"type":"string"},"industry":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"}},"required":["key","name"],"additionalProperties":false},"chainCount":{"description":"Non-archived chains.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"}},"required":["id","name","baseUrl","industry","chainCount","createdAt"],"additionalProperties":false}},"nextCursor":{"description":"Pass as `?cursor=` to fetch the next page. Null on the last page.","anyOf":[{"type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"},"total":{"description":"Total row count across all pages.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","nextCursor","hasMore","total"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"The token's account is deactivated.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/businesses/{businessId}/chains":{"get":{"operationId":"listBusinessChains","summary":"List chains of a business","description":"Chains (knowledge-graph pipelines) of one business, with pipeline state. `knowledgeGraphReady` tells you whether the graph has been built; archived chains are not returned.","tags":["Content"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"businessId","in":"path","required":true,"description":"Business id from `/businesses`.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's `nextCursor`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 100, maximum 200.","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Paginated chains.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"description":"Pipeline state. `ready` = knowledge graph built; `re_ingesting` = graph built and currently refreshing.","type":"string","enum":["empty","building","ready","re_ingesting"]},"currentStep":{"description":"Current pipeline step (1 Discover … 9 Knowledge Graph).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"knowledgeGraphReady":{"description":"True when the knowledge graph exists (`ready` or `re_ingesting`).","type":"boolean"},"graphScore":{"description":"Universal graph score (GIS), when computed.","anyOf":[{"type":"number"},{"type":"null"}]},"urlCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"}},"required":["id","name","description","state","currentStep","knowledgeGraphReady","graphScore","urlCount","createdAt"],"additionalProperties":false}},"nextCursor":{"description":"Pass as `?cursor=` to fetch the next page. Null on the last page.","anyOf":[{"type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"},"total":{"description":"Total row count across all pages.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","nextCursor","hasMore","total"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"The token's account is deactivated.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Business not found (or not yours).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/chains/{chainId}/urls":{"get":{"operationId":"listChainUrls","summary":"List URLs of a chain","description":"Pages of one chain with per-URL status: capture state and whether generated JSON-LD is available (`jsonLd.ready`) and fresh (`jsonLd.stale`).","tags":["Content"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"chainId","in":"path","required":true,"description":"Chain id from `/businesses/{businessId}/chains`.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page's `nextCursor`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 100, maximum 200.","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Paginated URLs.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"languageCode":{"description":"ISO 639-1 code.","type":"string"},"layer":{"type":"string","enum":["structural_core","editorial"]},"captureStatus":{"description":"Status of the current page capture. Null when never captured.","anyOf":[{"type":"string","enum":["draft","processing","processed","failed"]},{"type":"null"}]},"jsonLd":{"type":"object","properties":{"ready":{"description":"True when a generated JSON-LD document exists.","type":"boolean"},"stale":{"description":"True when the source page changed after generation — the document is still served but should be regenerated.","type":"boolean"},"generatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["ready","stale","generatedAt"],"additionalProperties":false}},"required":["id","url","languageCode","layer","captureStatus","jsonLd"],"additionalProperties":false}},"nextCursor":{"description":"Pass as `?cursor=` to fetch the next page. Null on the last page.","anyOf":[{"type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"},"total":{"description":"Total row count across all pages.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","nextCursor","hasMore","total"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"The token's account is deactivated.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Chain not found (or not yours).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/urls/{urlId}/jsonld":{"get":{"operationId":"getUrlJsonLd","summary":"Get JSON-LD by URL id","description":"The generated JSON-LD document for one URL. Stale documents are still returned (`stale: true`) — old structured data beats none on a live site.","tags":["Content"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"urlId","in":"path","required":true,"description":"URL id from `/chains/{chainId}/urls`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The JSON-LD document.","content":{"application/json":{"schema":{"type":"object","properties":{"urlId":{"type":"string"},"chainId":{"type":"string"},"businessId":{"type":"string"},"url":{"type":"string"},"languageCode":{"type":"string"},"stale":{"description":"True when the source page changed after generation. The document is still usable; regenerate to refresh.","type":"boolean"},"generatedAt":{"type":"string"},"jsonLd":{"description":"The Schema.org JSON-LD document (object or array), ready to embed in a `<script type=\"application/ld+json\">` tag."}},"required":["urlId","chainId","businessId","url","languageCode","stale","generatedAt","jsonLd"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"The token's account is deactivated.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"URL not found (or not yours), or JSON-LD not generated yet.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/jsonld":{"get":{"operationId":"lookupJsonLd","summary":"Get JSON-LD by page URL","description":"Looks a page URL up directly — built for CMS plugins that only know the permalink of the page being rendered. Matching is exact plus a trailing-slash variant. If the same URL exists in more than one chain, the freshest artifact wins (non-stale first, then newest).","tags":["Content"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"description":"Absolute URL of the page, e.g. `https://example.com/services/`.","schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"The JSON-LD document.","content":{"application/json":{"schema":{"type":"object","properties":{"urlId":{"type":"string"},"chainId":{"type":"string"},"businessId":{"type":"string"},"url":{"type":"string"},"languageCode":{"type":"string"},"stale":{"description":"True when the source page changed after generation. The document is still usable; regenerate to refresh.","type":"boolean"},"generatedAt":{"type":"string"},"jsonLd":{"description":"The Schema.org JSON-LD document (object or array), ready to embed in a `<script type=\"application/ld+json\">` tag."}},"required":["urlId","chainId","businessId","url","languageCode","stale","generatedAt","jsonLd"],"additionalProperties":false}}}},"400":{"description":"Missing or invalid `url` query parameter.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"The token's account is deactivated.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"URL not found in your businesses, or JSON-LD not generated yet.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"details":{}},"required":["message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}}}}