> ## Documentation Index > Fetch the complete documentation index at: https://docs.thedrive.ai/llms.txt > Use this file to discover all available pages before exploring further. # Extract Structured Data > 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. ## OpenAPI ````yaml /openapi.json post /api/v1/extract openapi: 3.1.0 info: title: The Drive AI API description: > ## The Drive AI API One API for screenshots, markdown extraction, structured data extraction, and more. 107+ file formats supported. ## Endpoints | Endpoint | Credits | Description | |----------|---------|-------------| | `GET /{url}` | 1 | Screenshot any URL | | `GET /md/{url}` | 1 | Convert any URL to markdown | | `POST /api/v1/thumbnails/generate` | 1 | Generate thumbnail from file or URL | | `POST /api/v1/markdown/convert` | 1 | Convert file/URL to markdown | | `POST /api/v1/extract` | 1/page or 5/site | Extract structured data | | `POST /api/v1/analyze` | 2/page or 10/site | Analyze — compute, reason, derive | ## Authentication All protected endpoints require an `X-API-Key` header: ```bash curl https://dev.thedrive.ai/stripe.com \ -H "X-API-Key: tda_live_your_key_here" ``` Get your API key at https://dev.thedrive.ai/login ## Pricing - **Free**: 100 credits/month, no card required - **Pro**: $0.01/credit, pay-as-you-go - **Enterprise**: Volume pricing, contact us version: 1.3.0 servers: [] security: [] tags: - name: screenshots description: Screenshot and thumbnail generation - name: markdown description: URL and document to markdown conversion - name: extraction description: Structured data extraction from documents - name: thumbnails description: Thumbnail generation via file upload or URL - name: health description: Service health and readiness probes paths: /api/v1/extract: post: tags: - extraction summary: Extract Structured Data description: >- 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. operationId: extract_structured_data_api_v1_extract_post parameters: - name: X-API-Key in: header required: false schema: type: string title: X-Api-Key requestBody: required: true content: multipart/form-data: schema: $ref: >- #/components/schemas/Body_extract_structured_data_api_v1_extract_post responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ExtractionResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: File too large content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '503': description: AI service unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: Body_extract_structured_data_api_v1_extract_post: properties: file: anyOf: - type: string contentMediaType: application/octet-stream - type: 'null' title: File description: File to extract data from url: anyOf: - type: string - type: 'null' title: Url description: URL to fetch file from url_headers: anyOf: - type: string - type: 'null' title: Url Headers description: JSON-encoded headers for URL auth schema: type: string title: Schema description: JSON schema defining fields to extract model: type: string title: Model description: 'Model: ''fast'', ''accurate'', or ''auto''' default: auto use_vision: type: boolean title: Use Vision description: Use vision mode for images and scanned documents default: false follow_links: type: boolean title: Follow Links description: >- Follow internal links (e.g. /about, /contact) to find more data. URL inputs only. default: false sync: type: boolean title: Sync description: Set to false to process asynchronously. Returns a task_id to poll. default: true webhook_url: anyOf: - type: string - type: 'null' title: Webhook Url description: URL to POST the result to when async processing completes. type: object required: - schema title: Body_extract_structured_data_api_v1_extract_post ExtractionResponse: properties: success: type: boolean title: Success description: >- True if all required fields were found. False if any required field is missing (partial data still returned). default: true data: additionalProperties: true type: object title: Data description: >- Extracted structured data matching the provided schema. Types are guaranteed when using typed schema. confidence: additionalProperties: type: number type: object title: Confidence description: >- Per-field calibrated confidence scores (0.0–1.0). Composite of LLM self-report, token logprobs, and OCR quality weighted by extraction method. citations: additionalProperties: true type: object title: Citations description: Per-field source text snippets from the document filename: type: string title: Filename description: Original filename or URL content_type: anyOf: - type: string - type: 'null' title: Content Type description: Detected MIME type model_used: type: string title: Model Used description: Model used for extraction (fast or accurate) extraction_method: type: string title: Extraction Method description: 'How text was extracted: text, ocr, ocr+vision, vision, or dom+text' text_length: type: integer title: Text Length description: Length of extracted text processed pages_processed: type: integer title: Pages Processed description: Number of document pages actually read (0 for non-paginated files) default: 0 total_pages: type: integer title: Total Pages description: Total pages in the document (0 for non-paginated files) default: 0 credits_used: type: integer title: Credits Used description: Credits consumed for this extraction default: 0 schema_format: anyOf: - $ref: '#/components/schemas/SchemaFormat' - type: 'null' description: >- Schema format: always 'typed'. Each field has an explicit type for guaranteed type conformance. field_status: anyOf: - additionalProperties: $ref: '#/components/schemas/FieldStatusInfo' type: object - type: 'null' title: Field Status description: Per-field status (typed schemas only). missing_required: anyOf: - items: type: string type: array - type: 'null' title: Missing Required description: >- List of required fields that could not be found (typed schemas only). Present only when success=false. quality_signals: anyOf: - additionalProperties: type: number type: object - type: 'null' title: Quality Signals description: >- 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. type: object required: - data - filename - model_used - extraction_method - text_length title: ExtractionResponse description: Response for structured data extraction. example: citations: invoice_number: 'Invoice #: INV-2024-0042' total_amount: 'Total Due: $1,234.56' confidence: invoice_number: 0.96 total_amount: 0.91 vendor_name: 0.94 content_type: application/pdf credits_used: 7 data: invoice_number: INV-2024-0042 total_amount: 1234.56 vendor_name: Acme Corp extraction_method: text field_status: invoice_number: confidence: 0.96 required: false status: found type: string total_amount: confidence: 0.91 required: true status: found type: number vendor_name: confidence: 0.94 required: false status: found type: string filename: invoice.pdf model_used: fast pages_processed: 50 schema_format: typed success: true text_length: 2450 total_pages: 1200 ErrorResponse: properties: success: type: boolean title: Success default: false error: type: string title: Error description: Error type detail: type: string title: Detail description: Human-readable error message type: object required: - error - detail title: ErrorResponse description: Standard error response. example: detail: File size exceeds maximum allowed (50MB) error: validation_error success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SchemaFormat: type: string enum: - typed title: SchemaFormat description: Schema format used for extraction/analysis. FieldStatusInfo: properties: status: $ref: '#/components/schemas/FieldStatusValue' description: Whether the field was found confidence: type: number maximum: 1 minimum: 0 title: Confidence description: Calibrated confidence score (0.0–1.0) type: type: string title: Type description: Expected type from schema required: type: boolean title: Required description: Whether the field was marked required type: object required: - status - confidence - type - required title: FieldStatusInfo description: Per-field extraction status (typed schemas only). ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError FieldStatusValue: type: string enum: - found - not_found title: FieldStatusValue description: Whether a field was found during extraction. ````