{"openapi":"3.1.0","info":{"title":"Scriblane API","description":"\nScriblane (by Botlane) turns PDFs, scans, images and Office files into\nstructured data.\n\n* **Convert** a document to Markdown and a structured JSON document model.\n* **Extract** invoice fields (with per-field confidence, source page and\n  bounding box, arithmetic checks and a `needs_review` flag) or generic\n  key-value pairs and tables.\n* **History**: with an organisation API key (create one under *API keys* in the\n  dashboard) every call is stored in your organisation's document history and\n  counted against your monthly page quota. Send it as `X-API-Key` or\n  `Authorization: Bearer`.\n\nExtraction is deterministic and runs fully offline; no LLM key is required.\n\nBuilt on open-source components (see THIRD_PARTY_LICENSES.md). Not affiliated\nwith or endorsed by IBM or the Docling project.\n","contact":{"name":"BotLane LLC","email":"admin@botlane.io"},"license":{"name":"Proprietary - Copyright (c) 2026 BotLane LLC"},"version":"0.3.0","x-logo":{"url":"/static/brand/botlane-bot-mark.png","altText":"Botlane","backgroundColor":"transparent"}},"paths":{"/health":{"get":{"tags":["system"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/v1/documents/convert":{"post":{"tags":["documents"],"summary":"Convert a document to Markdown and structured JSON","operationId":"convert_v1_documents_convert_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_convert_v1_documents_convert_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/documents/extract":{"post":{"tags":["documents"],"summary":"Extract invoice fields or generic key-values and tables","operationId":"extract_v1_documents_extract_post","parameters":[{"name":"type","in":"query","required":false,"schema":{"enum":["invoice","generic"],"type":"string","description":"Extraction profile","default":"invoice","title":"Type"},"description":"Extraction profile"},{"name":"include_markdown","in":"query","required":false,"schema":{"type":"boolean","description":"Also return the document as Markdown in a top-level `markdown` field (used by the web UI)","default":false,"title":"Include Markdown"},"description":"Also return the document as Markdown in a top-level `markdown` field (used by the web UI)"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_extract_v1_documents_extract_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvoiceExtraction"},{"$ref":"#/components/schemas/GenericExtraction"}],"title":"Response Extract V1 Documents Extract Post"}}},"headers":{"X-Botlane-Document-Id":{"description":"History id (organisation keys only)","schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/documents":{"get":{"tags":["history"],"summary":"List your organisation's recent documents","operationId":"list_documents_v1_documents_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"processed, needs_review, reviewed or failed","title":"Status"},"description":"processed, needs_review, reviewed or failed"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Documents V1 Documents Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/documents/{document_id}":{"get":{"tags":["history"],"summary":"Get a stored result by document id","operationId":"get_document_v1_documents__document_id__get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Document V1 Documents  Document Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage":{"get":{"tags":["history"],"summary":"This month's usage against your plan quota","operationId":"usage_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Usage V1 Usage Get"}}}}}}}},"components":{"schemas":{"BBox":{"properties":{"l":{"type":"number","title":"L"},"t":{"type":"number","title":"T"},"r":{"type":"number","title":"R"},"b":{"type":"number","title":"B"},"coord_origin":{"type":"string","const":"TOPLEFT","title":"Coord Origin","default":"TOPLEFT"}},"type":"object","required":["l","t","r","b"],"title":"BBox","description":"Bounding box in PDF points, top-left origin (l, t, r, b)."},"Body_convert_v1_documents_convert_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_convert_v1_documents_convert_post"},"Body_extract_v1_documents_extract_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_extract_v1_documents_extract_post"},"Check":{"properties":{"name":{"type":"string","title":"Name"},"passed":{"type":"boolean","title":"Passed"},"detail":{"type":"string","title":"Detail"}},"type":"object","required":["name","passed","detail"],"title":"Check"},"ConvertResponse":{"properties":{"document":{"$ref":"#/components/schemas/DocumentInfo"},"markdown":{"type":"string","title":"Markdown"},"document_json":{"additionalProperties":true,"type":"object","title":"Document Json","description":"Full structured document (texts, tables, pictures, pages, layout boxes)."}},"type":"object","required":["document","markdown","document_json"],"title":"ConvertResponse"},"DocumentInfo":{"properties":{"filename":{"type":"string","title":"Filename"},"pages":{"type":"integer","title":"Pages"},"processing_seconds":{"type":"number","title":"Processing Seconds"},"quality":{"$ref":"#/components/schemas/Quality"}},"type":"object","required":["filename","pages","processing_seconds","quality"],"title":"DocumentInfo"},"ExtractedField_Annotated_Decimal__PlainSerializer__":{"properties":{"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","default":0.0},"source":{"anyOf":[{"$ref":"#/components/schemas/SourceRef"},{"type":"null"}]},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method","description":"How the value was found, e.g. label, table, pattern, llm"},"raw":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Raw","description":"Original text the value was parsed from"}},"type":"object","title":"ExtractedField[Annotated[Decimal, PlainSerializer]]"},"ExtractedField_date_":{"properties":{"value":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Value"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","default":0.0},"source":{"anyOf":[{"$ref":"#/components/schemas/SourceRef"},{"type":"null"}]},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method","description":"How the value was found, e.g. label, table, pattern, llm"},"raw":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Raw","description":"Original text the value was parsed from"}},"type":"object","title":"ExtractedField[date]"},"ExtractedField_str_":{"properties":{"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","default":0.0},"source":{"anyOf":[{"$ref":"#/components/schemas/SourceRef"},{"type":"null"}]},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method","description":"How the value was found, e.g. label, table, pattern, llm"},"raw":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Raw","description":"Original text the value was parsed from"}},"type":"object","title":"ExtractedField[str]"},"GenericExtraction":{"properties":{"type":{"type":"string","const":"generic","title":"Type","default":"generic"},"document":{"$ref":"#/components/schemas/DocumentInfo"},"key_values":{"items":{"$ref":"#/components/schemas/KeyValue"},"type":"array","title":"Key Values"},"tables":{"items":{"$ref":"#/components/schemas/TableOut"},"type":"array","title":"Tables"},"needs_review":{"type":"boolean","title":"Needs Review"},"review_reasons":{"items":{"type":"string"},"type":"array","title":"Review Reasons"}},"type":"object","required":["document","key_values","tables","needs_review","review_reasons"],"title":"GenericExtraction"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Health":{"properties":{"status":{"type":"string","const":"ok","title":"Status"},"service":{"type":"string","title":"Service"},"version":{"type":"string","title":"Version"},"engine_ready":{"type":"boolean","title":"Engine Ready"}},"type":"object","required":["status","service","version","engine_ready"],"title":"Health"},"InvoiceExtraction":{"properties":{"type":{"type":"string","const":"invoice","title":"Type","default":"invoice"},"document":{"$ref":"#/components/schemas/DocumentInfo"},"vendor":{"$ref":"#/components/schemas/ExtractedField_str_"},"customer":{"$ref":"#/components/schemas/ExtractedField_str_"},"invoice_number":{"$ref":"#/components/schemas/ExtractedField_str_"},"issue_date":{"$ref":"#/components/schemas/ExtractedField_date_"},"due_date":{"$ref":"#/components/schemas/ExtractedField_date_"},"currency":{"$ref":"#/components/schemas/ExtractedField_str_"},"line_items":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array","title":"Line Items"},"subtotal":{"$ref":"#/components/schemas/ExtractedField_Annotated_Decimal__PlainSerializer__"},"tax":{"$ref":"#/components/schemas/ExtractedField_Annotated_Decimal__PlainSerializer__"},"total":{"$ref":"#/components/schemas/ExtractedField_Annotated_Decimal__PlainSerializer__"},"checks":{"items":{"$ref":"#/components/schemas/Check"},"type":"array","title":"Checks"},"needs_review":{"type":"boolean","title":"Needs Review","default":false},"review_reasons":{"items":{"type":"string"},"type":"array","title":"Review Reasons"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"},"llm_used":{"type":"boolean","title":"Llm Used","default":false}},"type":"object","required":["document"],"title":"InvoiceExtraction"},"KeyValue":{"properties":{"key":{"type":"string","title":"Key"},"value":{"type":"string","title":"Value"},"source":{"anyOf":[{"$ref":"#/components/schemas/SourceRef"},{"type":"null"}]},"method":{"type":"string","title":"Method"}},"type":"object","required":["key","value","method"],"title":"KeyValue"},"LineItem":{"properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"qty":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Qty"},"unit_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Unit Price"},"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","default":0.0},"source":{"anyOf":[{"$ref":"#/components/schemas/SourceRef"},{"type":"null"}]},"notes":{"items":{"type":"string"},"type":"array","title":"Notes"}},"type":"object","title":"LineItem"},"Quality":{"properties":{"ocr_used":{"type":"boolean","title":"Ocr Used"},"ocr_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ocr Score"},"layout_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Layout Score"},"parse_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Parse Score"},"grade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Grade"},"lowest_grade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lowest Grade"}},"type":"object","required":["ocr_used"],"title":"Quality"},"SourceRef":{"properties":{"page":{"type":"integer","title":"Page"},"bbox":{"anyOf":[{"$ref":"#/components/schemas/BBox"},{"type":"null"}]}},"type":"object","required":["page"],"title":"SourceRef"},"TableOut":{"properties":{"index":{"type":"integer","title":"Index"},"num_rows":{"type":"integer","title":"Num Rows"},"num_cols":{"type":"integer","title":"Num Cols"},"header":{"items":{"type":"string"},"type":"array","title":"Header"},"rows":{"items":{"items":{"type":"string"},"type":"array"},"type":"array","title":"Rows"},"source":{"anyOf":[{"$ref":"#/components/schemas/SourceRef"},{"type":"null"}]}},"type":"object","required":["index","num_rows","num_cols","header","rows"],"title":"TableOut"},"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"}}}}