Skip to main content
POST
/
v1
/
files
Upload File
curl --request POST \
  --url https://api.cuadra.ai/v1/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form 'resource_type=<string>' \
  --form 'resource_id=<string>'
{
  "id": "file_abc123",
  "filename": "document.pdf",
  "contentType": "application/pdf",
  "sizeBytes": 1048576,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb924",
  "status": "uploaded",
  "isDuplicate": false,
  "storageCharged": 1048576,
  "createdAt": "2025-01-17T12:00:00Z",
  "associations": [
    {
      "resourceType": "chat",
      "resourceId": "chat_xyz789",
      "createdAt": "2025-01-17T12:00:00Z"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

JWT token from Stytch B2B authentication (magic link, SSO, or M2M)

Headers

​
Idempotency-Key
string | null

Body

multipart/form-data
​
file
file
required

File to upload (PDF, DOCX, XLSX, TXT, MD, CSV, JSON)

​
resource_type
string | null

Resource type: chat or dataset

​
resource_id
string | null

ID of the resource to associate with.

Response

File uploaded successfully

File response schema - COMPOSITE SCHEMA. Combines data from multiple sources for API simplicity: - FileEntity: id, filename, created_at (logical file) - FileContent: sha256, size_bytes, content_type, status, processed_at (physical content) - Computed: isDuplicate, storageCharged (deduplication logic) - Relationships: associations (file-resource links) Used for GET /v1/files/{id} and POST /v1/files responses. Deduplication info: - isDuplicate: Whether this file reuses existing content - storageCharged: Actual storage bytes charged (0 for duplicates) - sha256: Content hash for deduplication tracking

​
id
string
required

Unique file identifier

Example:

"file_abc123"

​
filename
string
required

Original filename

Example:

"document.pdf"

​
contentType
string
required

MIME type of the file

Example:

"application/pdf"

​
sizeBytes
integer
required

File size in bytes

Required range: x >= 0
Example:

1048576

​
sha256
string
required

SHA256 hash of file content (for deduplication)

Example:

"abc123def456..."

​
status
enum<string>
required

Processing status

Available options:
uploading,
uploaded,
processing,
ready,
error,
failed
Example:

"ready"

​
isDuplicate
boolean
required

Whether this file reuses existing content (no storage charge)

Example:

false

​
storageCharged
integer
required

Actual storage bytes charged (0 for duplicates)

Required range: x >= 0
Example:

1048576

​
createdAt
string<date-time>
required

File upload timestamp

Example:

"2025-01-17T10:00:00Z"

​
processingStatus
ProcessingStatus · object

Detailed processing status

​
processedAt
string<date-time> | null

When file processing completed

Example:

"2025-01-17T10:02:30Z"

​
associations
FileAssociationOut · object[] | null

Resources this file is associated with (included when expanded with ?expand[]=associations)

​
source
string
default:api

Request origin: api, m2m, connector

Examples:

"api"

"m2m"

"connector"

​
sourceDetail
string | null

Specific source: dashboard, google_drive, notion, etc.

Example:

"dashboard"

​
connectorMetadata
ConnectorMetadata · object

Metadata from external connector (Google Drive, Notion, etc.). Only present for connector-synced files.