https://api.getclean.ai, described by one OpenAPI 3.1 contract with 22 operations under /v1. Every request carries Authorization: Bearer <key>, and every record starts with what happened, as an outcome, instead of an HTTP status. Each operation’s page in this section is generated from the contract, so its parameters, examples and rules are the contract’s own words. The contract itself is openapi.yaml.
A request and its response
This request fetches a shop page that answers with a bot challenge instead of the page.201 Created, which is what every outcome of a fetch gets. The record below leaves out its source and execution fields; Fetch contents shows it in full.
outcome comes first. Its kind is one of delivered, partial, failed, refused or needs_person, its reason says why, and its message says what you can try next. A page that couldn’t be read is a record like any other, and you pay for what happened: cost.actual is zero here. A problem, sent as application/problem+json, only answers a request that getclean itself refuses, such as 401 unauthorized for a missing key or 422 invalid-field for a value outside its set. Records goes through a record field by field, Outcomes and notices lists every reason, and Errors lists every problem type.
The operations
The operations form two families, contents and search, plus one request that serves both,get_limits. The contents family takes one source, a web page or a document, by URL or as a file, and makes its record; every later question about that source is answered from the record for free. The search family runs one question, in up to twenty wordings, on up to ten sources at once, and returns one ranked list with the facts of each result and a receipt of what ran where, before any page is fetched. Each line below is the first sentence of that operation’s page.
Fetch and upload
Records
Working with a record
Search
Account
What every operation has in common
Headers you send
Headers you get back
Where the rules are
Records
What a record contains, how long it’s kept, and how to read it again for free.
Outcomes and notices
Every outcome reason and every notice code, with what you can try next.
Errors and retries
Every problem type, who has to act, the fix as data, and the idempotency key.
Costs and budgets
The ceiling, the five limits behind it, and what gets dropped when the money runs short.
Limits
The rate, the bounds of every field, the body sizes and the key’s policy.
Repeatable output and model steps
What repeats, what doesn’t, pinning a version, and how a retirement is announced.