Fill schema
Fill your JSON Schema from a record you already have. You get a value only where the record states it, never a plausible one, with the place and the cited words for each property, and empty, absent or unread where the record says nothing. It is the same step as fetch_contents’s json_schema, run on the copy getclean keeps.
What it costs
The key needscontents:model. The price is 1 model_steps. The answer is 200 with SchemaFill; the call moves the record’s expires_at 48 hours ahead.
The idempotency key
Idempotency-Key is optional here. The billed answer is stored 24 hours and replayed under the same key and body with this call’s request_id and replayed true on cost; the same key in flight is 409 idempotency-key-in-flight; the same key with another body 422 idempotency-key-reused.
The fill
schema_statuses is keyed by JSON Pointer, one per property, with text the cited words and the place. absent means the content kept under scope says nothing; unread means the place may lie in parts not parsed, not recognized or past a cap, so absence cannot be claimed; an agent that meets absent beside a non-empty left_out may retry under scope: whole_page. schema_values carries no link and no image markup; a URL value is kept only when it stands in the record’s links or text, otherwise removed with the notice model_link_removed. The step is the whole call: a step that gave a bad answer is 502 gateway-error, a step that passed bounds.contents.model_step_seconds is 504 gateway-timeout, each retryable true and not billed. scope: whole_page on a document record, or block_kinds that match no block, is the notice field_not_applicable; with no block to read every status is absent and the step is not billed.
Refused before any work
json_schema missing: invalid-field, required. A schema that is not valid JSON Schema 2020-12: syntax; one whose root is not type: object, that has no properties, or whose pattern needs backtracking: not_allowed. A value outside its set: not_allowed; a bound passed: bound; an unknown field: unknown_field. A key whose policy forbids model work, or whose cap is below a model step: 403 policy-limit-exceeded. A record that failed, was refused or needs a person: 409 record-without-content. Every violation of the body is reported at once in violations.
Notices this operation makes
The record’s own notices first, thenmodel_link_removed, field_not_applicable, version_retiring.
Problem types
- 400
invalid-request, The request is invalid. - 401
unauthorized, The key is missing or rejected. - 403
insufficient-scope, The key lacks a scope this call needs;policy-limit-exceeded, The key’s policy forbids this;credit-exhausted, The credit is exhausted;run-budget-exhausted, The run’s budget is exhausted;key-budget-exhausted, The key’s budget is exhausted. - 404
not-found, Not found. - 409
record-without-content, The record has no content;idempotency-key-in-flight, The same request is still running. - 410
contents-expired, The record has expired. - 413
body-too-large, The body is too large. - 415
unsupported-media-type, The media type is not supported. - 422
invalid-field, A field is invalid;idempotency-key-reused, The idempotency key was reused with another body. - 429
rate-limit-exceeded, The rate limit is exceeded;concurrency-limit-exceeded, Too many calls are in flight. - 500
internal-error, The service failed. - 502
gateway-error, A step behind the service failed: the model step gave a bad answer; nothing was billed, and a retry may work. - 503
overloaded, The service is overloaded. - 504
gateway-timeout, A step behind the service timed out: the model step passed its time bound; nothing was billed, and a retry may work.
Authorizations
An API key from https://app.getclean.ai, or an access token issued by https://auth.getclean.ai/realms/getclean, sent as Authorization: Bearer <key> on every call. The scopes a key carries and what a 401 and a 403 say are on the keys and sign-in page.
Headers
One key per logical call, so a retry is never billed twice.
Optional on this operation; required on upload_contents, fetch_contents_batch and search_batch, where a duplicate would cost the most. The SDKs fill a fresh key when you give none and send the same key on every retry of that call; the command line and the MCP server do the same. Give your own key when your program retries across processes, so the second run finds the first answer.
The form: 1 to 255 visible ASCII characters, used exactly as sent, so a value written as a quoted Structured Field String keeps its quotes as part of the key. That is a stated departure from the IETF draft draft-ietf-httpapi-idempotency-key-header, revision 08, which is not yet a standard; this parameter documents the form in full.
What a repeated key does:
- The same key with the same body returns the first answer again, with this call's
request_id,expires_atas it stands andreplayedtrue on everycost. Nothing is billed again. - The same key while the first call still runs:
409 idempotency-key-in-flight, withRetry-After. - The same key with another body:
422 idempotency-key-reused.
Answers are stored for 24 hours, per account, for billed answers and running jobs only; a free answer is not stored. A call that may bill is kept in the store from its start, so a second call with its key meets the 409 while it runs.
1 - 255^[!-~]{1,255}$Your own trace id for the call, the W3C Trace Context traceparent header, optional on every operation. getclean logs it with the call, so a request in your traces can be matched to its Request-Id, and never forwards it to a site or a source, a stated departure from W3C Trace Context section 3.4, which asks a vendor to pass it on. A malformed value is ignored, never refused, as the same recommendation asks.
Body
The request of fill_schema. Every field is at the top level; an explicit null equals an absent field and gets the default. The object is closed; an unknown field is refused invalid-field, unknown_field.
Read only these blocks, 1 to 10 of text, heading, code, math, divider, interactive, table, image, embed, media; an open set. Default: every kind. When none matches, the notice field_not_applicable and every status absent.
1 - 10 elementsOne of the block kinds the field lists.
1Response
The values filled, one status per property with its place and cited words, the execution and the cost.
The answer of fill_schema: the record's id and facts, its new expires_at, the values filled, one status per property, the execution and the cost.