Endpoint
Authentication
This endpoint requires authentication via API key. Include your API key in the X-API-Key header:
X-API-Key: ca_your_api_key_here
Request Body
The request body must be a JSON object with the following fields:
Required Fields
| Field | Type | Description |
|---|
file_name | string | Name of the file being uploaded (e.g., “contract.pdf”) |
file_extension | string | File extension indicating the document type. Supported values: pdf, docx, doc, txt, xlsx, xls, pptx, ppt |
file_content_base64 | string | Base64-encoded content of the file |
Optional Fields
| Field | Type | Description |
|---|
user_email | string | Email address of the user on whose behalf this document is being uploaded. If not provided, the document will be attributed to the API key creator |
attributes | array | List of metadata attributes to attach to the document. Each attribute contains name, data_type, and value |
field_overrides | array | List of pre-filled org field values that override the values Chamelio’s AI would otherwise extract. Each entry is a Document Field Override Object |
business_id | integer | Identifier of the business to associate the document with |
document_type_id | integer | Identifier of the document type to assign to the document. Must be a valid document type for your organization — retrieve available types via GET /core/document-types. An invalid value returns a 400 error |
override_on_duplicate | boolean | Whether to override an existing document if a duplicate is detected. Defaults to false |
Attribute Object
Each object in the attributes array contains:
| Field | Type | Description |
|---|
name | string | Name of the metadata field (e.g., “contract_type”, “effective_date”) |
data_type | string | Type of the field. Allowed values: text, date, number, boolean, link |
value | string | Value of the metadata field (formatted as a string regardless of data_type) |
Document Field Override Object
Each object in the field_overrides array sets a pre-filled value for a specific org field, overriding the value Chamelio’s AI extraction would produce:
| Field | Type | Required | Description |
|---|
org_field_id | integer | Yes | Identifier of the org field to set |
field_value_type | string | Yes | Type of the field value. Allowed values: text, enum, number, boolean, date, clause |
value | string or null | No | The value to set. May be a string, number, boolean, or date; omit or set to null to leave empty |
is_verified | boolean | No | Whether the provided value should be marked as verified. Defaults to false |
Request Example
curl -X POST https://platform.chamelio.ai/core/upload \
-H "X-API-Key: ca_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"file_name": "master_services_agreement.pdf",
"file_extension": "pdf",
"file_content_base64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9...",
"user_email": "john.doe@example.com",
"attributes": [
{
"name": "contract_type",
"data_type": "text",
"value": "Master Services Agreement"
},
{
"name": "effective_date",
"data_type": "date",
"value": "2025-01-01"
},
{
"name": "contract_value",
"data_type": "number",
"value": "250000"
},
{
"name": "auto_renew",
"data_type": "boolean",
"value": "true"
},
{
"name": "vendor_website",
"data_type": "link",
"value": "https://vendor.example.com"
}
]
}'
import requests
import base64
# Read and encode file
with open("contract.pdf", "rb") as f:
file_content = base64.b64encode(f.read()).decode('utf-8')
url = "https://platform.chamelio.ai/core/upload"
headers = {
"X-API-Key": "ca_your_api_key_here",
"Content-Type": "application/json"
}
payload = {
"file_name": "master_services_agreement.pdf",
"file_extension": "pdf",
"file_content_base64": file_content,
"user_email": "john.doe@example.com",
"attributes": [
{
"name": "contract_type",
"data_type": "text",
"value": "Master Services Agreement"
},
{
"name": "effective_date",
"data_type": "date",
"value": "2025-01-01"
}
]
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
const fs = require('fs');
// Read and encode file
const fileBuffer = fs.readFileSync('contract.pdf');
const fileContent = fileBuffer.toString('base64');
const response = await fetch('https://platform.chamelio.ai/core/upload', {
method: 'POST',
headers: {
'X-API-Key': 'ca_your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
file_name: 'master_services_agreement.pdf',
file_extension: 'pdf',
file_content_base64: fileContent,
user_email: 'john.doe@example.com',
attributes: [
{
name: 'contract_type',
data_type: 'text',
value: 'Master Services Agreement'
},
{
name: 'effective_date',
data_type: 'date',
value: '2025-01-01'
}
]
})
});
const data = await response.json();
console.log(data);
Response
Success Response
Status Code: 200 OK
{
"document_processing_id": 12345,
"file_name": "master_services_agreement.pdf",
"status": "success"
}
Response Fields
| Field | Type | Description |
|---|
document_processing_id | integer | Unique identifier for the document processing job. Use this ID to track the document’s processing status |
file_name | string | Name of the uploaded file |
status | string | Upload status (always “success” for successful uploads) |
Error Responses
401 Unauthorized
Returned when authentication fails. See the authentication errors section for details.
{
"detail": "Invalid API key"
}
400 Bad Request
Returned when document_type_id is not a valid document type for your organization. Use GET /core/document-types to retrieve valid values.
{
"detail": "document_type_id 42 is not valid for this org. See GET /core/document-types for available document types."
}
422 Validation Error
Returned when the request body is invalid or missing required fields.
{
"detail": [
{
"loc": ["body", "file_name"],
"msg": "field required",
"type": "value_error.missing"
}
]
}
500 Internal Server Error
Returned when the document upload fails due to a server error.
{
"detail": "Failed to upload document: Internal processing error"
}
Notes
Documents are processed asynchronously. After a successful upload, the document will be queued for processing. Processing time varies depending on document size and complexity.
File content must be properly base64-encoded. Ensure you encode the binary file content, not the file path or text representation.
Use Cases
This endpoint is useful for:
- Automated document ingestion - Integrate document uploads into your existing workflows
- Bulk document processing - Upload multiple documents programmatically
- System integration - Connect your document management system with Chamelio
- Custom metadata - Attach structured metadata to documents during upload for better organization and searchability