Documentation

API reference

The public routes a running install actually calls. Admin and internal-operations routes are out of scope for this page.

Base URL and versioning#

Production: https://seogence.com. The JSON API is at contract v1 and its responses carry X-AutoSchema-Api-Version: v1. The Knowledge Layer routes below serve Markdown directly and do not carry that header.

Authentication model#

Public requests are scoped by a capability token bound to a specific hostname, issued alongside your install line. There is nothing hidden in the mechanism itself: the snippet format and endpoint shapes are intentionally observable. Abuse resistance comes from scoped capabilities, hostname binding, and rotation — not from keeping the request format secret.

Schema generation#

Route What it does

POST /api/generate-schema Triggers a (re)read of a URL — send just the URL and identifier. Seogence renders the page itself and generates schema from what it sees; page-content fields from older snippets are still accepted but never used for authoring. Returns CACHE_HIT or GENERATED with the schema, its Markdown copy and the content hash — GENERATION_IN_PROGRESS, which carries only retryAfterMs and no schema — or THIN_CONTENT (422, non-retryable) when the render is empty (parked page or un-hydrated app). markdown is null unless the copy-for-AI button is visible for the domain, which needs Markdown delivery on and the button switched on. markdownCopy.enabled carries that combined answer; markdownDelivery.enabled carries delivery on its own, which is what the crawler-facing <link> follows.

GET /api/schema?domainKey=&url= Reads back the stored schema for a URL. It never generates schema — though for a page that has never had a topic directory, it may start building one in the background.

Install and delivery#

Route What it does

GET /install/:domainKey The public install page with a copy-ready line for that domain.

GET /seogence.js?host=&propertyId=&token= Delivers the browser module. The install line is a plain <script async src> tag pointing here, so the browser fetches it directly — there is no separate loader step. A domain with no Property ID gets key= instead of propertyId=; domain and key remain accepted aliases. The body served is configured for the domain that requested it and starts itself on load; window.AutoSchemaModule.init(config) stays exported so lines pasted before this changed keep working.

Knowledge Layer#

Content-addressed Markdown, designed for crawlers that fetch raw HTML and do not execute JavaScript. Full contract, discovery mechanism, and honest limits: Knowledge Layer.

Route	What it does
`GET /KnowledgeLayer/:site/:contentHash.md`	The stored Markdown document for one captured page.
`GET /KnowledgeLayer/:site/by-url?u=`	Resolves a live page URL to its Markdown without knowing the content hash.
`GET /KnowledgeLayer/:site/llms.txt`	The domain’s discovery index — every known page, linked as Markdown.
`GET /KnowledgeLayer/:site/organization.md`	A typed Markdown statement of who is behind the site.

:site is your domain — /KnowledgeLayer/yoursite.com/llms.txt. The older form, your Seogence site key, still works on every route and always will, so anything already pasted or indexed keeps resolving.

All four accept HEAD for existence checks, and are gated by the domain’s Markdown delivery toggle — disabled domains return 404. The by-url resolver returns 406 when the request’s Accept header explicitly excludes Markdown.

You can build the by-url address yourself from any page URL. Spellings that differ only by www, a trailing slash, http against https, host capitalisation or a tracking parameter all reach the same document. A different query string or a hash route is a different page and resolves separately.

A request with no u, or a u that is not a full web address, returns 400 — the fault is in the request, not a missing page. When a site publishes a Knowledge Layer but has nothing stored for that page, the 404 carries X-Knowledge-Layer-Reason: no-artifact and names the index. Every other refusal is a plain 404 with nothing added, so the endpoint cannot be used to find out who our customers are.

A URL that only carries application state is not a page. If it still has a query string once tracking parameters are stripped, and the site’s own sitemap never declared it, it stays out of the index and returns 404 here. That keeps whatever a visitor typed into a search or filter box out of your published Knowledge Layer. Parameterised pages you do want read belong in your sitemap.xml.

Errors worth handling#

Status / code	Means
`429 RATE_LIMITED`	Back off and retry. Per-domain daily and burst limits apply; exact thresholds are not published.
`503 INJECTOR_DISABLED`	Schema delivery is switched off globally. Not retryable by the client.
`PAGE_QUOTA_EXCEEDED`	The account’s page allowance is used up; new pages are not added. A new page is refused before it is rendered.
`403 ROBOTS_DISALLOWED`	The site’s robots.txt asks crawlers like ours not to read the page, and we have not yet seen the install line in the site’s own HTML. Once we have, the site is read regardless: it invited us.
`503 ROBOTS_UNAVAILABLE`	The site’s robots.txt could not be read. That is not permission, so the page was not read. Retry after about ten minutes.
`422 THIN_CONTENT`	The render saw an essentially empty page — a parked domain, or an app shell that did not hydrate. Nothing is stored. Not retryable: waiting will not give an empty page content. The page is not rendered again for six hours.
`503 GENERATION_UNAVAILABLE`	The AI provider refused the request: out of credits, or rate-limited. No schema is generated, though the page snapshot may already be saved. The embed does not retry it within that page view. After an out-of-credits refusal, pages with no stored schema are refused for a few minutes without a render. A page whose generation failed gets this answer for six hours, without a render.

Keyword component and Markdown delivery policy#

A signed-in domain owner reads and writes their own page-scoped topic directory and their Markdown delivery toggle through customer-session routes under /api/customer/domains/:domainKey/…. These require an authenticated customer session scoped to the calling domain and are not documented further here — they are dashboard-driven settings, not integration surface.