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

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Extract values

> Extract typed values from text and images.

> [!WARNING]
>
> Extraction is in preview. Model availability depends on configured provider routes.

Extraction belongs to the Decisions family. Use decisions to choose among known
options; use extraction to return values such as an invoice number, date or total.

```typescript theme={null}
import { Phaseo } from "@phaseo/sdk";

const client = new Phaseo({ apiKey: process.env.PHASEO_API_KEY });
const result = await client.extractions.create({
  model: "cloudflare/clairic",
  input: "Invoice INV-2291: 4 pallets at $250 each, shipping $80.",
  fields: {
    invoice_number: { type: "text" },
    total: { type: "number", decimals: 2, instructions: "Total including shipping" },
  },
});
console.log(result.answers.total.value);
```

```python theme={null}
import os
from phaseo import Phaseo

client = Phaseo(api_key=os.environ["PHASEO_API_KEY"])
result = client.extractions.create({
    "model": "cloudflare/clairic",
    "input": "Invoice INV-2291: 4 pallets at $250 each, shipping $80.",
    "fields": {"total": {"type": "number", "decimals": 2,
                         "instructions": "Total including shipping"}},
})
print(result["answers"]["total"]["value"])
```

The examples require an active extraction model route. Check model availability
before sending requests. Python `AsyncPhaseo` also exposes
`await client.extractions.create(...)`.

## Field types

Supported types are `text`, `number`, `date`, `time`, `datetime`, `duration` and
`list`. Lists require `items: "text"`, `"number"` or `"date"`. Supply 1–64 fields
and at most 16,384 source characters. Field names start with a letter or underscore
and contain up to 64 letters, digits, underscores, dots or hyphens.

Numbers and durations support `integer` and `decimals` (0–6). Durations accept
`seconds`, `minutes`, `hours`, `days`, `weeks`, `months` or `years`. Set
`reference_date` when interpreting incomplete dates depends on a specific year.

Image inputs use `{ content_type, base64 }` objects: at most four PNG/JPEG/WebP
images, 4 MiB each and 8 MiB combined after decoding. The request limit is 16 MiB.
Remote URLs, PDFs, audio, video, estimates, forecasts and streaming are unsupported.

## Read answers

Read `answers[field_name].value`. A scalar value can be `null` when the source does
not determine it. `p_null` is the model's probability of an undetermined value;
`confidence` is a separate model-reported score. Lists provide confidence without
`p_null`. These scores do not guarantee correctness: choose review thresholds for
your workload. A valid empty list is different from a failed request.

`truncated: true` means the provider did not process all source input. Review or
resubmit shorter input before relying on completeness. Text offsets and raw guesses
are not exposed. Complex arithmetic should be performed in application code.

Usage reports aggregate `input_tokens` across provider passes. Output tokens are
zero. Use the gateway's returned pricing rather than estimating cost from source
length or multiplying usage by the number of fields.


## OpenAPI

````yaml openapi/v1/openapi.yaml POST /extractions
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: >-
    A gateway API for accessing various AI models with OpenAI-compatible
    endpoints.
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
    description: Global routing
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /extractions:
    post:
      tags:
        - Gateway
      summary: Extract typed values
      description: >-
        Extracts text, numbers, dates, times, durations and typed lists from
        text or embedded images. Returns typed values and model-reported
        uncertainty. Estimates, forecasts, streaming and remote image URLs are
        not supported.
      operationId: createExtraction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractionRequest'
      responses:
        '200':
          description: Typed extraction answers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionResponse'
