> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getclean.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> getclean's own MCP server is at https://mcp.getclean.ai/mcp. The /mcp path of this docs site is Mintlify's search over these pages, not getclean.
> Every answer of the API opens with outcome. A page that could not be read is a record whose outcome says why, never an HTTP error; read outcome before anything else.
> The API's contract is the OpenAPI 3.1 file at https://docs.getclean.ai/openapi.yaml; the SDKs are generated from it.
> The product's name is written getclean, in lower case.

# Fill your fields, each with the words it came from

> Send your own fields as a JSON Schema and get them filled from a source. A value comes only where the source states it, with the words it was taken from. An empty field says why it is empty.

An analyst fills one template from 300 sustainability reports. The worst thing a tool can do is put a plausible number in a cell that the report never stated. `fill_schema` fills a field only where the source states the value, returns the words the value came from, and tells an empty field apart from a part of the source that was not read.

A model does this work, and the response says so. What the model can return is bound to the source: each value comes with its words and its place.

## Send your fields

Describe the fields as a JSON Schema whose root is an object. Send it with the id of a record, which is the copy of a source that getclean stores after a fetch or an upload. This request sends a template of 6 fields for a company's quarterly report.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/contents/CONTENTS_ID:fill \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "json_schema": {
      "type": "object",
      "properties": {
        "revenue": { "type": "string", "description": "Revenue of the period, with its currency" },
        "revenue_growth": {
          "type": "string",
          "description": "Growth of revenue against the same period a year before"
        },
        "operating_margin": { "type": "string" },
        "dividend_per_share": { "type": "string" },
        "guidance": {
          "type": "string",
          "description": "What the company expects for the next period"
        },
        "auditor": { "type": "string", "description": "The firm that audited the statements" }
      }
    }
  }'
```

```python Python theme={"theme":"css-variables"}
from getclean import GetClean

client = GetClean()

filled = client.fill_schema(
    contents_id="CONTENTS_ID",
    json_schema={
        "type": "object",
        "properties": {
            "revenue": {"type": "string", "description": "Revenue of the period, with its currency"},
            "revenue_growth": {
                "type": "string",
                "description": "Growth of revenue against the same period a year before",
            },
            "operating_margin": {"type": "string"},
            "dividend_per_share": {"type": "string"},
            "guidance": {"type": "string", "description": "What the company expects for the next period"},
            "auditor": {"type": "string", "description": "The firm that audited the statements"},
        },
    },
)
```

```typescript TypeScript theme={"theme":"css-variables"}
import { GetClean } from "getclean";

const client = new GetClean();

const filled = await client.fillSchema("CONTENTS_ID", {
    json_schema: {
        type: "object",
        properties: {
            revenue: { type: "string", description: "Revenue of the period, with its currency" },
            revenue_growth: {
                type: "string",
                description: "Growth of revenue against the same period a year before",
            },
            operating_margin: { type: "string" },
            dividend_per_share: { type: "string" },
            guidance: { type: "string", description: "What the company expects for the next period" },
            auditor: { type: "string", description: "The firm that audited the statements" },
        },
    },
});
```

Replace `CONTENTS_ID` with the id of a record.

## Read each value with its words

The response has the values in the shape of your schema, and beside them one status for each field. This response is cut to those 2 parts.

```json 200 OK theme={"theme":"css-variables"}
{
  "schema_values": {
    "revenue": "EUR 4.1 bn",
    "revenue_growth": "12%",
    "guidance": "raised"
  },
  "schema_statuses": {
    "/revenue":            { "status": "found", "text": "Revenue rose 12% to EUR 4.1 bn" },
    "/revenue_growth":     { "status": "found", "text": "Revenue rose 12% to EUR 4.1 bn" },
    "/guidance":           { "status": "found", "text": "guidance was raised" },
    "/operating_margin":   { "status": "empty", "text": "Operating margin: to be reported with the annual results" },
    "/dividend_per_share": { "status": "absent" },
    "/auditor":            { "status": "unread" }
  }
}
```

Of the 6 fields, 3 are filled, and `text` has the words of the source that each was taken from. A status also says where those words are: the section and the block, on a document the page, and inside a table the row and the column. A reviewer can open each cell of your template at its place in the source.

The other 3 fields are not in `schema_values` at all, and each says why. The report shows the operating margin without a value. It says nothing about a dividend. And the auditor could be named in a part of the document that was not read. No plausible value was put into any of them.

## Know why a field is empty

A status says which of 5 things happened.

| `status` | What it means |
| - | - |
| `found` | The source states the value. |
| `empty` | The source shows the field and gives it no value. |
| `absent` | The part of the source that was read says nothing about it. |
| `unread` | The value could be in a part that was not read: a page that failed, a scan read with low confidence, or a part past a size limit. |
| `failed` | The model could not fill the field. |

The difference between `absent` and `unread` decides what a report can say. "The company does not disclose its scope 3 emissions" is a finding, and it rests on `absent`. With `unread` it would be a guess, because the pages where the figure could be were not read.

A field that is `absent` on a web page can still be on the page, outside its main content. If the record's `left_out` is not empty, fill the schema again with `scope` set to `whole_page`.

## Fill the fields while you fetch

`fetch_contents` and `upload_contents` take the same `json_schema`, so one call can fetch a source and fill your fields. A search takes it for the results that it fetches, in `contents.json_schema`, so one search can return a filled row for each of its first results.

## Check what a fill costs

A fill costs one model step. The key needs the scope `contents:model`. A request that sends `deterministic_only` as `true` cannot ask for a fill, because a fill is the work of a model.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.