---
title: "Extract Structured Data"
method: POST
path: "/api/v1/extract"
tags: ["extraction"]
---

# Extract Structured Data

`POST /api/v1/extract`

## Request

- Base URL: `https://docs.thedrive.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.thedrive.ai/api/v1/extract`
- Auth: none declared

Extract structured data from a file or URL using AI.

Upload a file (or provide a URL) along with a typed JSON schema describing the
fields you want extracted. Each field must have a `type` and `description`.
Returns structured data matching your schema with **guaranteed type conformance**.

**Example schema**:
```json
{
  "invoice_number": {"type": "string", "description": "The invoice number"},
  "total_amount": {"type": "number", "description": "Total amount due", "required": true},
  "status": {"type": "string", "enum": ["paid", "unpaid", "overdue"]},
  "line_items": {
    "type": "array",
    "description": "Each line item",
    "items": {
      "type": "object",
      "properties": {
        "description": {"type": "string"},
        "quantity": {"type": "integer"},
        "unit_price": {"type": "number"}
      }
    }
  }
}
```

**Supported types**: `string`, `number`, `integer`, `boolean`, `array`, `object`

**Supported formats**: PDF, DOCX, XLSX, PPTX, CSV, images (JPG, PNG),
and any file type supported by the markdown conversion endpoint.

**Vision mode**: For images or scanned documents, set `use_vision=true`
for highest accuracy on visual content.

## Headers

- `X-API-Key` string

## Response `200`

Successful Response

- ExtractionResponse: Response for structured data extraction.
  - `success` boolean: True if all required fields were found. False if any required field is missing (partial data still returned).
  - `data` object, required: Extracted structured data matching the provided schema. Types are guaranteed when using typed schema.
  - `confidence` object: Per-field calibrated confidence scores (0.0–1.0). Composite of LLM self-report, token logprobs, and OCR quality weighted by extraction method.
  - `citations` object: Per-field source text snippets from the document
  - `filename` string, required: Original filename or URL
  - `content_type` string, nullable: Detected MIME type
  - `model_used` string, required: Model used for extraction (fast or accurate)
  - `extraction_method` string, required: How text was extracted: text, ocr, ocr+vision, vision, or dom+text
  - `text_length` integer, required: Length of extracted text processed
  - `pages_processed` integer: Number of document pages actually read (0 for non-paginated files)
  - `total_pages` integer: Total pages in the document (0 for non-paginated files)
  - `credits_used` integer: Credits consumed for this extraction
  - `schema_format` 'typed': Schema format used for extraction/analysis.
  - `field_status` object, nullable: Per-field status (typed schemas only).
  - `missing_required` string[], nullable: List of required fields that could not be found (typed schemas only). Present only when success=false.
  - `quality_signals` object, nullable: Raw quality signals used for confidence calibration. 'ocr_quality': blended OCR quality (0.7*mean + 0.3*p10, 0–1, absent for non-OCR). 'doc_quality': geometric mean of LLM token probs (0–1). 'signal_disagreement': mean |llm_self_report - logprob| across fields. Values above 0.3 indicate the signals disagree — the model may be confidently wrong (high logprob, low self-report) or self-deprecating.

## Other responses

- `400`: Invalid request
- `413`: File too large
- `422`: Validation Error
- `503`: AI service unavailable

---

[API](https://skmtc.dev/thedrive/apis/the-drive-ai-api.md) · [All operations](https://skmtc.dev/thedrive/apis/the-drive-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thedrive/apis/the-drive-ai-api/revisions/ee4e32647ebf?raw)