Call the Extract API

You've built a Request Schema Version, benchmarked it with manual and scheduled runs, and picked a model deployment you trust. Now you want your application to actually use it. That's POST /api/extract — bearer-authenticated, multipart, returns structured JSON.

The same Schema Version your benchmarks ran against is the one the API uses. What you measured is what production gets — no separate "production schema" to drift.

What you'll need

• A published Extraction API Key (the full key, copied at creation — only the last 4 characters are recoverable afterwards).
• The UUID of a published Request Schema Version. Open the version in the admin; the ID is in the URL after /request-schema-versions/.
• The UUID of a Model Deployment. Make sure a tenant LLM API key is assigned to it, or the call returns 400.
• A document to extract from — PDF is the supported path; other formats work to the extent the model deployment accepts them.

The endpoint at a glance

Request fields

Response shape (200 OK)

{
  "success": true,
  "data": {
    "effective_date": "2024-03-01",
    "renewal_term_months": 12,
    "is_contract": true
  },
  "usage": {
    "inputTokens": 4821,
    "outputTokens": 312,
    "totalTokens": 5133,
    "cachedInputTokens": 0
  },
  "cost": {
    "inputCost": 0.01446,
    "outputCost": 0.00468,
    "totalCost": 0.01914,
    "inputPricePerMillion": 3.0,
    "outputPricePerMillion": 15.0
  },
  "durationMs": 4218
}

data is the structured extraction keyed by the field names you defined on the schema version. usage, cost, and durationMs are diagnostic — useful for client-side logging, surface metrics, or showing your users what an extraction cost and how long it took.

The cost object

cost breaks the spend for the call into its parts, all in US dollars, computed from the token counts in usage and the deployment's configured per-million-token prices.

Walkthrough

1. 1. Mint and stash a bearer token

   Create an Extraction API Key — see Manage Extraction API Keys. Copy the full key the moment it's shown; after the create screen, only the last 4 characters are stored.

   Stash it in your application's secret manager (env var, AWS Secrets Manager, Vault — whatever you already use). Never check it into source.

2. 2. Grab the Schema Version and Model Deployment IDs

   Open the Request Schema Version you want production to use. The UUID is the last segment of the URL, after /admin/collections/request-schema-versions/.

   For the model deployment, open Browse Supported LLM Models. The deployment ID isn't shown directly in the table — open the underlying record from Model Deployments (Models → Model Deployments in the sidebar) to copy it, or pull it from a /api/model-deployments query if you're scripting setup.

3. 3. POST multipart/form-data

   curl:

   curl -X POST https://evals.thelibrari.com/api/extract \
     -H "Authorization: Bearer $LIBRARI_EXTRACT_KEY" \
     -F "file=@/path/to/contract.pdf" \
     -F "requestSchemaVersionId=20448b1b-87d1-4e99-b521-80360b676035" \
     -F "modelDeploymentId=9f7e3c4d-b8a2-4e1f-8c6d-2a5b9c4d3e7f"

   Python (requests):

   import os, requests
   
   with open("/path/to/contract.pdf", "rb") as f:
       resp = requests.post(
           "https://evals.thelibrari.com/api/extract",
           headers={"Authorization": f"Bearer {os.environ['LIBRARI_EXTRACT_KEY']}"},
           files={"file": ("contract.pdf", f, "application/pdf")},
           data={
               "requestSchemaVersionId": "20448b1b-87d1-4e99-b521-80360b676035",
               "modelDeploymentId": "9f7e3c4d-b8a2-4e1f-8c6d-2a5b9c4d3e7f",
           },
           timeout=120,
       )
   resp.raise_for_status()
   extraction = resp.json()["data"]

   TypeScript / Node 20+ (fetch + FormData):

   import { readFile } from "node:fs/promises"
   
   const fileBuf = await readFile("/path/to/contract.pdf")
   const form = new FormData()
   form.append("file", new Blob([fileBuf], { type: "application/pdf" }), "contract.pdf")
   form.append("requestSchemaVersionId", "20448b1b-87d1-4e99-b521-80360b676035")
   form.append("modelDeploymentId", "9f7e3c4d-b8a2-4e1f-8c6d-2a5b9c4d3e7f")
   
   const res = await fetch("https://evals.thelibrari.com/api/extract", {
     method: "POST",
     headers: { Authorization: `Bearer ${process.env.LIBRARI_EXTRACT_KEY!}` },
     body: form,
   })
   if (!res.ok) throw new Error(`Extract failed: ${res.status} ${await res.text()}`)
   const { data } = await res.json() as { data: Record<string, unknown> }

