---
title: "Extract"
method: POST
path: "/v1/extract/{model}"
tags: ["extract"]
---

# Extract

`POST /v1/extract/{model}`

Extract entities or structured data from items.

Supports both msgpack and JSON request bodies (Content-Type header).
Returns msgpack by default, JSON if Accept header requests it.

Args:
    model: Model name to use for extraction.
    http_request: FastAPI request object (for body and app state).
    accept: Accept header for response content negotiation.
    x_machine_profile: Machine profile header for routing validation.

Returns:
    ExtractResponse with extraction results for each item.
    Format depends on Accept header: msgpack (default) or JSON.

Raises:
    HTTPException: 400 for invalid input or profile mismatch, 404 if model not found,
        503 if not loaded.

## Path parameters

- `model` string, required

## Headers

- `accept` string, nullable
- `X-SIE-MACHINE-PROFILE` string, nullable

## Request body

- ExtractRequestModel — Request body for extract endpoint.
  - `items` ItemModel[], required — Items to extract from
    - `id` string, nullable — Optional identifier for this item. Returned in response.
    - `text` string, nullable — Text content to encode
    - `images` ImageInputModel[], nullable — Images for multimodal models
      - `data` string, byte, required — Image data. Base64-encoded on the JSON path; native binary on the msgpack path.
      - `format` string, nullable — Image format hint: 'jpeg', 'png', etc.
    - `audio` AudioInputModel — Audio input for audio models.
      - `data` string, byte, required — Audio data. Base64-encoded on the JSON path; native binary on the msgpack path.
      - `format` string, nullable — Audio format: 'wav', 'mp3', etc.
      - `sample_rate` integer, nullable — Sample rate in Hz. Must be positive.
    - `video` VideoInputModel — Video input for video models.
      - `data` string, byte, required — Video data. Base64-encoded on the JSON path; native binary on the msgpack path.
      - `format` string, nullable — Video format: 'mp4', 'webm', etc.
    - `document` DocumentInputModel — Document input for composite-document extractors (PDF, DOCX, HTML, ...).
      - `data` string, byte, required — Document bytes (raw file content). Base64-encoded on the JSON path; native binary on the msgpack path.
      - `format` string, nullable — Document format hint: 'pdf', 'docx', 'html', etc.
    - `metadata` object, nullable — Arbitrary metadata. Returned in response.
  - `params` ExtractParamsModel — Parameters for extract requests.
    - `labels` string[], nullable — Entity labels to extract
    - `output_schema` object, nullable — Schema for structured extraction
    - `instruction` string, nullable — Task instruction
    - `options` object, nullable — Adapter-specific options. Recognized sub-keys include 'overflow_policy' (one of 'default', 'truncate_text', 'error'; default 'default') controlling how inputs exceeding the model's max_sequence_length are handled.

## Response `200`

Extraction completed successfully

- ExtractResponseModel — Response from extract endpoint.
  - `model` string, required — Model used for extraction
  - `items` ExtractResultModel[], required — Extraction results for each input item
    - `id` string, required — Item ID
    - `entities` EntityModel[] — Extracted entities
      - `text` string, required — Entity text
      - `label` string, required — Entity label/type
      - `score` number, required — Confidence score
      - `start` integer, nullable — Start character offset
      - `end` integer, nullable — End character offset
      - `bbox` number[], nullable — Bounding box for document entities
    - `relations` RelationModel[] — Extracted relations
      - `head` string, required — Head entity text
      - `tail` string, required — Tail entity text
      - `relation` string, required — Relation type
      - `score` number, required — Confidence score
    - `classifications` ClassificationModel[] — Classification results
      - `label` string, required — Classification label
      - `score` number, required — Confidence score
    - `data` object — Structured extraction data
    - `error` ExtractItemErrorModel — Stable per-item extraction failure.
      - `code` string, required — Stable extraction error code
      - `message` string, required — Sanitized extraction error message
  - `usage` UsageModel — Authoritative worker-emitted usage. Post-tokenization counts, never a character estimate. A reported 0 is a measurement (a video-only encode reads no text); an absent block means the counts were unavailable on this path.
    - `input_tokens` integer, required — Post-truncation input tokens processed
    - `images` integer, nullable — Images processed across the request's items

## Other responses

- `400` — Invalid request
- `404` — Model not found
- `422` — Validation Error
- `502` — Terminal model-load failure (MODEL_LOAD_FAILED). Carried in the ``detail`` envelope: ``{code, message, error_class, permanent, attempts}``. No ``Retry-After`` header — clients MUST NOT auto-retry.
- `503` — Model not loaded or service unavailable

---

[API](https://skmtc.dev/superlinked/apis/sie-server.md) · [All operations](https://skmtc.dev/superlinked/apis/sie-server/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/superlinked/sie-server/revisions/26ac644915a4/schema)