> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload Document
> Upload a document to Chamelio's Core for processing. Documents are processed asynchronously and will be available in your organization's document repository.
## Endpoint
```
POST /core/upload
```
## Authentication
This endpoint requires authentication via API key. Include your API key in the `X-API-Key` header:
```bash theme={null}
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](#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`](/api-reference/endpoint/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
```bash cURL theme={null}
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"
}
]
}'
```
```python Python theme={null}
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())
```
```javascript JavaScript theme={null}
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`
```json theme={null}
{
"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](/api-reference/introduction#authentication-errors) section for details.
```json theme={null}
{
"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`](/api-reference/endpoint/core/document-types) to retrieve valid values.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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