Files API — Upload and Manage Knowledge Base Documents

The Files API is an OpenAI-compatible interface for adding documents to your Ragen knowledge base and managing them over time. Files are scoped to the project the API key is bound to — every file you upload through the API lands in that project’s knowledge base and becomes immediately available to the Chat Completions endpoint once processing completes.

Endpoints

POST   /v1/files
GET    /v1/files
GET    /v1/files/{id}
DELETE /v1/files/{id}

Authentication:

Authorization: Bearer YOUR_API_KEY

Upload a file

POST /v1/files — multipart form body.

file

required

The document to upload. Supported formats: PDF, DOCX, PPTX, XLSX, CSV, TXT, MD, EPUB, SRT, and common image types.

string

default:"knowledge_base"

Accepts knowledge_base (default) or assistants (OpenAI alias — treated identically). Use either value; both result in the file being added to your project’s knowledge base.

The response returns immediately with status: "uploaded". The parse and embed pipeline runs asynchronously in the background.

{
  "id": "file-abc123",
  "object": "file",
  "bytes": 12345,
  "created_at": 1744664400,
  "filename": "handbook.pdf",
  "purpose": "knowledge_base",
  "status": "uploaded",
  "status_details": null
}

Processing status

Poll GET /v1/files/{id} until the file reaches a terminal status:

`status`	Meaning
`uploaded`	File is stored; the parse + embed pipeline hasn’t finished yet
`processed`	Parse and embed both completed — the file is available to chat
`error`	Parsing or embedding failed — check `status_details` for more information

Do not query the knowledge base for content from a file while its status is still uploaded. The file won’t appear in retrieval results until it reaches processed.

List files

GET /v1/files — returns a paginated list of files in your project.

integer

default:"20"

Number of files to return per page. Between 1 and 100.

string

Cursor for pagination — the file ID to start after (returns files created after the given ID).

string

Filter results by purpose (knowledge_base or assistants).

Returns { "object": "list", "data": [...] } with OpenAI file objects.

Retrieve a file

GET /v1/files/{id} — returns the full OpenAI file object for a single file, or 404 if it doesn’t exist in your project.

Delete a file

DELETE /v1/files/{id} — removes the file and all associated data, including any embeddings from the vector store. Returns:

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

Examples

TypeScript SDK
Python (openai SDK)
curl

import { Ragen } from '@webamigos/ragen-sdk-ts';
import { createReadStream } from 'fs';

const ragen = new Ragen({ apiKey: process.env.RAGEN_API_KEY });

// Upload a file
const file = await ragen.files.create({
  file: createReadStream('handbook.pdf'),
  purpose: 'knowledge_base',
});
console.log(file.id, file.status); // file-abc123 uploaded

// Poll until processed
async function waitUntilProcessed(fileId: string) {
  while (true) {
    const f = await ragen.files.retrieve(fileId);
    if (f.status === 'processed') return f;
    if (f.status === 'error') throw new Error(`Processing failed: ${f.status_details}`);
    await new Promise((r) => setTimeout(r, 2000)); // wait 2 s between polls
  }
}

const processed = await waitUntilProcessed(file.id);
console.log('Ready:', processed.filename);

import os
import time
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["RAGEN_BASE_URL"],
    api_key=os.environ["RAGEN_API_KEY"],
)

# Upload
with open("handbook.pdf", "rb") as f:
    file = client.files.create(file=f, purpose="assistants")
print(file.id, file.status)

# Poll until processed
while file.status == "uploaded":
    time.sleep(2)
    file = client.files.retrieve(file.id)

if file.status == "error":
    raise RuntimeError(f"Processing failed: {file.status_details}")

print("Ready:", file.filename)

# List all files
for f in client.files.list():
    print(f.id, f.filename, f.status)

# Upload
curl -X POST $RAGEN_BASE_URL/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "purpose=knowledge_base"

# Poll status
curl $RAGEN_BASE_URL/files/file-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# List files
curl "$RAGEN_BASE_URL/files?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Delete
curl -X DELETE $RAGEN_BASE_URL/files/file-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Error codes

Status	`type`	Cause
`400`	`invalid_request_error`	Missing `file` field, unsupported `purpose`, or validation failure
`401`	`authentication_error`	Missing or invalid API key
`404`	`not_found_error`	File doesn’t exist or isn’t in the caller’s project
`413`	`invalid_request_error`	File exceeds the per-file, organization, or project storage limit
`429`	`rate_limit_error`	Upload rate limit exceeded
`502`	`api_error`	Storage or background worker failure during upload

Rate limits

Endpoint	Limit
`POST /v1/files`	10 requests / minute
`GET /v1/files`, retrieve, delete	20 requests / minute

Getting Started

Endpoints

SDKs & Tools

Files API — Upload and Manage Knowledge Base Documents

Endpoints

Upload a file

Processing status

List files

Retrieve a file

Delete a file

Examples

Error codes

Rate limits

​Endpoints

​Upload a file

​Processing status

​List files

​Retrieve a file

​Delete a file

​Examples

​Error codes

​Rate limits

Endpoints

Upload a file

Processing status

List files

Retrieve a file

Delete a file

Examples

Error codes

Rate limits