{ "openapi": "3.1.0", "info": { "title": "Unsiloed AI Document Processing API", "description": "A comprehensive API for document processing, extraction, and analysis using AI-powered tools", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://prod.visionapi.unsiloed.ai", "description": "Production server" } ], "security": [ { "apiKeyAuth": [] } ], "paths": { "/v2/extract": { "post": { "summary": "Extract Data", "description": "Extract structured data from PDF documents using custom schemas with vision-language models. Supports multiple model tiers, optional bounding box citations, and intelligent page selection for large documents.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "pdf_file": { "type": "string", "format": "binary", "description": "The PDF file to process for data extraction. Maximum file size: 500MB. Either pdf_file or file_url must be provided." }, "file_url": { "type": "string", "description": "URL to a PDF file to process. Either pdf_file or file_url must be provided." }, "schema_data": { "type": "string", "description": "JSON schema defining the structure and fields to extract from the document. Example: {\"type\":\"object\",\"properties\":{\"invoice_number\":{\"type\":\"string\",\"description\":\"The invoice number\"}},\"required\":[\"invoice_number\"],\"additionalProperties\":false}" }, "model": { "type": "string", "description": "Model tier to use for extraction. Options: alpha, beta, gamma (default, recommended), delta", "default": "gamma", "enum": [ "alpha", "beta", "gamma", "delta" ] }, "enable_citations": { "type": "boolean", "description": "Return bounding box coordinates for extracted values", "default": false }, "high_accuracy_mode": { "type": "boolean", "description": "Enable an agentic verification and validation layer for higher accuracy/consistency. Extracted values are independently cross-checked against the document and uncertain fields are re-verified and reconciled before the result is returned. Slower. Off by default; set true to enable per request.", "default": false }, "schema_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schema Name", "description": "Optional name identifying the schema, stored with the job for traceability." }, "detect_pii": { "type": "boolean", "title": "Detect Pii", "description": "Run a pre-flight PII check before extraction. If PII is found at or above pii_block_severity, no extraction job is created and the endpoint returns HTTP 200 with \"status\": \"pii_blocked\" and \"blocked\": true in the body.", "default": false }, "pii_engine": { "type": "string", "title": "Pii Engine", "description": "PII detection engine: 'standard' (default) or 'advanced' (higher precision).", "default": "standard", "enum": [ "standard", "advanced" ] }, "pii_block_severity": { "type": "string", "title": "Pii Block Severity", "description": "Severity threshold that blocks extraction when detect_pii is enabled: 'any', 'low', 'medium', or 'high'.", "default": "high", "enum": [ "any", "low", "medium", "high" ] } }, "required": [ "schema_data" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique identifier for the extraction job" }, "status": { "type": "string", "description": "Initial job status (typically 'queued')" }, "message": { "type": "string", "description": "Descriptive message about the job creation" }, "quota_remaining": { "type": "number", "description": "Number of Credits remaining in your quota" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/batch/cite": { "post": { "summary": "Batch Cite", "description": "Process multiple PDF documents with structured data extraction using JSON schema", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "pdf_files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Array of PDF files to process" }, "schema_data": { "type": "string", "description": "JSON schema defining the structure of data to extract. Example: {\"type\":\"object\",\"properties\":{\"invoice_number\":{\"type\":\"string\",\"description\":\"The invoice number\"}},\"required\":[\"invoice_number\"],\"additionalProperties\":false}" }, "batch_size": { "type": "integer", "default": 10, "description": "Number of PDFs to process in each batch" } }, "required": [ "pdf_files", "schema_data" ] }, "encoding": { "pdf_files": { "contentType": "application/pdf", "explode": true, "style": "form" } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch_id": { "type": "string", "description": "Unique identifier for the batch processing job" }, "status": { "type": "string", "description": "Initial batch job status" }, "total_files": { "type": "number", "description": "Total number of files submitted for processing" }, "message": { "type": "string", "description": "Status message about the batch job creation" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/parse": { "post": { "summary": "Parse Document", "description": "Parse and chunk PDF, Image (PNG, JPEG, TIFF, BMP) and Office Documents (DOCX, XLSX, PPTX) documents into semantic sections using advanced AI-powered strategies", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Supported file types: PDFs, Images (PNG, JPEG, TIFF, BMP) and Office Documents (DOCX, XLSX, PPTX)" }, "use_high_resolution": { "type": "boolean", "description": "Whether to use high-resolution images for cropping and post-processing (default: false)", "default": false }, "segmentation_method": { "type": "string", "description": "Document segmentation strategy", "enum": [ "smart_layout_detection", "page_by_page" ], "default": "smart_layout_detection" }, "ocr_mode": { "type": "string", "description": "OCR processing strategy", "enum": [ "auto_ocr", "full_ocr" ], "default": "auto_ocr" }, "merge_tables": { "type": "boolean", "description": "Whether to merge adjacent table segments (default: false)", "default": false }, "segment_filter": { "type": "string", "description": "Filter output to include only specific segment types. Accepts comma-separated list (e.g., 'table', 'picture', 'table,picture') or 'all' for everything (default: 'all')", "default": "all" }, "xml_citation": { "type": "boolean", "description": "Enable citation extraction from PDF documents. Extracts structured bibliography and hyperlinks in-text citations in markdown output (default: false)", "default": false } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique identifier for the parsing job" }, "status": { "type": "string", "description": "Initial job status (typically 'Starting')" }, "file_name": { "type": "string", "description": "Name of the uploaded file" }, "created_at": { "type": "string", "description": "Timestamp when the job was created" }, "message": { "type": "string", "description": "Status message about the job creation" }, "quota_remaining": { "type": "number", "description": "Remaining page quota for the API key" }, "merge_tables": { "type": "boolean", "description": "Whether table merging is enabled" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/classify": { "post": { "summary": "Classify Document", "description": "Classify PDF and image documents into predefined categories", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "pdf_file": { "type": "string", "format": "binary", "description": "The document to classify: a PDF or an image (JPG, PNG, GIF, WebP, BMP, TIFF). Provide either pdf_file or file_url, not both. Maximum file size: 500MB." }, "file_url": { "type": "string", "description": "URL to a document to classify (PDF or image). Provide either pdf_file or file_url, not both." }, "categories": { "type": "string", "description": "JSON string containing an array of category objects with a required name. Example: [{\"name\":\"invoice\"},{\"name\":\"contract\"},{\"name\":\"receipt\"}]. A \"description\" key is accepted for compatibility but is not used by classification." } }, "required": [ "categories" ] } } } }, "responses": { "202": { "description": "Accepted - classification job started", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique identifier for the classification job" }, "status": { "type": "string", "description": "Current job status (typically 'processing')" }, "message": { "type": "string", "description": "Status message about the job" }, "quota_remaining": { "type": "number", "description": "Remaining API quota after this request" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/pdf-editor/edit/reparse": { "post": { "summary": "Edit PDF", "description": "Edit PDF documents by replacing text and images at specific bounding boxes with automatic re-parsing", "servers": [ { "url": "https://platformbackend.unsiloed.ai/api/v1", "description": "Platform Backend Development" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "PDF file to edit" }, "edit_request": { "type": "string", "description": "JSON string containing list of edit items with bounding box coordinates and replacement content" }, "image_files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Optional list of image files to upload and use for image replacements" } }, "required": [ "file", "edit_request" ] } } } }, "responses": { "200": { "description": "PDF edited successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the PDF edit operation was successful" }, "message": { "type": "string", "description": "Status message about the edit operation" }, "pdf_url": { "type": "string", "description": "URL of the edited PDF file (if upload_to_storage is true)" }, "original_size": { "type": "number", "description": "Size of the original PDF file in bytes" }, "edited_size": { "type": "number", "description": "Size of the edited PDF file in bytes" }, "items_processed": { "type": "number", "description": "Number of edit items that were processed" }, "reparsed": { "type": "boolean", "description": "Whether the edited PDF was submitted for re-parsing" }, "new_job_id": { "type": "string", "description": "New job ID for monitoring the re-parsing progress (if job_id was provided)" } } } } } }, "400": { "description": "Bad request - invalid file or edit request", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/parse/{job_id}": { "get": { "summary": "Get Parse Job Status", "description": "Check the status and retrieve results of parsing jobs", "parameters": [ { "in": "path", "name": "job_id", "schema": { "type": "string" }, "required": true, "description": "The unique identifier of the parsing job to check" } ], "responses": { "200": { "description": "Job status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique identifier for the parsing job" }, "status": { "type": "string", "description": "Current job status: Starting, Processing, Succeeded, or Failed" }, "created_at": { "type": "string", "description": "Timestamp when the job was created" }, "started_at": { "type": "string", "description": "Timestamp when processing started" }, "finished_at": { "type": "string", "description": "Timestamp when processing completed" }, "total_chunks": { "type": "number", "description": "Number of chunks in the document" }, "chunks": { "type": "array", "description": "Array of document chunks with detailed analysis" } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "array" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/jobs/{job_id}": { "get": { "summary": "Get Job Status", "description": "Check the status and progress of asynchronous processing jobs", "parameters": [ { "in": "path", "name": "job_id", "schema": { "type": "string" }, "required": true, "description": "The unique identifier of the job to check" } ], "responses": { "200": { "description": "Job status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current job status as stored, uppercase: QUEUED, PROCESSING, COMPLETED, or FAILED. Jobs flagged for human review carry the lowercase status \"review\"." }, "created_at": { "type": "string", "description": "Timestamp when the job was created" }, "id": { "type": "string", "description": "Unique identifier for the job" }, "updated_at": { "type": "string", "description": "Timestamp when the job was last updated" }, "error": { "type": "string", "description": "Error message if the job failed" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/jobs/{job_id}/result": { "get": { "summary": "Get Job Results", "description": "Retrieve the results of a completed processing job", "parameters": [ { "in": "path", "name": "job_id", "schema": { "type": "string" }, "required": true, "description": "The unique identifier of the job" } ], "responses": { "200": { "description": "Job results retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Job results object" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/classify/{job_id}": { "get": { "summary": "Get Classification Job Status", "description": "Check the status and progress of classification jobs and retrieve results", "parameters": [ { "in": "path", "name": "job_id", "schema": { "type": "string" }, "required": true, "description": "The unique identifier of the classification job" } ], "responses": { "200": { "description": "Classification job status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique identifier for the classification job" }, "status": { "type": "string", "description": "Current job status (queued, processing, completed, failed)" }, "progress": { "type": "string", "description": "Progress message" }, "error": { "type": "string", "description": "Error message if job failed" }, "result": { "type": "object", "description": "Classification results (only present when status is completed)", "properties": { "success": { "type": "boolean", "description": "Whether classification succeeded" }, "classification": { "type": "string", "description": "The classified category" }, "confidence": { "type": "number", "description": "Confidence score (0-1)" }, "total_pages": { "type": "number", "description": "Total number of pages" }, "processed_pages": { "type": "number", "description": "Number of pages processed" }, "page_results": { "type": "array", "description": "Per-page classification results", "items": { "type": "object", "properties": { "page": { "type": "number", "description": "Page number" }, "classification": { "type": "string", "description": "Classification for this page" }, "confidence": { "type": "number", "description": "Confidence score for this page" }, "success": { "type": "boolean", "description": "Whether this page was classified successfully" }, "raw_result": { "type": "string", "description": "The model's raw classification output for this page" } } } } } } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/org/get_usage": { "get": { "summary": "Get Organization Usage", "description": "Get organization usage information including current usage, monthly limit, and remaining quota", "servers": [ { "url": "https://platformbackend.unsiloed.ai/api/v1", "description": "Platform Backend" } ], "responses": { "200": { "description": "Usage information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "description": "Unique identifier for your organization" }, "org_name": { "type": "string", "description": "Name of your organization" }, "current_usage": { "type": "number", "description": "Number of credits used in the current billing cycle" }, "usage_limit": { "type": "number", "description": "Total usage limit (credits) for your organization" }, "remaining_quota": { "type": "number", "description": "Number of credits remaining in the current billing cycle" }, "last_billed_date": { "type": "string", "format": "date", "description": "Date of the last billing cycle reset (YYYY-MM-DD)" } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API key is required. Please provide 'api-key' in the request header." } } } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Organization not found" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/extract/{job_id}": { "get": { "summary": "Get Extraction Job Status", "description": "Check the status and retrieve results of extraction jobs", "parameters": [ { "in": "path", "name": "job_id", "schema": { "type": "string" }, "required": true, "description": "The unique identifier of the extraction job" } ], "responses": { "200": { "description": "Extraction job status and results retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Extraction job status and results" } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/splitter": { "post": { "summary": "Split Document", "description": "Split PDF documents by classifying pages into categories", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "PDF file to split. Either file or file_url must be provided." }, "file_url": { "type": "string", "description": "URL to a PDF file to split. Either file or file_url must be provided. Example: https://example.com/mixed_documents.pdf" }, "categories": { "type": "string", "description": "JSON string containing array of category objects with name and optional description. Example: [{\"name\":\"invoice\",\"description\":\"Business invoices with itemized charges\"},{\"name\":\"contract\",\"description\":\"Legal agreements and binding documents\"},{\"name\":\"report\"}]" }, "enable_reordering": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enable Reordering", "description": "Reorder pages within each category after classification, using content and page numbers to infer the logical order. Only applied to categories that match more than one page.", "default": false } }, "required": [ "categories" ] }, "encoding": { "file": { "contentType": "application/pdf" } } } } }, "responses": { "200": { "description": "Split job created", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique identifier for the splitting job" }, "status": { "type": "string", "description": "Current job status (typically 'processing')" }, "quota_remaining": { "type": "number", "description": "Remaining API quota after this request" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/splitter/{job_id}": { "get": { "summary": "Get Split Status", "description": "Check the status and retrieve results of document splitting jobs", "parameters": [ { "in": "path", "name": "job_id", "schema": { "type": "string" }, "required": true, "description": "The unique identifier of the splitting job" } ], "responses": { "200": { "description": "Split job status and results retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Unique identifier for the splitting job" }, "status": { "type": "string", "description": "Current job status (queued, processing, completed, failed)" }, "progress": { "type": "string", "description": "Progress message" }, "file_url": { "type": "string", "description": "Presigned download URL for the original uploaded file. Expires roughly an hour after the response is generated; re-issue this request for a fresh URL." }, "file_name": { "type": "string", "description": "Name of the original file" }, "parameters": { "type": "object", "description": "Job parameters", "properties": { "classes": { "type": "array", "description": "List of category names", "items": { "type": "string" } }, "category_descriptions": { "type": "object", "description": "Category descriptions map" }, "enable_reordering": { "type": "boolean", "description": "Whether pages were reordered within each category after classification" }, "page_count": { "type": "integer", "description": "Number of pages in the uploaded document" } } }, "result": { "type": "object", "description": "Split results (only present when status is completed)", "properties": { "success": { "type": "boolean", "description": "Whether splitting succeeded" }, "message": { "type": "string", "description": "Success/failure message" }, "files": { "type": "array", "description": "Array of split PDF files", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the split file" }, "path": { "type": "string", "description": "Relative path to the file" }, "type": { "type": "string", "description": "File type (always 'file')" }, "fileId": { "type": "string", "description": "Unique file identifier" }, "full_path": { "type": "string", "description": "Presigned download URL for the split file. Expires roughly an hour after the response is generated, so download the file straight away rather than storing the URL. Re-issue this request for a fresh URL." }, "confidence_score": { "type": "number", "description": "Classification confidence score (0-1)" } } } } } }, "error": { "type": "string", "description": "Error message if job failed" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "api-key" } } } }