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

# Create extraction

> Extract typed fields from text or images

<Note>
**Preview.** The `/alpha` path and the request and response formats may change before this API is marked stable. See [release stages](https://docs.inworld.ai/portal/support.md#what-do-experimental-preview-and-stable-mean).
</Note>

Send a `state`, optional images in `assets`, and a map of typed `fields` to the selected extraction model. It returns one answer per field: the value, the model's `confidence`, and the probability that the value is absent (`p_null`).

Find extraction models with the [List models API](https://docs.inworld.ai/api-reference/modelsAPI/modelservice/list-models.md) and `output_modalities=extractions`. The [Extractions guide](https://docs.inworld.ai/router/extractions.md) explains when to use this API instead of Decisions or structured outputs, and shows a complete image request. The reference examples use `inworld/models/clairic`.

## Images

Send each image in `assets` under a reference key, and write the key in `state` or in a field's `instructions` where the image belongs:

```json
{
  "state": "The supplier's invoice: invoice_scan",
  "assets": {
    "invoice_scan": { "format": "png", "data_base64": "<BASE64_IMAGE>" }
  }
}
```

This fragment illustrates `state` and `assets`; a complete request also requires `model` and `fields`.

| Field or constraint | Accepted values and behavior |
|:--|:--|
| `format` | `png`, `jpg`, `jpeg` or `webp`. `pdf` and `type: document` return `400`: render PDF pages to images first. |
| `data_base64` | Standard base64 of the image bytes, with no `data:` prefix. |
| Reference key | Must appear in `state` or in some field's `instructions` as a standalone token: a letter, digit, `_`, `.` or `-` directly before or after it makes it part of a longer word. An unreferenced asset returns `400`. |
| `state` | May be an empty string when the request carries images. |
| Count and size | Up to 4 images for `inworld/models/clairic`; other models can differ. A request that carries images must fit in 4 MiB (4,194,304 bytes), or it returns `413`. |
| Model | The model's `spec.inputModalities` must include `image`. |

With images, a `text` answer's `span` can index `state` with the reference keys removed. Set `options.return_state_text` to `true` to get the text that `span` positions refer to, as `state_text`.

## Errors

Request validation returns `400` with `error.type: "invalid_request_error"` before the request reaches a model. For field and asset validation, `error.param` names the member to fix. Other errors can omit `param`.

For example, `"fields": {"total": {"type": "money"}}` returns:

```json
{
  "error": {
    "message": "fields.total.type: unknown field type \"money\"; expected text, number, date, time, datetime, duration, list, estimate or forecast",
    "type": "invalid_request_error",
    "param": "fields.total.type"
  }
}
```

Errors from the model keep their HTTP status and use `{"error": {"message": "...", "type": "..."}}`: `rate_limit_error` for `429`, `timeout_error` for `504` and `api_error` for other `5xx` errors. When Inworld can't reach the model, the `502` uses `upstream_error`. Retry transient errors with exponential backoff and honor `Retry-After` when present.

Check the HTTP status and content type before parsing: errors for authentication, credits and your account's [rate limit](https://docs.inworld.ai/resources/rate-limits.md#inference-api-limits) use a different body. `401` and `429` are plain text, and `402` has a numeric `error.code`. See [Errors in the Extractions guide](https://docs.inworld.ai/router/extractions.md#errors) for every status and what to do.

## API reference

**Endpoint:** `POST https://api.inworld.ai/alpha/extractions`

### Authorization

- `Authorization` (string; required) — Your [authentication](../../../api-reference/introduction) credentials. For Basic authentication, please populate `Basic $INWORLD_API_KEY`.
  
  A standard API key can call chat completions, the Responses and Messages APIs, moderation and Decisions. To create, update or delete routers, the key also needs [write permissions for the Router API](https://docs.inworld.ai/portal/api-keys.md#key-permissions). You can create a key in one command with the [Inworld CLI](../../../developer-tools/inworld-cli): `inworld workspace add-key`.

### Request body

Content type: `application/json`

- `model` (string; required) — An extraction model: the `id` from the List models API with `output_modalities=extractions`, for example `inworld/models/clairic`. Chat and decision models are refused.
- `state` (string; required) — The text to read. Write each asset's reference key where its image belongs. May be an empty string only when the request carries images. Input longer than the model's `spec.contextLength` is cut, and the response has `truncated: true`.
- `fields` (object; required) — The values to extract, keyed by names you choose. Each answer comes back under the same name. At least one field is required.
- `assets` (object) — Images to read, keyed by a reference key you choose. Each key must appear in `state` or in some field's `instructions` as a standalone token: a letter, digit, `_`, `.` or `-` directly before or after it makes it part of a longer word, and an asset referenced nowhere returns `400`. The model's `spec.inputModalities` must include `image`. `inworld/models/clairic` reads up to 4 images per request, and a request that carries images must fit in 4 MiB (4,194,304 bytes).
- `reference_date` (string) — The date the content was written, `YYYY-MM-DD`, used to resolve relative dates such as "yesterday" or "next Friday".
- `options` (object) — Optional extras in the response.
  - `include_quantiles` (boolean) — Return the full `quantiles` array on `estimate` answers.
  - `return_state_text` (boolean) — Return `state_text`, the text that `span` positions index. With images, it is `state` with the reference keys removed.

#### Request example

```json
{
  "model": "inworld/models/clairic",
  "state": "Invoice INV-20417 from Example Supply Co. Issued October 28, 2026. Payment terms: net 30. Total due: $712.26.",
  "fields": {
    "invoice_number": {
      "type": "text",
      "instructions": "The invoice number"
    },
    "total": {
      "type": "number",
      "instructions": "The total amount due",
      "unit": "USD",
      "decimals": 2
    },
    "due_date": {
      "type": "date",
      "instructions": "When payment is due"
    }
  }
}
```

### Response

Status: `200`. Content type: `application/json`.

- `model` (string) — The model that answered. It can be a shorter form of the `id` you sent, such as `inworld/clairic` for `inworld/models/clairic`.
- `answers` (object) — One answer per field, keyed by the names used in `fields`.
- `truncated` (boolean) — `true` when the input was longer than the model's context and was cut. A field near the end may then be missing or guessed.
- `state_text` (string) — Present when `options.return_state_text` is `true`: the text `span` positions index.
- `usage` (object) — Token usage. Extractions are billed on `input_tokens` only. `input_tokens` can exceed the sum of the parts, because the model can read the input more than once (`passes`).
  - `state_tokens` (integer)
  - `image_tokens` (integer)
  - `schema_tokens` (integer) — Tokens for your field definitions.
  - `input_tokens` (integer) — The billed count.
  - `output_tokens` (integer) — Always 0; output is not billed.
  - `passes` (integer) — How many times the model read the input.
- `metadata` (object) — Inworld request metadata, with the same keys as on chat completions.
  - `attempts` (object[])
    - `model` (string)
    - `status_code` (integer)
    - `duration_ms` (number)
    - `success` (boolean)
  - `generation_id` (string) — Unique identifier for this request.
  - `total_duration_ms` (integer) — Total request duration in milliseconds.

### Response examples

#### 200: default_response

```json
{
  "model": "inworld/clairic",
  "answers": {
    "invoice_number": {
      "type": "text",
      "value": "INV-20417",
      "guess": "INV-20417",
      "confidence": 1,
      "p_null": 0.00005,
      "span": [
        8,
        17
      ]
    },
    "total": {
      "type": "number",
      "value": 712.26,
      "guess": 712.26,
      "confidence": 0.99999,
      "p_null": 2e-8
    },
    "due_date": {
      "type": "date",
      "value": "2026-11-27",
      "guess": "2026-11-27",
      "confidence": 0.99994,
      "p_null": 0.0000026
    }
  },
  "truncated": false,
  "usage": {
    "state_tokens": 45,
    "image_tokens": 0,
    "schema_tokens": 272,
    "input_tokens": 362,
    "output_tokens": 0,
    "passes": 2
  },
  "metadata": {
    "attempts": [
      {
        "model": "inworld/clairic",
        "status_code": 200,
        "duration_ms": 209.9,
        "success": true
      }
    ],
    "generation_id": "41149c81-1125-4eb4-89a7-eb76c429af4a",
    "total_duration_ms": 210
  }
}
```

#### 400: default_response

```json
{
  "error": {
    "message": "fields.total.type: unknown field type \"money\"; expected text, number, date, time, datetime, duration, list, estimate or forecast",
    "type": "invalid_request_error",
    "param": "fields.total.type"
  }
}
```

#### 401: default_response

```json
"Unauthorized"
```

#### 402: default_response

```json
{
  "error": {
    "code": 7,
    "message": "You have no credits remaining. Please add credits to continue using the service.",
    "details": []
  }
}
```

#### 404: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 413: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 422: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 500: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 502: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 503: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 504: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

### Code examples

#### cURL

```bash
curl -X POST 'https://api.inworld.ai/alpha/extractions' \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "inworld/models/clairic",
    "state": "Invoice INV-20417 from Example Supply Co. Issued October 28, 2026. Payment terms: net 30. Total due: $712.26.",
    "fields": {
      "invoice_number": {"type": "text", "instructions": "The invoice number"},
      "total": {"type": "number", "instructions": "The total amount due", "unit": "USD", "decimals": 2},
      "due_date": {"type": "date", "instructions": "When payment is due"}
    }
  }'
```

#### Python

```python
import os
import requests

response = requests.post(
    "https://api.inworld.ai/alpha/extractions",
    headers={"Authorization": f"Basic {os.environ['INWORLD_API_KEY']}"},
    json={
        "model": "inworld/models/clairic",
        "state": "Invoice INV-20417 from Example Supply Co. Issued October 28, 2026. "
        "Payment terms: net 30. Total due: $712.26.",
        "fields": {
            "invoice_number": {"type": "text", "instructions": "The invoice number"},
            "total": {
                "type": "number",
                "instructions": "The total amount due",
                "unit": "USD",
                "decimals": 2,
            },
            "due_date": {"type": "date", "instructions": "When payment is due"},
        },
    },
    timeout=60,
)
response.raise_for_status()
for name, answer in response.json()["answers"].items():
    print(name, answer["value"], answer["confidence"])
```

#### JavaScript

```javascript
const response = await fetch('https://api.inworld.ai/alpha/extractions', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${process.env.INWORLD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'inworld/models/clairic',
    state:
      'Invoice INV-20417 from Example Supply Co. Issued October 28, 2026. Payment terms: net 30. Total due: $712.26.',
    fields: {
      invoice_number: { type: 'text', instructions: 'The invoice number' },
      total: { type: 'number', instructions: 'The total amount due', unit: 'USD', decimals: 2 },
      due_date: { type: 'date', instructions: 'When payment is due' },
    },
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const { answers } = await response.json();
for (const [name, answer] of Object.entries(answers)) console.log(name, answer.value, answer.confidence);
```
