{"openapi":"3.0.3","info":{"title":"Tuko PDF Extraction API","version":"1.0.0","description":"Synchronous developer endpoints powered by Firecrawl PDF Inspector 1.12.0, Firecrawl's open-source Rust parsing engine. Inspect PDFs, extract Markdown or text, route selected pages through English or Malay OCR, and return native-text tables as structured rows. Tuko hosts and operates this API; Firecrawl supplies the underlying parser library. The current public API has no authentication, SLA, reserved capacity, or contractual data-processing terms; use it for approved low-volume development and human-reviewed workflows.","contact":{"name":"Tuko.my","url":"https://www.tuko.my/feedback"},"license":{"name":"Tuko.my Terms of Use","url":"https://www.tuko.my/terms"}},"servers":[{"url":"https://www.tuko.my","description":"Production"}],"externalDocs":{"description":"PDF Extraction API integration guide, use cases, and operational limits","url":"https://www.tuko.my/guides/pdf-extraction-api-guide"},"security":[],"x-parser-engine":{"name":"Firecrawl PDF Inspector","packageName":"@firecrawl/pdf-inspector","version":"1.12.0","repository":"https://github.com/firecrawl/pdf-inspector"},"tags":[{"name":"PDF extraction","description":"Inspect a PDF and return document signals with Markdown or text content."},{"name":"PDF tables","description":"Return each detected native-text table as a separate structured object."}],"paths":{"/api/v1/pdf/extract":{"get":{"tags":["PDF extraction"],"summary":"Get extraction endpoint usage","operationId":"getPdfExtractionUsage","responses":{"200":{"description":"Human-readable endpoint discovery data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointUsage"}}}}}},"post":{"tags":["PDF extraction"],"summary":"Inspect and extract a PDF","description":"Uploads one PDF for synchronous inspection and content extraction. Set `ocr=auto` to recognize up to five pages that the native-text inspection flags for OCR. Page selections are 1-indexed.","operationId":"extractPdf","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PdfExtractionRequest"},"encoding":{"file":{"contentType":"application/pdf"}}}}},"responses":{"200":{"description":"PDF inspection and extraction completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfExtractionResponse"},"example":{"success":true,"document":{"filename":"report.pdf","title":"Quarterly Operations Report","type":"TextBased","pageCount":12,"confidence":0.98,"processingTimeMs":184},"layout":{"isComplex":true,"pagesWithTables":[4,8],"pagesWithColumns":[2],"hasEncodingIssues":false},"ocr":{"required":false,"pages":[],"reasonsByPage":[],"processed":false,"language":null,"results":[],"remainingPages":[],"skippedPages":[],"failedPages":[]},"output":{"format":"markdown","content":"# Quarterly Operations Report\n\nExtracted content..."}}}}},"400":{"description":"The multipart request is missing a required field or contains an invalid option.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Invalid page selection: 0"}}}},"413":{"description":"The uploaded PDF is larger than 15 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"The PDF exceeds the 15 MB upload limit."}}}},"415":{"description":"The uploaded file does not have a valid PDF signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"The uploaded file is not a valid PDF."}}}},"422":{"description":"The PDF could not be processed, for example because it is encrypted, corrupted, or unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Failed to inspect the PDF.","details":"The PDF may be encrypted, corrupted, or unsupported."}}}}}}},"/api/v1/pdf/tables":{"get":{"tags":["PDF tables"],"summary":"Get table endpoint usage","operationId":"getPdfTableUsage","responses":{"200":{"description":"Human-readable endpoint discovery data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointUsage"}}}}}},"post":{"tags":["PDF tables"],"summary":"Extract native-text PDF tables","description":"Uploads one PDF and returns each detected native-text table independently. Scanned or image-only tables are not OCRed by this endpoint. Page selections are 1-indexed.","operationId":"extractPdfTables","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PdfTableRequest"},"encoding":{"file":{"contentType":"application/pdf"}}}}},"responses":{"200":{"description":"Table extraction completed, including when no tables are detected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfTablesResponse"},"example":{"success":true,"document":{"filename":"supplier-quotes.pdf","pageCount":3},"tableCount":1,"pagesWithTables":[2],"tables":[{"page":2,"index":1,"headers":["Supplier","Unit price","Lead time"],"rows":[["Alpha Sdn Bhd","RM 24.00","7 days"]],"markdown":"| Supplier | Unit price | Lead time |\n| --- | --- | --- |\n| Alpha Sdn Bhd | RM 24.00 | 7 days |","csv":"Supplier,Unit price,Lead time\r\nAlpha Sdn Bhd,RM 24.00,7 days"}]}}}},"400":{"description":"The multipart request is missing a required field or contains an invalid option.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Invalid page selection: 0"}}}},"413":{"description":"The uploaded PDF is larger than 15 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"The PDF exceeds the 15 MB upload limit."}}}},"415":{"description":"The uploaded file does not have a valid PDF signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"The uploaded file is not a valid PDF."}}}},"422":{"description":"The PDF could not be processed, for example because it is encrypted, corrupted, or unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Failed to inspect the PDF.","details":"The PDF may be encrypted, corrupted, or unsupported."}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false],"example":false},"error":{"type":"string"},"details":{"type":"string"}}},"EndpointUsage":{"type":"object","required":["name","endpoint","method","contentType","limit","parameters","engine"],"properties":{"name":{"type":"string"},"endpoint":{"type":"string"},"method":{"type":"string","enum":["POST"]},"contentType":{"type":"string","enum":["multipart/form-data"]},"limit":{"type":"string","example":"15 MB"},"parameters":{"type":"object","additionalProperties":{"type":"string"}},"engine":{"$ref":"#/components/schemas/ParserEngine"},"documentation":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"example":{"type":"string"},"response":{"type":"string"}}},"PdfExtractionRequest":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"A valid PDF file no larger than 15 MB."},"format":{"type":"string","enum":["markdown","text","json"],"default":"markdown","description":"The content representation recorded in `output.format`. Every HTTP response is JSON."},"pages":{"type":"string","example":"","description":"Optional 1-indexed page numbers and inclusive ranges, for example `1,3,5-8`."},"ocr":{"type":"string","enum":["auto","never"],"default":"never","description":"`auto` OCRs up to five pages flagged by native-text inspection."},"lang":{"type":"string","enum":["eng","msa","eng+msa"],"default":"eng","description":"OCR language: English, Malay, or both."}}},"ParserEngine":{"type":"object","required":["name","packageName","version","repository"],"properties":{"name":{"type":"string","example":"Firecrawl PDF Inspector"},"packageName":{"type":"string","example":"@firecrawl/pdf-inspector"},"version":{"type":"string","example":"1.12.0"},"repository":{"type":"string","format":"uri","example":"https://github.com/firecrawl/pdf-inspector"}}},"PdfTableRequest":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"A valid native-text PDF file no larger than 15 MB."},"pages":{"type":"string","example":"","description":"Optional 1-indexed page numbers and inclusive ranges, for example `2-6`."}}},"DocumentInfo":{"type":"object","required":["filename","title","type","pageCount","confidence","processingTimeMs"],"properties":{"filename":{"type":"string"},"title":{"type":"string","nullable":true},"type":{"type":"string","enum":["TextBased","Scanned","ImageBased","Mixed"]},"pageCount":{"type":"integer","minimum":0},"confidence":{"type":"number","minimum":0,"maximum":1},"processingTimeMs":{"type":"integer","minimum":0}}},"LayoutInfo":{"type":"object","required":["isComplex","pagesWithTables","pagesWithColumns","hasEncodingIssues"],"properties":{"isComplex":{"type":"boolean"},"pagesWithTables":{"$ref":"#/components/schemas/PageNumbers"},"pagesWithColumns":{"$ref":"#/components/schemas/PageNumbers"},"hasEncodingIssues":{"type":"boolean"}}},"PageNumbers":{"type":"array","items":{"type":"integer","minimum":1}},"PageOcrReasons":{"type":"object","required":["page","reasons"],"properties":{"page":{"type":"integer","minimum":1},"reasons":{"type":"array","items":{"type":"string"}}}},"OcrPageResult":{"type":"object","required":["page","text","confidence"],"properties":{"page":{"type":"integer","minimum":1},"text":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":100}}},"OcrInfo":{"type":"object","required":["required","pages","reasonsByPage","processed","language","results","remainingPages","skippedPages","failedPages"],"properties":{"required":{"type":"boolean"},"pages":{"$ref":"#/components/schemas/PageNumbers"},"reasonsByPage":{"type":"array","items":{"$ref":"#/components/schemas/PageOcrReasons"}},"processed":{"type":"boolean"},"language":{"type":"string","enum":["eng","msa","eng+msa",null],"nullable":true},"results":{"type":"array","items":{"$ref":"#/components/schemas/OcrPageResult"}},"remainingPages":{"$ref":"#/components/schemas/PageNumbers"},"skippedPages":{"$ref":"#/components/schemas/PageNumbers"},"failedPages":{"$ref":"#/components/schemas/PageNumbers"}}},"PdfOutput":{"type":"object","required":["format","content"],"properties":{"format":{"type":"string","enum":["markdown","text","json"]},"content":{"type":"string"}}},"PdfExtractionResponse":{"type":"object","required":["success","document","layout","ocr","output"],"properties":{"success":{"type":"boolean","enum":[true],"example":true},"document":{"$ref":"#/components/schemas/DocumentInfo"},"layout":{"$ref":"#/components/schemas/LayoutInfo"},"ocr":{"$ref":"#/components/schemas/OcrInfo"},"output":{"$ref":"#/components/schemas/PdfOutput"}}},"PdfTable":{"type":"object","required":["page","index","headers","rows","markdown","csv"],"properties":{"page":{"type":"integer","minimum":1},"index":{"type":"integer","minimum":1},"headers":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"markdown":{"type":"string"},"csv":{"type":"string"}}},"PdfTablesResponse":{"type":"object","required":["success","document","tableCount","pagesWithTables","tables"],"properties":{"success":{"type":"boolean","enum":[true],"example":true},"document":{"type":"object","required":["filename","pageCount"],"properties":{"filename":{"type":"string"},"pageCount":{"type":"integer","minimum":0,"description":"Number of pages included in this extraction response."}}},"tableCount":{"type":"integer","minimum":0},"pagesWithTables":{"$ref":"#/components/schemas/PageNumbers"},"tables":{"type":"array","items":{"$ref":"#/components/schemas/PdfTable"}}}}}}}