{"openapi":"3.1.0","info":{"title":"Optii OCR API","version":"2.1.0","x-chut-surfaces":[{"id":"optii","label":{"en":"OCR & Documents","fr":"OCR & Documents"},"icon":"file-scan","category":"documents","order":30,"description":"Extract text and structured data from scanned documents"}],"x-chut-manifest-version":"1.6.2"},"security":[{"GatewayHMAC":[]}],"paths":{"/platform/health":{"get":{"tags":["ocr"],"summary":"Platform Health","description":"HMAC-gated health probe for the Chut platform contract suite.","operationId":"platform_health_platform_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"x-tool-name":"optii.health_probe","x-tool-category":"read","x-side-effects":"none","x-requires-confirmation":false,"x-execution-mode":"sync","x-surface":"optii","x-result-render":"text","x-cost":"free","x-idempotent":true,"x-rate-limit":300,"x-timeout":5,"x-fast-path":true,"x-reversible":true}},"/ocr/extract":{"post":{"tags":["ocr"],"summary":"Extract Text","description":"Extract text from an image or PDF. Add ?structured=true for parsed fields.","operationId":"extract_text_ocr_extract_post","parameters":[{"name":"structured","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Structured"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","default":"v2","title":"Format"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_extract_text_ocr_extract_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-tool-name":"optii.ocr_extract","x-tool-category":"read","x-side-effects":"none","x-requires-confirmation":false,"x-execution-mode":"sync","x-surface":"optii","x-result-render":"record","x-cost":"low","x-idempotent":true,"x-rate-limit":300,"x-timeout":30,"x-fast-path":false,"x-reversible":true}},"/ocr/classify":{"post":{"tags":["ocr"],"summary":"Classify Document","description":"Classify a document into one of the Belgian document types the loaded model knows (32 for v2).","operationId":"classify_document_ocr_classify_post","parameters":[{"name":"top_k","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":5,"title":"Top K"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_classify_document_ocr_classify_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-tool-name":"optii.ocr_classify","x-tool-category":"read","x-side-effects":"none","x-requires-confirmation":false,"x-execution-mode":"sync","x-surface":"optii","x-result-render":"record","x-cost":"low","x-idempotent":true,"x-rate-limit":300,"x-timeout":30,"x-fast-path":false,"x-reversible":true}}},"components":{"schemas":{"APIKeyInfo":{"properties":{"id":{"type":"string","title":"Id"},"key_prefix":{"type":"string","title":"Key Prefix"},"name":{"type":"string","title":"Name"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At"},"requests_30d":{"type":"integer","title":"Requests 30D","default":0}},"type":"object","required":["id","key_prefix","name","is_active","created_at","last_used_at"],"title":"APIKeyInfo"},"AccountInfo":{"properties":{"id":{"type":"string","title":"Id"},"email":{"type":"string","title":"Email"},"tier":{"type":"string","title":"Tier"},"locale":{"type":"string","title":"Locale","default":"en"},"created_at":{"type":"string","title":"Created At"},"key_count":{"type":"integer","title":"Key Count","default":0},"tier_limits":{"additionalProperties":true,"type":"object","title":"Tier Limits"}},"type":"object","required":["id","email","tier","created_at","tier_limits"],"title":"AccountInfo"},"AccountUpdate":{"properties":{"locale":{"type":"string","maxLength":2,"minLength":2,"title":"Locale"}},"type":"object","required":["locale"],"title":"AccountUpdate"},"Body_classify_document_ocr_classify_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_classify_document_ocr_classify_post"},"Body_demo_extract_demo_extract_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_demo_extract_demo_extract_post"},"Body_demo_invoice_demo_invoice_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_demo_invoice_demo_invoice_post"},"Body_extract_invoice_endpoint_ocr_invoice_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_extract_invoice_endpoint_ocr_invoice_post"},"Body_extract_text_ocr_extract_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_extract_text_ocr_extract_post"},"CreateKeyRequest":{"properties":{"name":{"type":"string","maxLength":64,"title":"Name","default":""}},"type":"object","title":"CreateKeyRequest"},"CreateKeyResponse":{"properties":{"key":{"type":"string","title":"Key"},"key_prefix":{"type":"string","title":"Key Prefix"},"name":{"type":"string","title":"Name"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["key","key_prefix","name","created_at"],"title":"CreateKeyResponse"},"DailyUsage":{"properties":{"date":{"type":"string","title":"Date"},"requests":{"type":"integer","title":"Requests"},"file_size_kb":{"type":"integer","title":"File Size Kb"},"avg_ms":{"type":"number","title":"Avg Ms"},"errors":{"type":"integer","title":"Errors","default":0},"rate_limited":{"type":"integer","title":"Rate Limited","default":0},"p95_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Ms"}},"type":"object","required":["date","requests","file_size_kb","avg_ms"],"title":"DailyUsage"},"DashboardOverview":{"properties":{"tier":{"type":"string","title":"Tier"},"tier_limits":{"additionalProperties":true,"type":"object","title":"Tier Limits"},"key_count":{"type":"integer","title":"Key Count"},"total_requests":{"type":"integer","title":"Total Requests"},"total_file_size_kb":{"type":"integer","title":"Total File Size Kb"},"requests_today":{"type":"integer","title":"Requests Today","default":0},"quota_used_month":{"type":"integer","title":"Quota Used Month","default":0},"p50_ms_24h":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Ms 24H"},"p95_ms_24h":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Ms 24H"},"error_rate_24h":{"type":"number","title":"Error Rate 24H","default":0.0},"rate_limited_24h":{"type":"integer","title":"Rate Limited 24H","default":0}},"type":"object","required":["tier","tier_limits","key_count","total_requests","total_file_size_kb"],"title":"DashboardOverview"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LogItem":{"properties":{"id":{"type":"integer","title":"Id"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"},"created_at":{"type":"string","title":"Created At"},"endpoint":{"type":"string","title":"Endpoint"},"status_code":{"type":"integer","title":"Status Code"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"processing_ms":{"type":"integer","title":"Processing Ms","default":0},"ocr_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ocr Ms"},"extract_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Extract Ms"},"file_size_kb":{"type":"integer","title":"File Size Kb","default":0},"file_ext":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Ext"},"pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages"},"structured":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Structured"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"document_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"},"warnings":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Warnings"},"replayed":{"type":"boolean","title":"Replayed","default":false},"key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Id"},"key_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Prefix"}},"type":"object","required":["id","created_at","endpoint","status_code"],"title":"LogItem"},"LogsPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/LogItem"},"type":"array","title":"Items"},"next_before":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Before"}},"type":"object","required":["items"],"title":"LogsPage"},"UpdateKeyRequest":{"properties":{"name":{"type":"string","maxLength":64,"title":"Name"}},"type":"object","required":["name"],"title":"UpdateKeyRequest"},"UsageStats":{"properties":{"period":{"type":"string","title":"Period"},"total_requests":{"type":"integer","title":"Total Requests"},"total_file_size_kb":{"type":"integer","title":"Total File Size Kb"},"daily":{"items":{"$ref":"#/components/schemas/DailyUsage"},"type":"array","title":"Daily"},"total_errors":{"type":"integer","title":"Total Errors","default":0},"total_rate_limited":{"type":"integer","title":"Total Rate Limited","default":0},"p95_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Ms"}},"type":"object","required":["period","total_requests","total_file_size_kb","daily"],"title":"UsageStats"},"UserProfile":{"properties":{"id":{"type":"string","title":"Id"},"email":{"type":"string","title":"Email"},"tier":{"type":"string","title":"Tier"},"created_at":{"type":"string","title":"Created At"},"key_count":{"type":"integer","title":"Key Count"}},"type":"object","required":["id","email","tier","created_at","key_count"],"title":"UserProfile"},"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"},"VersionInfo":{"properties":{"api_version":{"type":"string","title":"Api Version"},"ocr_engine":{"type":"string","title":"Ocr Engine"},"ocr_det_model":{"type":"string","title":"Ocr Det Model"},"ocr_rec_model":{"type":"string","title":"Ocr Rec Model"},"classifier_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Classifier Version"},"document_types":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Document Types"},"languages":{"items":{"type":"string"},"type":"array","title":"Languages","default":[]}},"type":"object","required":["api_version","ocr_engine","ocr_det_model","ocr_rec_model"],"title":"VersionInfo"}},"securitySchemes":{"GatewayHMAC":{"type":"apiKey","in":"header","name":"X-Gateway-Signature","description":"Gateway-signed request per chut/platform APP-MANIFEST §1.1 + §1.2.\nThe HMAC signature header is the primary discriminator, but every\nsigned request MUST also carry:\n  - X-Gateway-Timestamp (unix-seconds)\n  - X-Tenant-Id          (tenant uuid)\n  - X-Platform-User-Id   (user uuid)\n  - X-User-Email, X-User-Name, X-User-Roles (json array),\n    X-User-KYC-Level (none|pending|verified|review|denied),\n    X-Source-Origin (user|ai|platform),\n    X-Source-App-Id (callee app slug or empty),\n    X-Request-Id (uuid)\nBackend MUST NOT trust any of these headers from any source other\nthan the gateway. Verify the HMAC; everything else is derived."},"AdminProvisioningSecret":{"type":"apiKey","in":"header","name":"X-Source-Origin","description":"Admin provisioning per APP-MANIFEST §1.11. Either:\n  - X-Source-Origin: platform   (gateway-internal call), OR\n  - X-User-Roles includes \"admin\"\nBoth paths are still gateway-HMAC-signed; the scheme above\ndocuments only the admin-gate principal check on top."}}}}