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

# Typed extraction (text, number, date, list, estimate, forecast)

> Send text and/or up to 4 images plus a schema of typed fields — `text` (a span of the input), `number`, `date` / `time` / `datetime`, `duration`, `list`, `estimate` (a distribution over a range), `forecast` (per-step estimates) — and get a value, calibrated confidence and null probability for every field in one forward pass. No free-form text, no reasoning tokens; a field the input does not determine comes back null. Billed per input token under `clairic` (64K context); output tokens are free.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/extractions
openapi: 3.0.3
info:
  title: AI Reserve Gateway API
  description: >-
    The AI Reserve API surface — OpenAI-compatible chat completions,
    Anthropic-compatible messages, Bedrock Converse, images, video, files,
    text-to-speech, realtime voice sessions, and provider-hidden GPU
    infrastructure — all behind one endpoint and one API key.
  version: 1.0.0
servers:
  - url: https://api.aireserve.com
security:
  - bearerAuth: []
tags:
  - name: Customers
    description: >-
      Per-end-customer usage, cost, and billable amounts for organizations that
      tag requests with their own customers.
  - name: GPU Infrastructure
    description: >-
      Provision and manage provider-hidden GPU instances. The recommended
      Instances API accepts workload requirements and an hourly price ceiling;
      AI Reserve handles provider placement internally. Every mutation is
      asynchronous and returns an operation to poll.
  - name: Customer keys
    description: >-
      Mint, list, and revoke API keys pinned to your own end customers (and
      their organizations), so spend splits per customer without per-request
      tagging.
paths:
  /v1/extractions:
    post:
      tags:
        - Extractions
      summary: Typed extraction (text, number, date, list, estimate, forecast)
      description: >-
        Send text and/or up to 4 images plus a schema of typed fields — `text`
        (a span of the input), `number`, `date` / `time` / `datetime`,
        `duration`, `list`, `estimate` (a distribution over a range), `forecast`
        (per-step estimates) — and get a value, calibrated confidence and null
        probability for every field in one forward pass. No free-form text, no
        reasoning tokens; a field the input does not determine comes back null.
        Billed per input token under `clairic` (64K context); output tokens are
        free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
              required:
                - model
                - fields
              properties:
                model:
                  description: 'Extraction model: `clairic` (64K context, text + images).'
                  type: string
                  enum:
                    - clairic
                state:
                  description: >-
                    The text to read and extract from. Text answers are
                    character spans of this string. Required unless `images` is
                    sent. Long text is truncated upstream to fit the model's
                    context (`truncated: true` in the response).
                  type: string
                fields:
                  minProperties: 1
                  maxProperties: 256
                  description: >-
                    Map of field name → typed field spec; 1 to 256 fields.
                    Answers come back under the same names. Fields that do not
                    fit next to the state in one pass are split across parallel
                    passes upstream.
                  type: object
                  additionalProperties:
                    additionalProperties: true
                    type: object
                    required:
                      - type
                    properties:
                      type:
                        description: >-
                          `text` (a span of the state), `number`, `date`,
                          `time`, `datetime`, `duration`, `list`, `estimate`
                          (distribution over `min`..`max`) or `forecast`
                          (per-step estimates over `horizon`).
                        anyOf:
                          - type: string
                            enum:
                              - text
                          - type: string
                            enum:
                              - number
                          - type: string
                            enum:
                              - date
                          - type: string
                            enum:
                              - time
                          - type: string
                            enum:
                              - datetime
                          - type: string
                            enum:
                              - duration
                          - type: string
                            enum:
                              - list
                          - type: string
                            enum:
                              - estimate
                          - type: string
                            enum:
                              - forecast
                      instructions:
                        maxLength: 20000
                        description: >-
                          What the field should contain, plus any rule the model
                          should apply.
                        type: string
                images:
                  maxItems: 4
                  description: >-
                    Up to 4 embedded PNG / JPEG / WebP images placed before the
                    state, as `data:` URLs or `{content_type, base64}` objects
                    (4 MiB each, 8 MiB total decoded; remote URLs are not
                    accepted). Each image bills at most 4,096 input tokens.
                  type: array
                  items: {}
                reference_date:
                  maxLength: 40
                  description: ISO date that anchors dates written without a year.
                  type: string
                options:
                  additionalProperties: false
                  type: object
                  properties:
                    include_quantiles:
                      description: Add 99 percentiles to every estimate and forecast step.
                      type: boolean
                    return_state_text:
                      description: >-
                        Return the text that `span` offsets index into
                        (`state_text`).
                      type: boolean
      responses:
        '200':
          description: Default Response
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your AI Reserve API key (aireserve_api_…) from the API Keys page in the
        portal (https://portal.aireserve.com/keys).

````

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