Files API

Upload and manage files for creating cartridges from your own data.

Overview

The Files API allows you to upload documents that can be used to train custom cartridges. These files serve as the corpus for self-study training, enabling you to create cartridges that efficiently compress and serve your specific data - whether it's research papers, documentation, codebases, or knowledge bases.

OpenAI Compatibility: Our Files API follows the OpenAI Files API specification, making it a drop-in replacement for existing OpenAI-compatible workflows while adding cartridge training capabilities.

Upload File

POST /api/v1/files

Upload a file that can be used to train cartridges or provide additional context. Uploaded files can be referenced when creating training jobs or chat completions.

Request Parameters

ParameterTypeRequiredDescription
filefileYesThe file to upload (multipart/form-data)
purposestringYesPurpose: "cartridge-training" or "assistants"

Supported File Types

.txt
.pdf
.md
.json
.jsonl
.csv

Response Format

{
  "id": "file-abc123",
  "object": "file",
  "bytes": 120000,
  "created_at": 1699999999,
  "filename": "research_paper.pdf",
  "purpose": "cartridge-training",
  "status": "uploaded",
  "status_details": null
}

Example Request (cURL)

curl /api/v1/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "purpose=cartridge-training" \
  -F "file=@research_paper.pdf"

Python Example

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="/api/v1"
)

# Upload a file
file = client.files.create(
    file=open("research_paper.pdf", "rb"),
    purpose="cartridge-training"
)

print(f"Uploaded file ID: {file.id}")
print(f"Filename: {file.filename}")
print(f"Size: {file.bytes} bytes")

List Files

GET /api/v1/files

Retrieve a list of all files that have been uploaded to your organization.

Query Parameters

ParameterTypeDescription
purposestringFilter by purpose (optional)

Response Format

{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "file",
      "bytes": 120000,
      "created_at": 1699999999,
      "filename": "research_paper.pdf",
      "purpose": "cartridge-training"
    },
    {
      "id": "file-def456",
      "object": "file",
      "bytes": 85000,
      "created_at": 1699999888,
      "filename": "documentation.md",
      "purpose": "cartridge-training"
    }
  ]
}

Example Request

curl /api/v1/files \
  -H "Authorization: Bearer YOUR_API_KEY"

Python Example

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="/api/v1"
)

# List all files
files = client.files.list()

for file in files.data:
    print(f"{file.id}: {file.filename} ({file.bytes} bytes)")

Retrieve File

GET /api/v1/files/{file_id}

Retrieve information about a specific file by its ID.

Response Format

{
  "id": "file-abc123",
  "object": "file",
  "bytes": 120000,
  "created_at": 1699999999,
  "filename": "research_paper.pdf",
  "purpose": "cartridge-training",
  "status": "processed",
  "status_details": null
}

Example Request

curl /api/v1/files/file-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Python Example

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="/api/v1"
)

# Retrieve file info
file = client.files.retrieve("file-abc123")

print(f"Filename: {file.filename}")
print(f"Status: {file.status}")
print(f"Bytes: {file.bytes}")

Delete File

DELETE /api/v1/files/{file_id}

Delete a file from your organization. This operation is permanent and cannot be undone.

Warning: Deleting a file that is being used by active cartridges may affect inference performance. Make sure the file is no longer needed before deletion.

Response Format

{
  "id": "file-abc123",
  "object": "file",
  "deleted": true
}

Example Request

curl /api/v1/files/file-abc123 \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY"

Python Example

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="/api/v1"
)

# Delete file
result = client.files.delete("file-abc123")

if result.deleted:
    print(f"File {result.id} deleted successfully")

Retrieve File Content

GET /api/v1/files/{file_id}/content

Download the content of a previously uploaded file.

Example Request

curl /api/v1/files/file-abc123/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o downloaded_file.pdf

Python Example

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="/api/v1"
)

# Download file content
content = client.files.content("file-abc123")

# Save to disk
with open("downloaded_file.pdf", "wb") as f:
    f.write(content.read())

Best Practices

File Organization

Use descriptive filenames and keep track of file IDs. Group related files by purpose (e.g., all training data for a specific domain).

Format Optimization

Plain text formats (.txt, .md, .json) typically work best for cartridge training. PDFs are supported but may require additional processing time.

File Size Limits

Maximum file size is 512MB per file. For larger corpora, split into multiple files or use compression techniques.

Lifecycle Management

Regularly audit and delete unused files to optimize storage costs and keep your workspace organized.

Common Use Cases

Research Papers

Upload academic papers to create cartridges that can answer questions about research methodologies, findings, and citations.

Documentation

Compress technical documentation into cartridges for fast retrieval and question-answering without reprocessing context on every request.

Knowledge Bases

Transform FAQs, wikis, and internal knowledge bases into efficient cartridges for customer support and employee assistance.

Code Repositories

Upload code files to create cartridges that understand your codebase for code review, documentation, and assistance.

Related Documentation