defineFile.
Define a file
files/playbook.ts
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):
/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:
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 withfiles. 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:
For structured, queryable data (CRM objects, tables) use
models instead — files are for unstructured knowledge.

