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
Theoutput_schema parameter accepts a standard JSON Schema object. This is the same format used by the Chat API for structured outputs.
Thinking Level
Thethinking_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
Passfolders 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.
ContractscoversContracts/2026too. folderscombines withfile_ids: the scope is the union of both.- An empty list is no folder scope.
"folders": []behaves as iffolderswere omitted, sofile_idsorfile_namesmust 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, orfolderstogether withfile_namesanswers422 request.invalid. At most 1,000 entries. - The response echoes
folders: the folders the scope was resolved from, normalized and de-duplicated (nullwhen the request named none). A response to a request with a non-emptyfoldersthat has nofolderswas not scoped by folder: do not use it as if it were (see Checking that a folder was applied). file_idsin the response keeps echoing the request’sfile_ids; the sources found throughfoldersare 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 usingobject 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 a200 response whose JSON body is an error instead of the extraction result:
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
- Use standard JSON Schema — The API accepts any valid JSON Schema, giving you full flexibility
- Be specific in descriptions — Detailed property descriptions improve extraction accuracy
- Use appropriate types — Match property types to expected data (
numberfor amounts,stringfor dates) - Provide clear instructions — Guide the extraction with format preferences and edge cases
- Use objects for structured data — Group related fields using nested objects (e.g., address with street, city, zip)
- Use arrays for lists — Extract repeating items using arrays with appropriate item schemas
- Keep nesting shallow — Avoid deeply nested structures for better extraction accuracy
- Define required fields — Use the
requiredarray to specify mandatory properties - Use raw_json for debugging — The
raw_jsonfield contains the model’s raw output before validation
Related
Data Extraction Guide
Learn schema design and extraction best practices
Data Ingestion
Improve parsing quality for better extraction results

