Agent files

Overview

Each personal CREAO agent has a durable file space — the skill folder mounted into sandbox runs (for example SKILL.md plus supporting references, scripts, and templates). CREAO CLI can upload a file to an exact path, list those files, fetch a short-lived download URL, and delete a file. Together with Update an agent, this lets you write an agent’s whole skill folder on your machine and push it as is: skill_content sets SKILL.md, and each supporting file is uploaded to the path SKILL.md refers to. No agent run rewrites the files on the way in.

Get an agent with its files

Get an agent returns the same file list in files, each with a download_url, so one request covers the whole agent. Add include=file_content to also get the text of small UTF-8 files, such as scripts and Markdown, in content:

curl "https://developer.creao.ai/v1/agents/00000000-0000-4000-8000-000000000000?include=file_content" \
  -H "Authorization: Bearer cr_sk_your_key_here"

{
  "agent_id": "00000000-0000-4000-8000-000000000000",
  "name": "Equity Research Agent",
  "skill_content": "# Equity Research Agent",
  "files": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "analyze_filings.py",
      "mime_type": "text/x-python",
      "size_bytes": 2048,
      "sha256": "9f86d081...",
      "created_at": "2026-07-02T00:00:00.000Z",
      "download_url": "https://s3.example/analyze_filings.py?X-Amz-Signature=...",
      "download_url_expires_at": "2026-07-03T01:00:00.000Z",
      "content": "import json\n..."
    }
  ]
}

content is filled for text and code files up to 256 KB each, in list order, until the inlined text reaches 2 MB. Binary files, larger files, and files past that budget return content: null; download them from download_url. Without include=file_content, every content is null.

Upload a file

Send the file as multipart/form-data in the file field, and the relative path inside the agent in path:

curl -X POST https://developer.creao.ai/v1/agents/00000000-0000-4000-8000-000000000000/files \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -F "file=@references/style-guide.md" \
  -F "path=references/style-guide.md"

{
  "id": "66666666-6666-4666-8666-666666666666",
  "name": "references/style-guide.md",
  "mime_type": "text/markdown",
  "size_bytes": 3120,
  "sha256": "2c26b46b...",
  "created_at": "2026-10-21T00:00:00.000Z"
}

Folders are kept. A run sees the file at the same relative path in the agent’s folder, so a SKILL.md that says “read references/style-guide.md” finds it.
Uploading to a path that already holds a file replaces it and returns 200. A new file returns 201.
path defaults to the uploaded file name. curl -F "file=@references/style-guide.md" sends only style-guide.md as the name, so pass path for any file in a folder.
Characters outside the safe file-name set, such as spaces, become _. The response name is the stored path. .. segments are refused.
SKILL.md and config.yaml at the root are part of the agent definition. Set them with skill_content and config_content on Update an agent; uploading them returns AGENT_FILE_PATH_RESERVED. A SKILL.md inside a folder, such as skills/research/SKILL.md, is an ordinary file.
Each file can be up to 20 MB, and an agent holds at most 50 files, including SKILL.md.

Push a local agent folder

This script makes the agent match a local folder: it sets SKILL.md from the folder, uploads every other file to its relative path, and deletes files that are no longer in the folder.

AGENT_ID=00000000-0000-4000-8000-000000000000
API=https://developer.creao.ai/v1/agents/$AGENT_ID
AUTH="Authorization: Bearer cr_sk_your_key_here"
cd my-agent

jq -n --rawfile skill SKILL.md '{skill_content: $skill}' \
  | curl -sf -X PATCH "$API" -H "$AUTH" -H "Content-Type: application/json" -d @- > /dev/null

find . -type f ! -path '*/.*' ! -path ./SKILL.md ! -path ./config.yaml | sed 's|^\./||' | while read -r f; do
  curl -sf -X POST "$API/files" -H "$AUTH" -F "file=@$f" -F "path=$f" > /dev/null
done

curl -sf "$API/files" -H "$AUTH" | jq -r '.files[] | [.id, .name] | @tsv' \
  | while IFS=$'\t' read -r id name; do
      [ "$name" = SKILL.md ] || [ -f "$name" ] || curl -sf -X DELETE "$API/files/$id" -H "$AUTH" > /dev/null
    done

The next run of the agent uses the new files. The script skips hidden files such as .DS_Store, and it assumes local names are already safe (no spaces, quotes, parentheses, or &): a stored name that differs from the local one looks deleted and is removed. Every call counts toward the per-minute request limit, so pace a folder of more than about 25 files; see Rate limits.

List files

curl https://developer.creao.ai/v1/agents/00000000-0000-4000-8000-000000000000/files \
  -H "Authorization: Bearer cr_sk_your_key_here"

{
  "files": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "name": "SKILL.md",
      "mime_type": "text/markdown",
      "size_bytes": 1204,
      "sha256": "abc123...",
      "created_at": "2026-07-02T00:00:00.000Z"
    }
  ]
}

Agents are capped at 50 files, so this endpoint is not paginated. Listings include the auto-staged SKILL.md when present.

Download a file

curl https://developer.creao.ai/v1/agents/00000000-0000-4000-8000-000000000000/files/55555555-5555-4555-8555-555555555555 \
  -H "Authorization: Bearer cr_sk_your_key_here"

{
  "id": "55555555-5555-4555-8555-555555555555",
  "name": "notes.txt",
  "mime_type": "text/plain",
  "size_bytes": 12,
  "sha256": null,
  "created_at": "2026-07-02T00:00:00.000Z",
  "download_url": "https://s3.example/notes.txt?X-Amz-Signature=...",
  "download_url_expires_at": "2026-07-02T01:00:00.000Z"
}

download_url is a presigned URL that expires in 1 hour.

Delete a file

curl -X DELETE https://developer.creao.ai/v1/agents/00000000-0000-4000-8000-000000000000/files/55555555-5555-4555-8555-555555555555 \
  -H "Authorization: Bearer cr_sk_your_key_here"

{
  "deleted": true
}

Deleting SKILL.md is allowed. CREAO re-stages it automatically the next time the agent’s skill content is updated.

Errors

Code	When
`AGENT_NOT_FOUND`	Agent is missing, not personal, or not owned by the API key account
`FILE_NOT_FOUND`	File ID is unknown or does not belong to this agent
`INVALID_INPUT`	Bad UUID path param, a missing `file` field on upload, or an unknown `include` value on Get an agent
`INVALID_AGENT_FILE_PATH`	Upload `path` is empty, longer than 512 characters, or contains a `..` segment
`AGENT_FILE_PATH_RESERVED`	Upload `path` is `SKILL.md` or `config.yaml` at the root; use Update an agent instead
`AGENT_FILE_LIMIT_REACHED`	The agent already holds 50 files and the upload is not a replacement
`FILE_TOO_LARGE`	Uploaded file is larger than 20 MB
`TEAM_STORAGE_QUOTA_EXCEEDED`	The account has used all of its plan’s storage

See also the OpenAPI operations under Agent Files.

Get Started

Agents

Agent Memory

Product Profile

Agent Runs

Super Agent

Account

Workspaces

Workspace Files

Secrets

Skills

Rooms

Concepts

Agent files

Overview

Get an agent with its files

Upload a file

Push a local agent folder

List files

Download a file

Delete a file

Errors

​Overview

​Get an agent with its files

​Upload a file

​Push a local agent folder

​List files

​Download a file

​Delete a file

​Errors

Overview

Get an agent with its files

Upload a file

Push a local agent folder

List files

Download a file

Delete a file

Errors