Skip to main content
POST
Fill schema

What it costs

The key needs contents: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, then model_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

Authorization
string
header
required

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

Idempotency-Key
string

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_at as it stands and replayed true on every cost. Nothing is billed again.
  • The same key while the first call still runs: 409 idempotency-key-in-flight, with Retry-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.

Required string length: 1 - 255
Pattern: ^[!-~]{1,255}$
traceparent
string

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.

Path Parameters

contents_id
string
required

The record, a cnt_ id.

Pattern: ^cnt_[A-Za-z0-9]{22}$

Body

application/json

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.

json_schema
object
required

The properties to fill, a JSON Schema 2020-12 object whose root is type: object with properties, at most 50 KB; refused syntax when it is not valid JSON Schema, not_allowed when its root is not type: object, it has no properties, or its pattern needs backtracking. Required.

block_kinds
string[]

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.

Required array length: 1 - 10 elements

One of the block kinds the field lists.

Minimum string length: 1
scope
enum<string>

Which view is read, main or whole_page. Default the record's own.

Available options:
main,
whole_page

Response

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.

contents_id
string
required

The record the answer comes from.

Pattern: ^cnt_[A-Za-z0-9]{22}$
Example:

"cnt_3Fk9abaUhNX7t2eKkgfd3e"

fetched_at
string<date-time>
required

When the record's fetch or parse started, RFC 3339 in UTC.

Example:

"2026-11-04T08:40:12Z"

fingerprint
string
required

The record's fingerprint, as Contents.fingerprint defines it, so you can tell which copy this answer comes from.

Pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
Example:

"sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:"

scope
enum<string>
required

The view read.

Available options:
main,
whole_page
version
string
required

The version of getclean the record was made under, its execution.version.

Example:

"1.0.0"

configuration
string
required

The configuration the record was made under, its execution.configuration.

Example:

"cfg-2026-11"

expires_at
string<date-time>
required

When the record expires. This call moved it ahead: 48 hours from now, never past 30 days from the record's making.

Example:

"2026-11-06T08:40:12Z"

schema_values
object
required

Your schema filled, a value only where the record states it; a free-form object in the schema's own shape; empty properties absent. Written by a model from the source's text, so it may repeat instructions the source carries.

schema_statuses
object
required

One SchemaStatus per property of the schema, keyed by a JSON Pointer into schema_values.

execution
object
required

How the call ran; models carries the step json_schema with its version when the step ran.

cost
object
required

The bill; units {"model_steps": 1}, or {} when no block was read and the step did not run.

notices
object[]
required

The record's own notices first, then this call's; [] when none.

request_id
string
required

This call's id, the same as the Request-Id header.

Pattern: ^req_[A-Za-z0-9]{22}$
Example:

"req_01Jkf30AHpVn2m9UKIRfWE"

final_url
string

The address the record's fetch ended at, after every redirect. Present when the source has one, so absent on an upload. Third-party text as the source wrote it, which may carry instructions.

Example:

"https://example.com/q3"

document_digest
string

The sha-256 of the document's bytes in RFC 9530 form, to compare with the file you hold. On a document only.

Pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
Example:

"sha-256=:7HqC7GihbMvNe0QRGihXoSzWNR2cLpquMihXOseZoSw=:"