Skip to main content
The getclean API is a single HTTPS API at 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.
The response is 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

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.