components:
  schemas:
    ExtractionRequest:
      type: object
      additionalProperties: false
      required:
        - model
        - input
        - fields
      properties:
        model:
          type: string
          minLength: 1
          maxLength: 256
          description: Model ID with the extraction.extract capability.
        input:
          type: string
          maxLength: 16384
          description: Source text. May be empty when images are supplied.
        fields:
          type: object
          minProperties: 1
          maxProperties: 64
          description: Field names match ^[A-Za-z_][A-Za-z0-9_.-]{0,63}$.
          additionalProperties:
            $ref: '#/components/schemas/ExtractionField'
        images:
          type: array
          maxItems: 4
          description: >-
            Embedded PNG, JPEG or WebP images; 4 MiB each and 8 MiB combined
            decoded.
          items:
            $ref: '#/components/schemas/ExtractionImage'
        reference_date:
          type: string
          format: date
          description: Explicit date context for incomplete dates.
    ExtractionResponse:
      type: object
      required:
        - model
        - answers
        - truncated
        - usage
      properties:
        model:
          type: string
        answers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ExtractionAnswer'
        truncated:
          type: boolean
          description: Whether the provider truncated source input.
        usage:
          $ref: '#/components/schemas/ExtractionUsage'
    ExtractionField:
      oneOf:
        - $ref: '#/components/schemas/ExtractionTextField'
        - $ref: '#/components/schemas/ExtractionNumberField'
        - $ref: '#/components/schemas/ExtractionDateField'
        - $ref: '#/components/schemas/ExtractionTimeField'
        - $ref: '#/components/schemas/ExtractionDatetimeField'
        - $ref: '#/components/schemas/ExtractionDurationField'
        - $ref: '#/components/schemas/ExtractionListField'
    ExtractionImage:
      type: object
      additionalProperties: false
      required:
        - content_type
        - base64
      properties:
        content_type:
          type: string
          enum:
            - image/png
            - image/jpeg
            - image/webp
        base64:
          type: string
          maxLength: 5592408
          description: Base64-encoded image bytes, without a data URL prefix.
    ExtractionAnswer:
      oneOf:
        - $ref: '#/components/schemas/ExtractionStringAnswer'
        - $ref: '#/components/schemas/ExtractionNumberAnswer'
        - $ref: '#/components/schemas/ExtractionListAnswer'
    ExtractionUsage:
      type: object
      required:
        - input_tokens
        - output_tokens
        - total_tokens
      properties:
        input_tokens:
          type: integer
          minimum: 0
          description: Provider-reported aggregate input tokens across all passes.
        output_tokens:
          type: integer
          enum:
            - 0
        total_tokens:
          type: integer
          minimum: 0
    ExtractionTextField:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - text
        instructions:
          type: string
          maxLength: 2048
    ExtractionNumberField:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - number
        instructions:
          type: string
          maxLength: 2048
        integer:
          type: boolean
        decimals:
          type: integer
          minimum: 0
          maximum: 6
        unit:
          type: string
          maxLength: 64
    ExtractionDateField:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - date
        instructions:
          type: string
          maxLength: 2048
    ExtractionTimeField:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - time
        instructions:
          type: string
          maxLength: 2048
    ExtractionDatetimeField:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - datetime
        instructions:
          type: string
          maxLength: 2048
    ExtractionDurationField:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - duration
        instructions:
          type: string
          maxLength: 2048
        integer:
          type: boolean
        decimals:
          type: integer
          minimum: 0
          maximum: 6
        unit:
          type: string
          enum:
            - seconds
            - minutes
            - hours
            - days
            - weeks
            - months
            - years
    ExtractionListField:
      type: object
      additionalProperties: false
      required:
        - type
        - items
      properties:
        type:
          type: string
          enum:
            - list
        instructions:
          type: string
          maxLength: 2048
        items:
          type: string
          enum:
            - text
            - number
            - date
        decimals:
          type: integer
          minimum: 0
          maximum: 6
    ExtractionStringAnswer:
      type: object
      required:
        - type
        - value
        - confidence
        - p_null
      properties:
        type:
          type: string
          enum:
            - text
            - date
            - time
            - datetime
        value:
          type: string
          description: Extracted text or ISO date/time, or null when undetermined.
          nullable: true
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: Model-reported confidence; not a guarantee of correctness.
        p_null:
          type: number
          minimum: 0
          maximum: 1
          description: Probability that the value is undetermined.
    ExtractionNumberAnswer:
      type: object
      required:
        - type
        - value
        - confidence
        - p_null
      properties:
        type:
          type: string
          enum:
            - number
            - duration
        value:
          type: number
          nullable: true
        confidence:
          type: number
          minimum: 0
          maximum: 1
        p_null:
          type: number
          minimum: 0
          maximum: 1
    ExtractionListAnswer:
      type: object
      required:
        - type
        - value
        - confidence
      properties:
        type:
          type: string
          enum:
            - list
        value:
          type: array
          maxItems: 4096
          items:
            oneOf:
              - type: string
              - type: number
        confidence:
          type: number
          minimum: 0
          maximum: 1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication

````

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