Skip to main content

​
Files API

The Files API provides managed file storage (Storage v2). Upload files to Castari’s managed storage and attach them to agents. Access via client.files: 
const client = new CastariClient({ apiKey: '...' });
const files = client.files;

​
Methods

​
upload(file, filename, options?)

Upload a file to managed storage. 
const result = await client.files.upload(file, filename, options?);
Parameters:
NameTypeRequiredDescription
fileBlobYesThe file data
filenamestringYesFile name
options.descriptionstringNoFile description
options.tagsstring[]NoTags for organization
Returns: Promise<FileUploadResponse> Example: 
const file = new Blob(['Hello, world!'], { type: 'text/plain' });
const result = await client.files.upload(file, 'hello.txt', {
  description: 'Greeting file',
  tags: ['example'],
});
console.log(result.file_id);

​
list(options?)

List files in managed storage. 
const result = await client.files.list(options?);
Parameters:
NameTypeRequiredDescription
options.limitnumberNoMax results (default: 50)
options.offsetnumberNoPagination offset
options.scope'user' | 'agent' | 'session'NoFilter by scope
options.tagsstring[]NoFilter by tags
options.searchstringNoSearch by filename
Returns: Promise<ManagedFileList>

​
get(fileId)

Get file metadata. 
const file = await client.files.get(fileId);
Returns: Promise<ManagedFile>

​
update(fileId, options)

Update file metadata. 
const file = await client.files.update(fileId, options);
Returns: Promise<ManagedFile>

​
delete(fileId)

Delete a file from managed storage. 
await client.files.delete(fileId);
Returns: Promise<void>

​
download(fileId)

Download a file. 
const response = await client.files.download(fileId);
Returns: Promise<Response>

​
getUsage()

Get storage usage statistics. 
const usage = await client.files.getUsage();
Returns: Promise<StorageUsage> Example: 
const usage = await client.files.getUsage();
console.log(`${usage.total_files} files, ${usage.total_mb} MB used (${usage.usage_percent}%)`);
Response type: 
interface StorageUsage {
  total_files: number;
  total_bytes: number;
  total_mb: number;
  limit_mb: number;
  usage_percent: number;
}

​
getUploadUrl(filename, sizeBytes, options?)

Get a presigned upload URL for large files. 
const presigned = await client.files.getUploadUrl(filename, sizeBytes, options?);
Returns: Promise<PresignedUpload>

​
confirmUpload(fileId, sha256Hash)

Confirm a presigned upload completed successfully. 
const file = await client.files.confirmUpload(fileId, sha256Hash);
Returns: Promise<ManagedFile>

​
attachToAgent(agentSlug, options)

Attach a file to an agent. 
const agentFile = await client.files.attachToAgent(agentSlug, options);
Parameters:
NameTypeRequiredDescription
agentSlugstringYesThe agent’s slug
options.fileIdstringYesFile ID to attach
options.mountPathstringNoPath inside the sandbox
options.readOnlybooleanNoMount as read-only
Returns: Promise<AgentFile>

​
listAgentFiles(agentSlug)

List files attached to an agent. 
const result = await client.files.listAgentFiles(agentSlug);
Returns: Promise<AgentFileList>

​
detachFromAgent(agentSlug, fileId)

Detach a file from an agent. 
await client.files.detachFromAgent(agentSlug, fileId);
Returns: Promise<void>

​
See Also