Create Extraction

Run a structured extraction on a document.

Extracts structured data from the document according to the supplied json_schema, using the requested model. Returns the extraction with its output, consensus details, and usage on 201. When stream is true, partial results are streamed back as they are produced.

POST /v1/extractions

Python

from retab import Retab

client = Retab()

extraction = client.extractions.create(
    document="Invoice.pdf",
    json_schema="Invoice_schema.json",
    model="retab-small",
    n_consensus=1,
    metadata={"source": "docs"},
)

print(f"Extraction ID: {extraction.id}")
print(f"Filename: {extraction.file.filename}")
print(extraction.output)

200

{
  "id": "extr_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "Invoice.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "json_schema": {
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string" },
      "total": { "type": "number" }
    }
  },
  "n_consensus": 1,
  "image_resolution_dpi": 192,
  "output": {
    "invoice_number": "INV-2024-0042",
    "total": 1234.56
  },
  "consensus": {
    "choices": [],
    "likelihoods": {
      "invoice_number": 0.98,
      "total": 0.97
    }
  },
  "metadata": {
    "source": "docs"
  },
  "usage": {
    "prompt_tokens": 2760,
    "completion_tokens": 20,
    "total_tokens": 2780
  },
  "created_at": "2024-03-15T10:30:00Z"
}

Extract structured data from a document against a JSON schema and persist the result as an Extraction resource that can later be retrieved via GET /v1/extractions/{extraction_id} or listed via GET /v1/extractions.

Python

from retab import Retab

client = Retab()

extraction = client.extractions.create(
    document="Invoice.pdf",
    json_schema="Invoice_schema.json",
    model="retab-small",
    n_consensus=1,
    metadata={"source": "docs"},
)

print(f"Extraction ID: {extraction.id}")
print(f"Filename: {extraction.file.filename}")
print(extraction.output)

200

{
  "id": "extr_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "Invoice.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "json_schema": {
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string" },
      "total": { "type": "number" }
    }
  },
  "n_consensus": 1,
  "image_resolution_dpi": 192,
  "output": {
    "invoice_number": "INV-2024-0042",
    "total": 1234.56
  },
  "consensus": {
    "choices": [],
    "likelihoods": {
      "invoice_number": 0.98,
      "total": 0.97
    }
  },
  "metadata": {
    "source": "docs"
  },
  "usage": {
    "prompt_tokens": 2760,
    "completion_tokens": 20,
    "total_tokens": 2780
  },
  "created_at": "2024-03-15T10:30:00Z"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request to run a structured extraction on a single document.

Extends the base extraction request with the document to process (either inline content or a reference to a previously uploaded file) and a stream flag that controls whether results are returned incrementally.

document · MIMEData · object · required

A file represented by its filename and a base64 data url.

MIMEData

FileRef

Show child attributes

json_schema · Json Schema · object · required

JSON schema describing the structured output

model · string · default: retab-small

The model to use for the extraction

image_resolution_dpi · integer · default: 192

Resolution of the image sent to the LLM

instructions · string | null

Free-form instructions appended to the system prompt to steer the extraction.

n_consensus · integer · default: 1

Number of consensus extraction runs to perform. Uses deterministic single-pass when set to 1.

metadata · Metadata · object

User-defined metadata to associate with this extraction

Show child attributes

additional_messages · Additional Messages · object[] | null

Additional chat messages forwarded to the extraction model.

bust_cache · boolean · default: false

If true, skip the LLM cache and force a fresh completion

stream · boolean · default: false

background · boolean · default: false

If true, run asynchronously: returns immediately with status 'queued' and an empty output. Poll GET /v1//{id} until status is terminal. Mutually exclusive with stream.

chunking_keys · Chunking Keys · object

Show child attributes

Response

200

application/stream+json

Streaming extraction chunks