{"openapi":"3.1.0","info":{"title":"DocAI - Document Intelligence API","description":"AI-powered document parsing and data extraction service. Parse PDFs, images, and Office documents to extract structured data.","version":"1.29.5"},"paths":{"/v1/extract":{"post":{"tags":["Extraction"],"summary":"Extract structured data from a file or text","description":"Schema-on-Request extraction. Send a file (PDF, image, DOCX, Excel) OR pre-parsed Markdown text, plus an optional JSON Schema. DocAI handles OCR, parsing, and LLM extraction automatically.","operationId":"extract_from_file_v1_extract_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_extract_from_file_v1_extract_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/extract/text":{"post":{"tags":["Extraction"],"summary":"Extract structured data from pre-parsed text","description":"Extract from Markdown text (skips OCR). Use when you already have the document text and just need LLM extraction.","operationId":"extract_from_text_v1_extract_text_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/task":{"post":{"tags":["Task","Task"],"summary":"Execute AI task on a file or text","description":"Send a file (PDF, image, etc.) or text + prompt + output_schema. DocAI handles OCR/parsing automatically if a file is provided. async_mode=true returns task_id immediately — poll GET /v1/task/{task_id} (recommended for large scans: OCR can take minutes).","operationId":"execute_task_with_file_v1_task_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_execute_task_with_file_v1_task_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TaskResponse"},{"$ref":"#/components/schemas/TaskAsyncAccepted"}],"title":"Response Execute Task With File V1 Task Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/task/{task_id}":{"get":{"tags":["Task","Task"],"summary":"Poll async task status/result","description":"Return async task state. 404 for unknown/expired/foreign task ids.","operationId":"get_task_status_v1_task__task_id__get","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/task/text":{"post":{"tags":["Task","Task"],"summary":"Execute AI task on pre-parsed text","description":"For when you already have document text — skips OCR.","operationId":"execute_task_text_v1_task_text_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ladder/extract":{"post":{"tags":["Extraction Ladder (experimental)"],"summary":"Ladder Extract","description":"Extract typed fields and ruled tables via the ladder (no LLM).","operationId":"ladder_extract_v1_ladder_extract_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_ladder_extract_v1_ladder_extract_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Ladder Extract V1 Ladder Extract Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/match":{"post":{"tags":["Registry Match"],"summary":"Match extracted values against a client registry (stateless)","description":"Multipart: registry file (XLSX/CSV) + values (JSON array of strings) + key_column. The registry is processed in memory and never stored.","operationId":"match_registry_v1_match_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_match_registry_v1_match_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Match Registry V1 Match Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/schemas":{"get":{"tags":["Schemas"],"summary":"List available schemas","description":"Get list of all available extraction schemas.","operationId":"list_schemas_v1_schemas_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaListResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/schemas/{schema_type}":{"get":{"tags":["Schemas"],"summary":"Get schema info","description":"Get information about a specific schema type.","operationId":"get_schema_info_v1_schemas__schema_type__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"schema_type","in":"path","required":true,"schema":{"type":"string","title":"Schema Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaInfo"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/schemas/{schema_type}/{version}":{"get":{"tags":["Schemas"],"summary":"Get schema details","description":"Get detailed schema definition for a specific version.","operationId":"get_schema_detail_v1_schemas__schema_type___version__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"schema_type","in":"path","required":true,"schema":{"type":"string","title":"Schema Type"}},{"name":"version","in":"path","required":true,"schema":{"type":"string","title":"Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/embed":{"post":{"tags":["Embeddings"],"summary":"Generate text embedding","description":"Generate an embedding vector for search or indexing.\n\n- `text-search-query` — for user search queries (default)\n- `text-search-doc` — for document text (use include_chunks in /extract instead)","operationId":"embed_text_v1_embed_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/split":{"post":{"tags":["Document Splitting"],"summary":"Split composite document","description":"Split a composite PDF (contract + appendices) into separate logical sub-documents. Returns PDF and Markdown for each section.","operationId":"split_document_v1_split_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_split_document_v1_split_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/split/analyze":{"post":{"tags":["Document Splitting"],"summary":"Split, classify, and extract","description":"Split a composite PDF, then classify and extract structured data from each section independently. Combines /v1/split + /v1/classify + /v1/parse.","operationId":"split_and_analyze_v1_split_analyze_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_split_and_analyze_v1_split_analyze_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitAnalyzeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stats":{"get":{"tags":["Statistics"],"summary":"Get API statistics","description":"Get aggregated statistics about API usage.","operationId":"get_stats_v1_stats_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stats/reset":{"post":{"tags":["Statistics"],"summary":"Reset statistics","description":"Reset all statistics to zero.","operationId":"reset_stats_v1_stats_reset_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Reset Stats V1 Stats Reset Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/clients":{"get":{"tags":["Admin","Admin"],"summary":"List Clients","description":"List all clients.","operationId":"list_clients_v1_admin_clients_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ClientResponse"},"type":"array","title":"Response List Clients V1 Admin Clients Get"}}}}},"security":[{"APIKeyHeader":[]}]},"post":{"tags":["Admin","Admin"],"summary":"Create Client","description":"Create a new API client. Returns the API key — shown ONCE.","operationId":"create_client_v1_admin_clients_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientCreatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/admin/clients/{client_id}":{"get":{"tags":["Admin","Admin"],"summary":"Get Client","description":"Get client details.","operationId":"get_client_v1_admin_clients__client_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Client Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Admin","Admin"],"summary":"Update Client","description":"Update client settings.","operationId":"update_client_v1_admin_clients__client_id__patch","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Client Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/clients/{client_id}/rotate-key":{"post":{"tags":["Admin","Admin"],"summary":"Rotate Key","description":"Rotate API key for a client. Returns new key (shown ONCE).","operationId":"rotate_key_v1_admin_clients__client_id__rotate_key_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Client Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/clients/{client_id}/usage":{"get":{"tags":["Admin","Admin"],"summary":"Get Client Usage","description":"Get usage stats for a client.","operationId":"get_client_usage_v1_admin_clients__client_id__usage_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Client Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientUsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"tags":["Health"],"summary":"Health Check","description":"Health check endpoint.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Check Health Get"}}}}}}}},"components":{"schemas":{"AppendixInfo":{"properties":{"index":{"type":"integer","title":"Index","description":"Appendix position (1-based)"},"type":{"type":"string","title":"Type","description":"Detected type (technical_specification, act, specification, etc.)"},"title":{"type":"string","title":"Title","description":"Appendix title from document"},"markdown":{"type":"string","title":"Markdown","description":"Appendix markdown content"},"data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Data","description":"Extracted data (only if extract_appendices requested)"},"page_start":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Start","description":"First page (1-based, PDF only)"},"page_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page End","description":"Last page (1-based, inclusive, PDF only)"}},"type":"object","required":["index","type","title","markdown"],"title":"AppendixInfo","description":"An appendix detected inside a composite document (regex, no LLM)."},"Body_execute_task_with_file_v1_task_post":{"properties":{"prompt":{"type":"string","title":"Prompt","description":"Task instruction (prompt)"},"file":{"anyOf":[{"type":"string","contentMediaType":"application/octet-stream"},{"type":"null"}],"title":"File","description":"Document file (optional)"},"document_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Text","description":"Document text (if no file)"},"output_schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Schema","description":"JSON Schema for output (string)"},"system_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Prompt","description":"System prompt override"},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context","description":"Additional context (JSON string)"},"temperature":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Temperature","default":0.1},"max_tokens":{"type":"integer","maximum":16384.0,"minimum":1.0,"title":"Max Tokens","default":4096},"document_type":{"type":"string","title":"Document Type","description":"Known document type hint (e.g. contract, act) — tunes the parsing pipeline","default":"auto"},"async_mode":{"type":"boolean","title":"Async Mode","description":"Return task_id immediately, process in background (poll for result)","default":false},"include_markdown":{"type":"boolean","title":"Include Markdown","description":"Вернуть markdown документа после OCR/парсинга","default":false},"include_chunks":{"type":"boolean","title":"Include Chunks","description":"Вернуть чанки с embeddings (векторизация параллельно LLM-задаче)","default":false}},"type":"object","required":["prompt"],"title":"Body_execute_task_with_file_v1_task_post"},"Body_extract_from_file_v1_extract_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"Document file"},"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema","description":"JSON Schema for extraction (string)"},"document_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type","description":"Document type hint"},"schema_version":{"type":"string","title":"Schema Version","description":"Schema version","default":"latest"},"include_chunks":{"type":"boolean","title":"Include Chunks","description":"Return chunks with embeddings","default":false},"chunk_size":{"type":"integer","title":"Chunk Size","description":"Target chunk size in chars","default":500},"extract_appendices":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extract Appendices","description":"JSON list of appendix types to extract via LLM, e.g. [\"supplementary_agreement\",\"technical_specification\"]"},"business_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Context","description":"Business instruction for extraction. DocAI wraps it with technical rules automatically."},"skip_cache":{"type":"boolean","title":"Skip Cache","description":"Skip cache and force re-processing","default":false},"extraction_mode":{"type":"string","enum":["fast","balanced","accurate"],"title":"Extraction Mode","description":"Latency vs accuracy trade-off (DCAI-43). 'fast' = single-shot + primary model only (~15s VLM). 'balanced' (default) = chunked + fallback chain. 'accurate' = chunked + retries + cross-field.","default":"balanced"}},"type":"object","required":["file"],"title":"Body_extract_from_file_v1_extract_post"},"Body_ladder_extract_v1_ladder_extract_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"grammars":{"type":"string","title":"Grammars","default":"kks,requisites,measures,eskd_stamp"},"required":{"type":"string","title":"Required","default":""},"use_ocr":{"type":"boolean","title":"Use Ocr","default":true}},"type":"object","required":["file"],"title":"Body_ladder_extract_v1_ladder_extract_post"},"Body_match_registry_v1_match_post":{"properties":{"registry":{"type":"string","contentMediaType":"application/octet-stream","title":"Registry","description":"Реестр: XLSX или CSV"},"values":{"type":"string","title":"Values","description":"Извлечённые значения (JSON: [\"v1\", \"v2\", ...])"},"key_column":{"type":"string","title":"Key Column","description":"Колонка реестра-ключ (например, ARTCL)"}},"type":"object","required":["registry","values","key_column"],"title":"Body_match_registry_v1_match_post"},"Body_split_and_analyze_v1_split_analyze_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"Composite PDF document"}},"type":"object","required":["file"],"title":"Body_split_and_analyze_v1_split_analyze_post"},"Body_split_document_v1_split_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"Composite PDF document"},"use_llm_fallback":{"type":"boolean","title":"Use Llm Fallback","description":"Use LLM to detect boundaries when regex finds none","default":true}},"type":"object","required":["file"],"title":"Body_split_document_v1_split_post"},"ClassificationInfo":{"properties":{"category":{"type":"string","title":"Category","description":"Category name (e.g., 'incoming_invoice')"},"display_name":{"type":"string","title":"Display Name","description":"Human-readable category name"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Classification confidence (0-1)"},"reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning","description":"LLM reasoning for classification"}},"type":"object","required":["category","display_name","confidence"],"title":"ClassificationInfo","description":"Document classification result."},"ClientCreate":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"plan":{"type":"string","pattern":"^(free|starter|business|enterprise)$","title":"Plan","default":"free"}},"type":"object","required":["name"],"title":"ClientCreate","description":"Request to create a new API client."},"ClientCreatedResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"api_key_prefix":{"type":"string","title":"Api Key Prefix"},"plan":{"type":"string","title":"Plan"},"pages_used_this_month":{"type":"integer","title":"Pages Used This Month"},"pages_limit":{"type":"integer","title":"Pages Limit"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"api_key":{"type":"string","title":"Api Key","description":"Full API key — shown only once at creation time."}},"type":"object","required":["id","name","email","description","api_key_prefix","plan","pages_used_this_month","pages_limit","is_active","created_at","updated_at","api_key"],"title":"ClientCreatedResponse","description":"Response after creating a client — includes the API key (shown ONCE)."},"ClientResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"api_key_prefix":{"type":"string","title":"Api Key Prefix"},"plan":{"type":"string","title":"Plan"},"pages_used_this_month":{"type":"integer","title":"Pages Used This Month"},"pages_limit":{"type":"integer","title":"Pages Limit"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","name","email","description","api_key_prefix","plan","pages_used_this_month","pages_limit","is_active","created_at","updated_at"],"title":"ClientResponse","description":"Client info (no API key — shown only on creation)."},"ClientUpdate":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"plan":{"anyOf":[{"type":"string","pattern":"^(free|starter|business|enterprise)$"},{"type":"null"}],"title":"Plan"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"},"pages_limit":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Pages Limit"}},"type":"object","title":"ClientUpdate","description":"Request to update an existing client."},"ClientUsage":{"properties":{"requests":{"type":"integer","title":"Requests","default":0},"pages":{"type":"integer","title":"Pages","default":0},"chars":{"type":"integer","title":"Chars","default":0},"tokens":{"type":"integer","title":"Tokens","default":0},"processing_time_ms":{"type":"integer","title":"Processing Time Ms","default":0},"errors":{"type":"integer","title":"Errors","default":0},"by_type":{"additionalProperties":{"$ref":"#/components/schemas/TypeUsage"},"type":"object","title":"By Type"}},"type":"object","title":"ClientUsage","description":"Usage stats for a single client."},"ClientUsageResponse":{"properties":{"client_id":{"type":"string","format":"uuid","title":"Client Id"},"name":{"type":"string","title":"Name"},"plan":{"type":"string","title":"Plan"},"pages_used_this_month":{"type":"integer","title":"Pages Used This Month"},"pages_limit":{"type":"integer","title":"Pages Limit"},"total_requests":{"type":"integer","title":"Total Requests"},"total_pages":{"type":"integer","title":"Total Pages"},"total_tokens":{"type":"integer","title":"Total Tokens"},"total_cost_rub":{"type":"number","title":"Total Cost Rub"}},"type":"object","required":["client_id","name","plan","pages_used_this_month","pages_limit","total_requests","total_pages","total_tokens","total_cost_rub"],"title":"ClientUsageResponse","description":"Usage stats for a client."},"DocumentChunk":{"properties":{"index":{"type":"integer","title":"Index","description":"Chunk position in document"},"text":{"type":"string","title":"Text","description":"Chunk text content"},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page","description":"Page number (if detected)"},"embedding":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"null"}],"title":"Embedding","description":"Embedding vector (256-dim for Yandex)"}},"type":"object","required":["index","text"],"title":"DocumentChunk","description":"A chunk of document text with optional embedding vector."},"EmbedRequest":{"properties":{"text":{"type":"string","minLength":1,"title":"Text","description":"Text to embed"},"model":{"type":"string","enum":["text-search-query","text-search-doc"],"title":"Model","description":"Embedding model: 'text-search-query' for search, 'text-search-doc' for documents","default":"text-search-query"}},"type":"object","required":["text"],"title":"EmbedRequest","description":"Request for text embedding."},"EmbedResponse":{"properties":{"embedding":{"items":{"type":"number"},"type":"array","title":"Embedding","description":"Embedding vector (256-dim)"},"dimension":{"type":"integer","title":"Dimension","description":"Vector dimension","default":256},"model":{"type":"string","title":"Model","description":"Model used"},"tokens_used":{"type":"integer","title":"Tokens Used","description":"Tokens consumed","default":0}},"type":"object","required":["embedding","model"],"title":"EmbedResponse","description":"Response with embedding vector."},"ExtractRequest":{"properties":{"markdown_text":{"type":"string","minLength":1,"title":"Markdown Text","description":"Pre-parsed Markdown text (e.g. from /v1/split response)"},"document_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type","description":"Type of document. Optional when schema is provided.","examples":["incoming_invoice","contract","act"]},"extraction_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Extraction Schema","description":"Inline JSON Schema for extraction (Schema-on-Request)."},"schema_version":{"type":"string","title":"Schema Version","description":"Version of extraction schema to use","default":"latest"},"custom_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Custom Schema","description":"Custom extraction schema (backward compat alias for `schema`)"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"Specific LLM model to use (overrides default)"},"include_chunks":{"type":"boolean","title":"Include Chunks","description":"Return chunks with Yandex embeddings (256-dim vectors)","default":false},"chunk_size":{"type":"integer","maximum":2000.0,"minimum":100.0,"title":"Chunk Size","description":"Target chunk size in chars","default":500},"business_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Context","description":"Business instruction for extraction (e.g. 'Extract party details, payment terms and penalties'). DocAI wraps it with technical rules automatically."},"extraction_mode":{"type":"string","enum":["fast","balanced","accurate"],"title":"Extraction Mode","description":"Latency vs accuracy trade-off. 'fast' = single-shot, primary model only, lower latency. 'balanced' (default) = current chunked+fallback. 'accurate' = chunked + full fallback chain + anonymize retries + cross-field validation.","default":"balanced"}},"type":"object","required":["markdown_text"],"title":"ExtractRequest","description":"Request for Schema-on-Request extraction from pre-parsed Markdown text.\n\nSchema hierarchy:\n1. `schema` (inline JSON Schema) → full client control\n2. `custom_schema` (alias, backward compat) → same as schema\n3. `document_type` → use built-in schema from registry\n4. Neither → auto-detect type and extract"},"ExtractionMetadata":{"properties":{"document_type":{"type":"string","title":"Document Type"},"schema_version":{"type":"string","title":"Schema Version"},"provider":{"type":"string","title":"Provider"},"model":{"type":"string","title":"Model"},"processing_time_ms":{"type":"integer","title":"Processing Time Ms"},"tokens_used":{"type":"integer","title":"Tokens Used","default":0},"pages_processed":{"type":"integer","title":"Pages Processed","default":0},"route_used":{"type":"string","title":"Route Used","default":""},"normalized_pages":{"type":"integer","title":"Normalized Pages","description":"Billing unit: ceil(chars / 2000)","default":0},"main_document_pages":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Main Document Pages","description":"Pages belonging to main document excluding appendices (1-based, PDF only)"},"file_hash":{"type":"string","title":"File Hash","default":""},"input_quality_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Input Quality Score","description":"Input quality score 0-1 for scanned/photo input. Distinct from None: `None` means 'not measured' (text-native PDF/DOCX, no OCR step); `0.0` means 'measured and unreadable' (tiny/corrupt image). `1.0` means 'clean text-native or perfect OCR'. Clients comparing quality MUST handle None separately from 0.0."}},"type":"object","required":["document_type","schema_version","provider","model","processing_time_ms"],"title":"ExtractionMetadata","description":"Metadata about the extraction process."},"ExtractionResult":{"properties":{"data":{"additionalProperties":true,"type":"object","title":"Data","description":"Extracted structured data"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Overall confidence score (0-1)"},"field_confidences":{"additionalProperties":{"type":"number"},"type":"object","title":"Field Confidences","description":"Confidence score per field"}},"type":"object","required":["data","confidence"],"title":"ExtractionResult","description":"Result of data extraction."},"ExtractionWarning":{"properties":{"code":{"type":"string","enum":["invalid_inn_length","invalid_kpp_length","suspicious_amount","ocr_noise","duplicate_party","missing_contractor_inn","ambiguous_document_number","low_input_quality","llm_extraction_unavailable","parse_only","ocr_unreadable","ocr_rate_limited","ocr_timeout","ocr_connection_error","ocr_bad_response","totals_mismatch","weight_invariant_violation","sender_equals_carrier","date_out_of_range"],"title":"Code","description":"Stable warning code (e.g. 'invalid_inn_length', 'duplicate_party')"},"field":{"type":"string","title":"Field","description":"Dotted path to the affected field (e.g. 'supplier.inn', 'items[0].amount') or '$document' for whole document"},"severity":{"type":"string","enum":["low","medium","high"],"title":"Severity","description":"Severity: low (informational), medium (review advised), high (likely wrong)"},"message":{"type":"string","title":"Message","description":"Human-readable explanation (ru)"}},"type":"object","required":["code","field","severity","message"],"title":"ExtractionWarning","description":"Structured warning about extraction quality or validation failure.\n\nEmitted by DocAI when the response may be unreliable. Clients should\nuse this as a signal to ask user confirmation or reject the value.\nImmutable — `warnings` are events, not state."},"FieldSourceInfo":{"properties":{"chunk_index":{"type":"integer","title":"Chunk Index","description":"Index of the chunk containing this field"},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page","description":"Page number (if detected)"},"text_snippet":{"type":"string","title":"Text Snippet","description":"Text around the matched value (~160 chars)"}},"type":"object","required":["chunk_index","text_snippet"],"title":"FieldSourceInfo","description":"Links an extracted field to its source location in the document."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ParseResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"extraction_status":{"type":"string","enum":["full","partial","fallback","parse_only"],"title":"Extraction Status","description":"Extraction quality: 'full' (LLM), 'partial' (some chunks), 'fallback' (regex only), 'parse_only' (no extraction)","default":"full"},"result":{"$ref":"#/components/schemas/ExtractionResult"},"metadata":{"$ref":"#/components/schemas/ExtractionMetadata"},"markdown":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Markdown","description":"Parsed Markdown text (when include_chunks=True)"},"chunks":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentChunk"},"type":"array"},{"type":"null"}],"title":"Chunks","description":"Chunks with embeddings (when include_chunks=True)"},"appendices":{"anyOf":[{"items":{"$ref":"#/components/schemas/AppendixInfo"},"type":"array"},{"type":"null"}],"title":"Appendices","description":"Detected appendices (regex, no LLM cost)"},"field_sources":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/FieldSourceInfo"},"type":"object"},{"type":"null"}],"title":"Field Sources","description":"Field-to-source mapping (when include_chunks=True)"},"warnings":{"items":{"$ref":"#/components/schemas/ExtractionWarning"},"type":"array","title":"Warnings","description":"Structured warnings about extraction quality/validation issues"}},"type":"object","required":["result","metadata"],"title":"ParseResponse","description":"Response from document parsing."},"SchemaDetailResponse":{"properties":{"type":{"type":"string","title":"Type"},"version":{"type":"string","title":"Version"},"display_name":{"type":"string","title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"system_prompt":{"type":"string","title":"System Prompt"},"extraction_schema":{"additionalProperties":true,"type":"object","title":"Extraction Schema"},"post_processing":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Post Processing"}},"type":"object","required":["type","version","display_name","system_prompt","extraction_schema"],"title":"SchemaDetailResponse","description":"Detailed schema definition."},"SchemaInfo":{"properties":{"type":{"type":"string","title":"Type"},"display_name":{"type":"string","title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"versions":{"items":{"type":"string"},"type":"array","title":"Versions"},"latest_version":{"type":"string","title":"Latest Version"}},"type":"object","required":["type","display_name","versions","latest_version"],"title":"SchemaInfo","description":"Information about an extraction schema."},"SchemaListResponse":{"properties":{"schemas":{"items":{"$ref":"#/components/schemas/SchemaInfo"},"type":"array","title":"Schemas"}},"type":"object","required":["schemas"],"title":"SchemaListResponse","description":"List of available schemas."},"SplitAnalyzeResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"total_pages":{"type":"integer","title":"Total Pages","description":"Total pages in original document"},"sections_found":{"type":"integer","title":"Sections Found","description":"Number of sections detected"},"sections":{"items":{"$ref":"#/components/schemas/SplitAnalyzeSectionResult"},"type":"array","title":"Sections"},"processing_time_ms":{"type":"integer","title":"Processing Time Ms"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["total_pages","sections_found","sections","processing_time_ms"],"title":"SplitAnalyzeResponse","description":"Response from split + classify + extract."},"SplitAnalyzeSectionResult":{"properties":{"section":{"$ref":"#/components/schemas/SplitSectionInfo"},"pdf_base64":{"type":"string","title":"Pdf Base64","description":"Section PDF encoded as base64"},"markdown":{"type":"string","title":"Markdown","description":"Markdown text of this section"},"classification":{"anyOf":[{"$ref":"#/components/schemas/ClassificationInfo"},{"type":"null"}],"description":"Classification result for this section"},"extraction":{"anyOf":[{"$ref":"#/components/schemas/ExtractionResult"},{"type":"null"}],"description":"Extracted structured data for this section"}},"type":"object","required":["section","pdf_base64","markdown"],"title":"SplitAnalyzeSectionResult","description":"Section with classification and extraction results."},"SplitResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"total_pages":{"type":"integer","title":"Total Pages","description":"Total pages in original document"},"sections_found":{"type":"integer","title":"Sections Found","description":"Number of sections detected"},"sections":{"items":{"$ref":"#/components/schemas/SplitSectionResult"},"type":"array","title":"Sections"},"processing_time_ms":{"type":"integer","title":"Processing Time Ms"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["total_pages","sections_found","sections","processing_time_ms"],"title":"SplitResponse","description":"Response from document splitting."},"SplitSectionInfo":{"properties":{"index":{"type":"integer","minimum":1.0,"title":"Index","description":"Section number (1-based)"},"title":{"type":"string","title":"Title","description":"Detected section title (e.g. 'Приложение №1')"},"start_page":{"type":"integer","minimum":1.0,"title":"Start Page","description":"First page of section (1-based)"},"end_page":{"type":"integer","minimum":1.0,"title":"End Page","description":"Last page of section (1-based, inclusive)"},"page_count":{"type":"integer","minimum":1.0,"title":"Page Count","description":"Number of pages in section"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Boundary detection confidence"},"starts_mid_page":{"type":"boolean","title":"Starts Mid Page","description":"True if the section boundary was detected mid-page","default":false}},"type":"object","required":["index","title","start_page","end_page","page_count","confidence"],"title":"SplitSectionInfo","description":"Metadata about a detected document section."},"SplitSectionResult":{"properties":{"section":{"$ref":"#/components/schemas/SplitSectionInfo"},"pdf_base64":{"type":"string","title":"Pdf Base64","description":"Section PDF encoded as base64"},"markdown":{"type":"string","title":"Markdown","description":"Markdown text of this section"}},"type":"object","required":["section","pdf_base64","markdown"],"title":"SplitSectionResult","description":"Single section from a split document."},"StatsResponse":{"properties":{"uptime_seconds":{"type":"integer","title":"Uptime Seconds"},"total_requests":{"type":"integer","title":"Total Requests"},"requests_by_category":{"additionalProperties":{"type":"integer"},"type":"object","title":"Requests By Category"},"avg_confidence":{"type":"number","title":"Avg Confidence"},"avg_processing_time_ms":{"type":"number","title":"Avg Processing Time Ms"},"classification_count":{"type":"integer","title":"Classification Count"},"extraction_count":{"type":"integer","title":"Extraction Count"},"clients":{"additionalProperties":{"$ref":"#/components/schemas/ClientUsage"},"type":"object","title":"Clients","description":"Per-client usage breakdown"}},"type":"object","required":["uptime_seconds","total_requests","requests_by_category","avg_confidence","avg_processing_time_ms","classification_count","extraction_count"],"title":"StatsResponse","description":"API usage statistics."},"TaskAsyncAccepted":{"properties":{"task_id":{"type":"string","title":"Task Id","description":"Job id for polling."},"status":{"type":"string","title":"Status","default":"processing"},"poll_url":{"type":"string","title":"Poll Url","description":"GET this URL with the same X-API-Key."}},"type":"object","required":["task_id","poll_url"],"title":"TaskAsyncAccepted","description":"Immediate response for async_mode=true: poll GET /v1/task/{task_id}."},"TaskRequest":{"properties":{"prompt":{"type":"string","minLength":1,"title":"Prompt","description":"Instruction for the LLM (prompt from the caller)."},"document_text":{"type":"string","minLength":1,"title":"Document Text","description":"Document text (markdown) to process."},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema","description":"JSON Schema for structured output. If provided, LLM returns JSON matching this schema."},"system_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Prompt","description":"Optional system prompt override. Defaults to a generic document assistant."},"context":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Context","description":"Optional context data (e.g. compare_with_document_id)."},"temperature":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Temperature","description":"LLM temperature (0.0 = deterministic, 1.0 = creative).","default":0.1},"max_tokens":{"type":"integer","maximum":16384.0,"minimum":1.0,"title":"Max Tokens","description":"Maximum tokens in LLM response.","default":4096},"include_chunks":{"type":"boolean","title":"Include Chunks","description":"Вернуть чанки с embeddings (векторизация идёт параллельно LLM-задаче).","default":false}},"type":"object","required":["prompt","document_text"],"title":"TaskRequest","description":"Request for POST /v1/task.\n\nDocAI is a universal executor — it does not know about business logic.\nPrompts and output schemas are defined by the caller (e.g. DocInspect)."},"TaskResponse":{"properties":{"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"string"}],"title":"Result","description":"Task result — JSON object (if output_schema provided) or free text."},"tokens_used":{"type":"integer","title":"Tokens Used","description":"Total tokens consumed.","default":0},"pages_processed":{"type":"integer","title":"Pages Processed","description":"Pages processed (for billing).","default":0},"model":{"type":"string","title":"Model","description":"Model used for this task.","default":""},"provider":{"type":"string","title":"Provider","description":"Provider (yandex / vllm).","default":""},"anonymization":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Anonymization","description":"PII boundary info: {mode, items, categories} — counts of scrubbed placeholders sent to the external LLM instead of real values. None when the boundary is off (local / self_hosted)."},"markdown":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Markdown","description":"Markdown документа после OCR/парсинга (include_markdown=true, файловый вариант)."},"chunks":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Chunks","description":"Чанки с embeddings (include_chunks=true): [{index, text, page, embedding}]. Векторизуются параллельно с LLM-задачей; embeddings считаются по анонимизированному тексту, text — оригинальный."},"ladder":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Ladder","description":"Extraction-ladder pre-pass (LADDER_ENABLED, PDF): {overrides, hints, stats}. Overrides — детерминированные значения (чексуммы/формат), записанные в result поверх ответа LLM; hints — списки кандидатов, из которых выбирала LLM. None — лестница выключена или файл не PDF."}},"type":"object","required":["result"],"title":"TaskResponse","description":"Response from POST /v1/task."},"TaskStatusResponse":{"properties":{"task_id":{"type":"string","title":"Task Id"},"status":{"type":"string","title":"Status","description":"processing | done | error"},"result":{"anyOf":[{"$ref":"#/components/schemas/TaskResponse"},{"type":"null"}],"description":"Filled when status == done."},"error":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Error","description":"{code, message, details} when status == error."}},"type":"object","required":["task_id","status"],"title":"TaskStatusResponse","description":"Response of GET /v1/task/{task_id}."},"TypeUsage":{"properties":{"requests":{"type":"integer","title":"Requests","default":0},"pages":{"type":"integer","title":"Pages","default":0},"chars":{"type":"integer","title":"Chars","default":0},"tokens":{"type":"integer","title":"Tokens","default":0},"processing_time_ms":{"type":"integer","title":"Processing Time Ms","default":0},"errors":{"type":"integer","title":"Errors","default":0}},"type":"object","title":"TypeUsage","description":"Usage stats for one document type within a client."},"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"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}