For agents
Where the machine-readable versions of these docs live, and the rules an agent needs before calling the API on someone's behalf.
These docs are written for agents as well as people. The same rules appear in three places so an agent gets them whichever way it arrives.
Machine-readable entry points
| Resource | URL |
|---|---|
| Page index | /llms.txt |
| Every page, concatenated | /llms-full.txt |
| Any page as Markdown | append .md to its path, for example /docs/quickstart.md, or send Accept: text/markdown |
| The contract | https://api.ongoing.ai/v1/openapi.json |
Operation notes in the contract
Every operation in the OpenAPI document carries three vendor extensions:
| Extension | Content |
|---|---|
x-scope | The scope the key needs, or any / none. |
x-billing-unit | The unit a successful call consumes, or free. |
x-agent-notes | When to call it, what it costs, side effects, and how to read the result correctly. |
The MCP server (later release) builds its tool descriptions from x-agent-notes, so the tool an agent sees and the page a person reads are the same text.
Rules that prevent wrong conclusions
- A
404orno_matchmeans no profile was returned; it does not say why. Readreasonfirst.not_in_corpusis missing coverage, and offering an observation (refresh: true, needswrite:scans) is the right response.not_ecommerceis the one case that is a statement about the site: we observed it and classified it as not a store. Never report either as "this is not a store" without naming which one it was. - A technology missing from
technologieswas not seen within what that observation covered. Only atechnology_removedsignal or aninstall_stateofinactiveis a confirmed removal, and both require three consecutive comparable misses. Do not report a single absence as a vendor being dropped. last_observed_at-style fields describe the observation, not the change.effective_aton a signal is the estimate of when the change happened.staleresults are complete and billed. Do not discard them; report the observation date.- Every
POSTyou might retry needs anIdempotency-Keyderived from a stable identifier, or a timeout can bill twice. - Read
GET /v1/accountbefore a bulk run and keep withinplan.limits; compareperiod.includedagainstperiod.usedbefore spending. - Quote
request_idwhen reporting a failure to a person.
Test the rules
The acceptance test for these docs is a fresh agent session with a test key that completes: validate the key, read one store, enrich a batch, explain a no_match correctly, and recover from a 403 forbidden_scope by naming the missing scope. If any step needs information that is not in llms-full.txt or the contract, that is a documentation bug; report it.