> ## 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 Knowledge Center for asynchronous processing, automatic classification, and inclusion in your 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`](https://docs.chamelio.ai/api-reference/endpoint/core/document-types). An invalid value returns a `400` error |
| `document_title` | string | Title to give the document instead of the one Chamelio's AI generates. Leading and trailing whitespace is trimmed; a blank value falls back to the AI-generated title |
| `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",
    "document_title": "Acme Master Services Agreement",
    "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",
    "document_title": "Acme Master Services Agreement",
    "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}
import fs from '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',
    document_title: 'Acme Master Services Agreement',
    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](https://docs.chamelio.ai/api-reference/api-keys.md#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`](https://docs.chamelio.ai/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

> [!NOTE]
>
> Documents are processed asynchronously. After a successful upload, the document will be queued for processing. Processing time varies depending on document size and complexity.

> [!WARNING]
>
> 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
