Skip to main content

Endpoint

POST /core/upload

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

FieldTypeDescription
file_namestringName of the file being uploaded (e.g., “contract.pdf”)
file_extensionstringFile extension indicating the document type. Supported values: pdf, docx, doc, txt, xlsx, xls, pptx, ppt
file_content_base64stringBase64-encoded content of the file

Optional Fields

FieldTypeDescription
user_emailstringEmail 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
attributesarrayList of metadata attributes to attach to the document. Each attribute contains name, data_type, and value
field_overridesarrayList 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_idintegerIdentifier of the business to associate the document with
document_type_idintegerIdentifier 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_duplicatebooleanWhether to override an existing document if a duplicate is detected. Defaults to false

Attribute Object

Each object in the attributes array contains:
FieldTypeDescription
namestringName of the metadata field (e.g., “contract_type”, “effective_date”)
data_typestringType of the field. Allowed values: text, date, number, boolean, link
valuestringValue 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:
FieldTypeRequiredDescription
org_field_idintegerYesIdentifier of the org field to set
field_value_typestringYesType of the field value. Allowed values: text, enum, number, boolean, date, clause
valuestring or nullNoThe value to set. May be a string, number, boolean, or date; omit or set to null to leave empty
is_verifiedbooleanNoWhether 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

FieldTypeDescription
document_processing_idintegerUnique identifier for the document processing job. Use this ID to track the document’s processing status
file_namestringName of the uploaded file
statusstringUpload 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