Sign in
files

Upload a file

Uploads a file that can be used with vector stores for RAG. Files are uploaded as multipart/form-data with the following fields:

  • file: The file to upload (required)
  • purpose: The intended purpose of the file (default: "assistants")
  • owner_type: Owner type - "organization", "project", or "user" (required)
  • owner_id: Owner ID (required)
post/api/v1/files

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v1/files
  • Auth: HTTP bearer

Response

File uploaded successfully

bytesinteger required
content_typestring nullable

Hadrian Extension: MIME content type of the file

created_atstring date-time required
expires_atstring date-time nullable
filenamestring required
idstring required

File ID (serialized with file- prefix for OpenAI compatibility)

objectstring

Object type identifier (always "file" for API compatibility)

owner_idstring uuid required

Hadrian Extension: Owner ID for multi-tenancy

owner_type'organization' | 'team' | 'project' | 'user' required

Owner type for collections (organization, team, project, or user)

purpose'assistants' | 'batch' | 'fine_tune' | 'vision' required

File purpose (OpenAI Files API compatible)

status'uploaded' | 'processed' | 'error' required

File upload status (OpenAI Files API compatible)

Tracks the state of a file uploaded via the Files API. Note: This status is deprecated in OpenAI's API but still returned for compatibility.

State Transitions

┌──────────┐     validation      ┌───────────┐
│ uploaded │ ──────────────────▶ │ processed │
└──────────┘     success         └───────────┘
      │
      │ validation failed
      ▼
┌──────────┐
│  error   │
└──────────┘
  • uploaded: File received and stored, initial validation pending
  • processed: File validated and ready for use (e.g., adding to vector stores)
  • error: File validation failed (see status_details for reason)

Important

This is the file upload status, not the vector store processing status. When a file is added to a vector store, its processing status is tracked separately via VectorStoreFileStatus.

status_detailsstring nullable

Example response

{
  "id": "file-550e8400-e29b-41d4-a716-446655440000"
}

Changes

No recorded changes to this operation across all 16 revisions of this API.