Documentation Index
Fetch the complete documentation index at: https://docs.castari.com/llms.txt
Use this file to discover all available pages before exploring further.
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?);
| Name | Type | Required | Description |
|---|
file | Blob | Yes | The file data |
filename | string | Yes | File name |
options.description | string | No | File description |
options.tags | string[] | No | Tags for organization |
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?);
| Name | Type | Required | Description |
|---|
options.limit | number | No | Max results (default: 50) |
options.offset | number | No | Pagination offset |
options.scope | 'user' | 'agent' | 'session' | No | Filter by scope |
options.tags | string[] | No | Filter by tags |
options.search | string | No | Search by filename |
Promise<ManagedFileList>
get(fileId)
Get file metadata.
const file = await client.files.get(fileId);
Promise<ManagedFile>
update(fileId, options)
Update file metadata.
const file = await client.files.update(fileId, options);
Promise<ManagedFile>
delete(fileId)
Delete a file from managed storage.
await client.files.delete(fileId);
Promise<void>
download(fileId)
Download a file.
const response = await client.files.download(fileId);
Promise<Response>
getUsage()
Get storage usage statistics.
const usage = await client.files.getUsage();
Promise<StorageUsage>
Example:
const usage = await client.files.getUsage();
console.log(`${usage.total_files} files, ${usage.total_mb} MB used (${usage.usage_percent}%)`);
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?);
Promise<PresignedUpload>
confirmUpload(fileId, sha256Hash)
Confirm a presigned upload completed successfully.
const file = await client.files.confirmUpload(fileId, sha256Hash);
Promise<ManagedFile>
attachToAgent(agentSlug, options)
Attach a file to an agent.
const agentFile = await client.files.attachToAgent(agentSlug, options);
| Name | Type | Required | Description |
|---|
agentSlug | string | Yes | The agent’s slug |
options.fileId | string | Yes | File ID to attach |
options.mountPath | string | No | Path inside the sandbox |
options.readOnly | boolean | No | Mount as read-only |
Promise<AgentFile>
listAgentFiles(agentSlug)
List files attached to an agent.
const result = await client.files.listAgentFiles(agentSlug);
Promise<AgentFileList>
detachFromAgent(agentSlug, fileId)
Detach a file from an agent.
await client.files.detachFromAgent(agentSlug, fileId);
Promise<void>
See Also