4. 4. Read the response

   Happy path:

   {
     "success": true,
     "data": { "...": "..." },
     "usage": { "inputTokens": 4821, "outputTokens": 312, "totalTokens": 5133, "cachedInputTokens": 0 },
     "cost": { "inputCost": 0.01446, "outputCost": 0.00468, "totalCost": 0.01914, "inputPricePerMillion": 3.0, "outputPricePerMillion": 15.0 },
     "durationMs": 4218
   }

   data is the only field most production code touches. cost.totalCost is per-call spend in US dollars — handy if you want to surface cost-per-extraction to your end users, or shed load when a customer is over quota. (If the deployment has no pricing configured, totalCost is 0 and the …PricePerMillion fields are null — check the price, not the cost, to detect that.)

Text-layer requirement

OCR and extraction are two separate calls. /api/extract never runs OCR — it only extracts. OCR (flattening a scan into a PDF with a selectable text layer) is its own endpoint: Apply OCR to a Document (POST /api/ocr).

If the Request Schema Version has Requires Text set and you upload a PDF, /api/extract first probes the PDF for a text layer:

• Has a text layer (born-digital PDF, or already OCRd) → extraction proceeds normally.
• No text layer (a raw scan), or the probe can't confirm one → the call is rejected with text_layer_required (HTTP 422) before the model is ever called. The model is never sent a scan it can't read.

When you get a text_layer_required back, the fix is a two-step flow:

1. POST /api/ocr with the scan → you get back the same PDF with a text layer applied.
2. POST /api/extract with the OCRd PDF → extraction proceeds.

One caveat: OCR can succeed and still find no text — a photo, a blank page, an illegible scan. The /api/ocr response tells you which case you're in via its X-Ocr-Has-Text-Layer header (it runs this same probe). If that header says false, resubmitting to /api/extract will just produce this 422 again — treat the document as unreadable instead.

This split lets you OCR once and reuse the flattened PDF across many extractions, and keeps OCR-service slowness or outages from being charged against — or confused with — your extraction calls. Schema versions that use Requires Vision (the model reads the page images directly) don't need a text layer and skip this check entirely.

How limit rejections are reported

"This document is too big" can be caught in two different places, and which one fires decides the shape you get back. Understanding the split is the key to handling size/page/format rejections cleanly.

Layer 1 — pre-flight, before the model is ever called. The API probes your file (page count, byte size, image dimensions and format) and checks it against the limits declared on the chosen Model Deployment. Any violation comes back as a single precheck_failed 400 that lists every failed limit at once. No provider round-trip, no token spend, fully deterministic. This only covers limits you've actually set on the deployment — a null limit is skipped.

