Skip to main content
POST
Upload File

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. Supported: PDF, DOC, DOCX, PPT, PPTX, XLSX, XLS, TXT, MD, HTML, CSV, JSON, XML, EML, MSG, images (JPEG, PNG, GIF, WebP, SVG)

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 | null

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 | null

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