Skip to main content
The Files API allows you to upload, manage, and organize files that can be used in knowledge bases. Files serve as data sources for agent retrieval and knowledge augmentation.

​
Key Features

  • File Upload: Support for multiple file formats
  • File Management: List, organize, and delete files
  • Metadata Tracking: File types, sizes, and processing status
  • Bulk Operations: Efficient handling of multiple files
  • Search & Filtering: Find files by name, type, or tags

​
Authentication

All endpoints require authentication using your API key:
  • API Key: x-api-key: <key>

​
Available Endpoints

List Files

Retrieve all accessible files

Upload File

Upload a new file to the system

Get File

Retrieve file details and metadata

Delete File

Remove a file from the system

Bulk Operations

Perform operations on multiple files

​
Supported File Types

  • PDF: .pdf
  • Word: .doc, .docx
  • Text: .txt, .md
  • Rich Text: .rtf

​
File Processing Pipeline

  1. Upload: File uploaded to secure storage
  2. Validation: Format and content verification
  3. Processing: Text extraction and analysis
  4. Indexing: Preparation for knowledge base integration
  5. Ready: Available for use in collections

​
File Status States

File is being uploaded to the system
File is processed and ready for use
File is archived but still accessible
File is marked for deletion
Processing failed - check error details

​
File Organization

​
Tags

Organize files with custom tags:
  • Project-based: project:website, project:mobile
  • Content-type: manual, policy, faq
  • Department: hr, engineering, sales

​
Search & Filtering

Find files efficiently:
  • By name: Partial filename matching
  • By type: Filter by document, image, etc.
  • By status: Active, archived, or error states
  • By tags: Multiple tag filtering
Use consistent tagging strategies to improve file organization and retrieval.

​
File Metadata

Each file includes comprehensive metadata:
​
id
string
Unique file identifier
​
original_filename
string
Original name of the uploaded file
​
file_type
string
Categorized file type (document, image, etc.)
​
size_bytes
integer
File size in bytes
​
status
string
Current processing status
​
tags
array
Associated tags for organization

​
Usage in Knowledge Bases

Files can be:
  • Added to collections: Grouped with related files
  • Processed for retrieval: Text extracted and indexed
  • Used by agents: Referenced in knowledge base queries
  • Updated or replaced: Maintain current information
Files must be added to collections before they can be used in knowledge bases.