Skip to main content

Overview

The Data Extraction API allows you to extract structured information from your documents using standard JSON Schema and natural language instructions. The extraction uses the active parsing version of the specified document.

Endpoint

Authentication

Include your API token in the Authorization header:

Request

Headers

Body Parameters

*At least one of file_ids, file_names or folders must be provided and non-empty. file_ids is preferred over file_names.

Output Schema

The output_schema parameter accepts a standard JSON Schema object. This is the same format used by the Chat API for structured outputs.

Thinking Level

The thinking_level parameter controls the model and thinking configuration used for extraction:

Example Request (using file_ids)

Example Request (using file_names - deprecated)

Scope by folder

Pass folders to extract from everything in one or more folders; folders alone is enough:
  • Each folder covers every source at or below it, in any processing status, read when the request arrives. Contracts covers Contracts/2026 too.
  • folders combines with file_ids: the scope is the union of both.
  • An empty list is no folder scope. "folders": [] behaves as if folders were omitted, so file_ids or file_names must then be given. If you build the list in code, check for an empty list before sending.
  • A folder that holds no source refuses the whole request with 400 chat.folder_scope_empty, even when the other folders hold sources.
  • The top level ("", "/") is not a folder. A top-level entry, an invalid path, or folders together with file_names answers 422 request.invalid. At most 1,000 entries.
  • The response echoes folders: the folders the scope was resolved from, normalized and de-duplicated (null when the request named none). A response to a request with a non-empty folders that has no folders was not scoped by folder: do not use it as if it were (see Checking that a folder was applied).
  • file_ids in the response keeps echoing the request’s file_ids; the sources found through folders are not added to it.
Folders are available on the REST API today. In the SDKs they land in the next releases: Python graphor 0.28.0, TypeScript graphor 0.25.0 and the MCP package graphor-mcp 0.25.0. The folder methods, parameters and response fields shown for the SDKs need those versions or later; the hosted remote MCP server offers the folder tools once it runs graphor-mcp 0.25.0.

Example Request with Thinking Level

Example Request with Nested Objects and Arrays

Response

Success Response (200 OK)

Example Response

Response with Object and Array Types

When using object and array types in your schema:

Error Responses

Failures after the response started

A long extraction streams whitespace first to keep the connection open. A failure after that point cannot change the HTTP status, so it arrives as a 200 response whose JSON body is an error instead of the extraction result:
Check for status_code before reading the result: when present, treat the body as an error with that status. detail can be a string or an object, and code depends on what failed, so key your handling on status_code and retryable: retry only when retryable is true (after retry_after seconds when set). reference is present when there is one to quote to support. The SDKs raise the matching error for you. A structured output that still fails validation after correction is a non-retryable error with code: "extraction.internal" and an object detail ({"message": "Structured output validation failed", "error": ...}): a 422 answer, or, once the response has started, a 200 body with status_code: 422 and retryable: false.

Schema Examples

Invoice Extraction

Contract Analysis

Resume Parsing

Product Catalog

Usage Examples

Python

Python with Nested Objects and Arrays

JavaScript

JavaScript with Nested Objects and Arrays

Best Practices

  1. Use standard JSON Schema — The API accepts any valid JSON Schema, giving you full flexibility
  2. Be specific in descriptions — Detailed property descriptions improve extraction accuracy
  3. Use appropriate types — Match property types to expected data (number for amounts, string for dates)
  4. Provide clear instructions — Guide the extraction with format preferences and edge cases
  5. Use objects for structured data — Group related fields using nested objects (e.g., address with street, city, zip)
  6. Use arrays for lists — Extract repeating items using arrays with appropriate item schemas
  7. Keep nesting shallow — Avoid deeply nested structures for better extraction accuracy
  8. Define required fields — Use the required array to specify mandatory properties
  9. Use raw_json for debugging — The raw_json field contains the model’s raw output before validation

Data Extraction Guide

Learn schema design and extraction best practices

Data Ingestion

Improve parsing quality for better extraction results