Primitives

File Storage

Per-tenant file storage for user uploads and agent-generated artifacts. Theazo handles per-user isolation, signed URLs, and storage metering.

Overview

AgentCo's users upload documents for agents to process — contracts, datasets, spreadsheets. Agents generate reports, screenshots, and data files that users download. Without Theazo file storage, AgentCo builds their own per-user upload/download pipeline with access controls.

Every file is scoped to a userId and tagged with a purpose so you can distinguish inputs from outputs from knowledge base documents.

Upload a file

upload.ts

import { Theazo } from class="cb-str">'theazo'

const theazo = new Theazo({ apiKey: class="cb-str">'th_live_...' })

// Upload a file for a user
const file = await theazo.files.upload({
  userId: class="cb-str">'user_123',
  file: pdfBuffer,
  filename: class="cb-str">'contract.pdf',
  purpose: class="cb-str">'agent_input',
})
// -> { id: 'file_abc', filename: 'contract.pdf', size: 2100000,
//      mimeType: 'application/pdf', purpose: 'agent_input', ... }

Files uploaded with purpose: 'agent_input' are available inside the agent's sandbox at /data/filename.

File purposes

Purpose	Description
`agent_input`	User uploads for agents to process (PDFs, CSVs, images)
`agent_output`	Files generated by agents (reports, screenshots, data exports)
`knowledge`	Documents ingested into the knowledge base for RAG

List files

list.ts

// List all files for a user
const files = await theazo.files.list({
  userId: class="cb-str">'user_123',
  purpose: class="cb-str">'agent_output',
})

// Filter by agent or session
const agentFiles = await theazo.files.list({
  agentId: class="cb-str">'agt_xyz',
})

const sessionFiles = await theazo.files.list({
  sessionId: class="cb-str">'ses_abc',
})

Get file metadata

get.ts

const file = await theazo.files.get(class="cb-str">'file_abc')
// -> {
//   id: 'file_abc',
//   filename: 'contract.pdf',
//   mimeType: 'application/pdf',
//   size: 2100000,
//   purpose: 'agent_input',
//   userId: 'user_123',
//   agentId: null,
//   sessionId: 'ses_abc',
//   createdAt: '2026-05-06T10:30:00Z'
// }

Download files

Use getUrl() to generate a time-limited signed URL for downloading. The URL expires after the specified duration.

download.ts

// Get a signed download URL (default: 1 hour)
const url = await theazo.files.getUrl(class="cb-str">'file_abc')

// Custom expiry
const url = await theazo.files.getUrl(class="cb-str">'file_abc', { expiresIn: class="cb-str">'24h' })
// -> 'https://storage.theazo.com/files/file_abc?token=...'

Delete files

delete.ts

await theazo.files.delete(class="cb-str">'file_abc')

API endpoints

Method	Endpoint	Description
`POST`	/v1/files	Upload a file
`GET`	/v1/files	List files (filter by userId, purpose, agentId)
`GET`	/v1/files/:id	Get file metadata
`GET`	/v1/files/:id/url	Get signed download URL
`DELETE`	/v1/files/:id	Delete a file

Agent integration

Files uploaded with agent_input purpose are automatically mounted in the agent's sandbox filesystem. Agent-generated files are captured with agent_output purpose and linked to the agent that created them.

agent-integration.ts

// Upload input for the agent
await theazo.files.upload({
  userId: class="cb-str">'user_123',
  file: csvBuffer,
  filename: class="cb-str">'leads.csv',
  purpose: class="cb-str">'agent_input',
})

// Agent processes the file in its sandbox
const result = await session.run(class="cb-str">'data_analyst', class="cb-str">'analyze leads.csv')

// Agent output files are auto-captured
const outputs = await theazo.files.list({
  userId: class="cb-str">'user_123',
  purpose: class="cb-str">'agent_output',
})

// Download the result
const url = await theazo.files.getUrl(outputs[class="cb-num">0].id)