Layer 2 — the provider's own rejection, echoed back. If a limit wasn't declared on the deployment (or can't be known until the model tokenises the input, like the context window), the document goes to the provider and the provider rejects it. The API catches that raw vendor error, parses it, and re-emits it in the same structured shape — translating each provider's idiosyncratic wording into a stable type (page_cap_exceeded, payload_too_large, context_overflow, images_per_request_exceeded) with typed numeric fields like pagesUsed / tokensLimit.

The practical consequence: the same physical limit can surface under two different type values. A PDF that's over the page cap returns precheck_failed if you set maxPages on the deployment, or page_cap_exceeded if you didn't and the provider caught it. Tell them apart by shape — precheck_failed carries a failures[] array and may list several problems together; the provider-echoed types are single-issue with their own numeric fields. Both are documented below.

Errors

The endpoint returns two different error shapes depending on where the failure happened.

Setup / auth errors — flat string

Returned for problems the API can detect before it ever calls the LLM provider: missing bearer token, missing required fields, wrong UUID, no provider key wired up. The body is { "error": "<message>" }.

Provider / extraction errors — structured object

Once the request reaches the LLM provider, any failure (rate limit, context overflow, bad credentials, timeout, …) comes back as a structured object so your client can branch on it without parsing prose:

{
  "error": {
    "type": "context_overflow",
    "status": 400,
    "retryable": false,
    "message": "Anthropic request failed (model=claude-haiku-4-5-20251001): 400 ... prompt is too long: 204004 tokens > 200000 maximum",
    "provider": "Anthropic",
    "providerStatus": 400,
    "tokensUsed": 204004,
    "tokensLimit": 200000
  }
}

The HTTP status matches error.status. Fields:

Pre-flight limit validation (type: "precheck_failed")

Before the document is sent to the LLM, the API checks it against every limit declared on the chosen Model Deployment. If anything is out of bounds, you get a precheck_failed response with every failed limit listed in one shot — no need to fix-and-retry one at a time:

{
  "error": {
    "type": "precheck_failed",
    "status": 400,
    "retryable": false,
    "message": "Document violates 2 model-deployment limit(s); see failures for details.",
    "failures": [
      {
        "limit": "maxPages",
        "observed": 250,
        "allowed": 100,
        "unit": "pages",
        "message": "PDF has 250 pages; this deployment caps PDF input at 100 pages per request."
      },
      {
        "limit": "maxRequestPayloadMb",
        "observed": 38.4,
        "allowed": 32,
        "unit": "MB",
        "message": "Uploaded file is 38.4 MB; this deployment caps a single request payload at 32 MB."
      }
    ]
  }
}

Each entry in failures has the same shape:

Limits enforced before the LLM call:

Not pre-flight-checked (relies on the provider's own error to surface): contextWindowTokens, maxTokens, and the multi-doc variants of maxImagesPerRequest / maxDocumentsPerRequest (this endpoint only takes one file). If the document slips past pre-flight but blows the model's context window, you'll get the normal context_overflow error instead.

If the deployment has a limit set to null, that limit is skipped — pre-flight only enforces what the catalog explicitly declares.

Error types

A minimal client-side retry rule — branch on error.retryable, never on the prose message:

const res = await fetch(extractUrl, { method: "POST", headers, body: form })
if (res.ok) return res.json()

const { error } = await res.json() as { error: { type: string; retryable: boolean; message: string } }
if (error.retryable) {
  // back off (exponential WITH FULL JITTER), then retry the same request
} else {
  // surface error.type to your monitoring; do NOT auto-retry
}

The retryable types are extract_at_capacity (503), rate_limit (429), timeout (504), and upstream_unavailable (502). Everything else is terminal — retrying sends the same document into the same wall.

Versioning, rollouts, and rollbacks

The Schema Version UUID is what pins your extraction to a specific (fields × base prompt × per-field prompts) tuple. When you want to ship a change:

1. Build the new Schema Version under the same Schema Type. The version number auto-increments — v2, then v3.
2. Benchmark v2 side-by-side with v1 using Run a Manual Test against the same Test Set.
3. When v2 clears your bar, change the requestSchemaVersionId your app sends. Old v1 calls (in-flight when you flip the config) still extract against v1 — there's no hard cutover.
4. Rollback is the same flip in reverse. v1 stays Published indefinitely.

Same applies to model swaps via modelDeploymentId. You don't need to redeploy your application to switch models — that's the whole point of keeping the IDs as configuration.

Rate limits and concurrency

The service runs on an autoscaling pool of replicas, each of which accepts a bounded number of concurrent extractions. Two distinct limits can throttle you:

• Service concurrency (extract_at_capacity, 503). When a replica is already at its in-flight ceiling, it fast-fails immediately with a retryable 503 rather than queueing your request and risking a memory blowout. The pool scales out under load, but a new replica takes roughly 30–70 seconds to come online — so a simultaneous burst can see a few 503s during that window. They clear on their own; the fix is client-side retry.
• Provider rate limits (rate_limit, 429). Beyond the service, your own BYOK provider key has its own throttle, surfaced as a retryable 429.

Both are retryable and both want the same handling: exponential backoff with full jitter.

Recommended policy (identical to the OCR client — see Apply OCR to a Document):

Related

• Apply OCR to a Document — the separate POST /api/ocr step for scans, before extraction.
• Manage Extraction API Keys — minting the bearer token.
• Manage LLM Provider API Keys — wiring up the provider credential the deployment needs.
• Build a Request Schema — defining the shape of data.
• Browse Supported LLM Models — picking a deployment.
• Explore Costs — see what every call cost, broken out by operation type.
• Export a Schema as LangChain JSON — when you'd rather run extraction in your own LangChain pipeline and skip this endpoint entirely.