Skip to main content
Files are unstructured resources — documents, PDFs, transcripts, playbooks. When attached to an agent or tool, their content is chunked and embedded so it can be retrieved by meaning (semantic search), not just keywords. You upload one from a local path with defineFile.

Define a file

files/playbook.ts
The content is uploaded on deploy; the file handle can then be referenced as an agent resource.

Supported types

Using files in agents

Attach files (or folders of files) as agent resources. The agent searches them with vector similarity — a query for “pricing concerns” surfaces content about “cost objections” even without the exact words. Add a description to steer how the agent prioritizes the content.

From the CLI

Storing files at runtime

Files are also plain storage. A worker, app or script can write a file at a path, read it back, list a folder and hand out a link, without the file being indexed for search or mirrored into your context. Paths are folders plus a name (reports/2026-q3/summary.pdf); writing to a path creates any missing folders and overwrites the file already there.
put accepts any size: large files go straight to storage in parts. From a worker, use createCargoObjects (it reads the worker’s CARGO_API_TOKEN):
Writes from a worker are capped at 100 MB each. Over HTTP the same files are objects, addressed by path under /v1/content/objects/: PUT, GET (add ?meta=true for details instead of bytes) and DELETE on /v1/content/objects/reports/2026-q3/summary.pdf, and GET /v1/content/objects?prefix=reports/ to list. An object is a content file, so /v1/content/files/<uuid> reaches the same file by uuid. Overwriting a file keeps its own settings unless you pass new ones. Files uploaded with upload, in the app or with defineFile keep today’s defaults: indexed and mirrored. Links. url returns a signed link anyone can open until it expires, for up to 3 hours. A public file also has a stable link, https://api.getcargo.io/files/public/<uuid>/<name>. That link works without auth for as long as the file stays public, and it stops working the moment you make the file private or delete it.

In a workflow

writeFile, readFile and getFileUrl are native workflow nodes, so a play can generate a file and send the link on:
writeFile takes text, or base64 bytes with encoding: "base64", up to 10 MB, and returns the file’s path, a signed url valid for an hour and, for a public file, its publicUrl. A preview run writes nothing. readFile returns the content as text or base64, up to 10 MB.

In a project

defineFile takes the same options, set only when you need them:
Changing index or mirrorToContext uploads the file again in place, with the same uuid. Changing visibility updates it in place.

Letting an agent write

List files and folders on an agent with files. A folder with readOnly: false also gives the agent a write tool (capability_file_write) that saves text it produces into that folder (unindexed, private) and returns a link:
The agent can write only inside the folders you list, never elsewhere in the workspace.
For structured, queryable data (CRM objects, tables) use models instead — files are for unstructured knowledge.