Skip to main content
POST
https://app.commodityai.com
/
api
/
v1
/
documents
curl -X POST "https://app.commodityai.com/api/v1/documents" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -F "file=@/path/to/contract.pdf" \
  -F "workflow_id=abc12345-e89b-12d3-a456-426614174000" \
  -F 'metadata={"source_system": "SAP", "batch_id": "BATCH-2024-001"}' \
  -F "callback_url=https://your-system.com/webhooks/commodityai" \
  -F "priority=normal"

{
  "data": {
    "id": "doc-550e8400-e29b-41d4-a716-446655440000",
    "filename": "contract.pdf",
    "file_size": 245678,
    "mime_type": "application/pdf",
    "status": "queued",
    "workflow_id": "abc12345-e89b-12d3-a456-426614174000",
    "metadata": {
      "source_system": "SAP",
      "batch_id": "BATCH-2024-001"
    },
    "priority": "normal",
    "callback_url": "https://your-system.com/webhooks/commodityai",
    "submitted_at": "2024-01-22T14:30:00Z",
    "estimated_completion": "2024-01-22T14:32:00Z"
  }
}
Submits a document to the processing pipeline for classification, segmentation, and data extraction. Documents are processed asynchronously.

​
Request Body

​
file
file
required
The document file to process. Supported formats: PDF, PNG, JPG, JPEG, TIFF.
​
workflow_id
string
The workflow to process this document through. If omitted, the default workflow is used.
​
metadata
object
Optional metadata to attach to the document (e.g., source system, batch identifier)
​
callback_url
string
URL to receive a webhook notification when processing completes
​
priority
string
default:"normal"
Processing priority: low, normal, or high

​
Request Examples

curl -X POST "https://app.commodityai.com/api/v1/documents" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -F "file=@/path/to/contract.pdf" \
  -F "workflow_id=abc12345-e89b-12d3-a456-426614174000" \
  -F 'metadata={"source_system": "SAP", "batch_id": "BATCH-2024-001"}' \
  -F "callback_url=https://your-system.com/webhooks/commodityai" \
  -F "priority=normal"

​
Response

{
  "data": {
    "id": "doc-550e8400-e29b-41d4-a716-446655440000",
    "filename": "contract.pdf",
    "file_size": 245678,
    "mime_type": "application/pdf",
    "status": "queued",
    "workflow_id": "abc12345-e89b-12d3-a456-426614174000",
    "metadata": {
      "source_system": "SAP",
      "batch_id": "BATCH-2024-001"
    },
    "priority": "normal",
    "callback_url": "https://your-system.com/webhooks/commodityai",
    "submitted_at": "2024-01-22T14:30:00Z",
    "estimated_completion": "2024-01-22T14:32:00Z"
  }
}

​
Response Fields

​
data
object
The submitted document details

​
Supported File Formats

FormatMIME TypeMax Size
PDFapplication/pdf50 MB
PNGimage/png25 MB
JPG/JPEGimage/jpeg25 MB
TIFFimage/tiff50 MB

​
Processing Status

Documents progress through the following statuses:
StatusDescription
queuedDocument received and awaiting processing
processingDocument is being classified and extracted
completedProcessing finished successfully
failedProcessing failed (see error details)

​
Webhook Callback

When callback_url is provided, a POST request is sent upon completion: 
{
  "event": "document.processed",
  "document_id": "doc-550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "sources_created": 3,
  "records_created": 12,
  "processed_at": "2024-01-22T14:31:45Z"
}
For failed documents: 
{
  "event": "document.failed",
  "document_id": "doc-550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": {
    "code": "extraction_failed",
    "message": "Unable to extract data from document"
  },
  "failed_at": "2024-01-22T14:31:45Z"
}

​
Error Codes

StatusCodeDescription
400validation_errorInvalid request or unsupported file format
401unauthorizedInvalid or missing API key
404workflow_not_foundSpecified workflow does not exist
413file_too_largeFile exceeds maximum allowed size
422invalid_documentDocument is corrupted, password-protected, or unreadable
429rate_limit_exceededToo many requests (see Rate Limits)
500internal_errorInternal server error