Files
The files on an AI team's disk, addressed through one of its sessions. Paths are relative to the team's files; a path that leaves them is refused. Reads are masked like the terminal.
List a folder
/v1/sessions/{session_id}/filesfiles:readOne folder's entries, paged with cursor. No path lists the team's root.
On an AI team that turned on Protected files, a key that lacks files:protected.read (or whose person lacks it) sees each protected file or folder as one entry with protected: true and no size, and listing inside one is 403 protected_path.
session_idstringrequiredA session id.
pathstringThe folder's path, relative to the team's files. Omit for the root.
cursorstringThe
next_cursorof the previous page.limitintegerEntries per page, 1 to 2000. Default 1000.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a FileListing object.
200The folder's entries.
OtherAn RFC 9457 problem.
Create an empty file
/v1/sessions/{session_id}/filesfiles:writeNever replaces an existing file (409). Write its content with PUT /files/content.
On an AI team that turned on Protected files, changing a protected path (or a folder that contains one) needs files:protected.write on the key and its person: 403 protected_path otherwise.
A service key cannot change the agent configuration at the root (.claude/, .codex/, CLAUDE.md, AGENTS.md, CLAUDE.local.md, AGENTS.override.md, .mcp.json, or a linked folder reaching them): 403 agent_config_protected.
session_idstringrequiredA session id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
pathstringrequired
Returns a File object.
201The new file.
OtherAn RFC 9457 problem.
Delete a file or a folder
/v1/sessions/{session_id}/filesfiles:writeA folder is deleted with everything in it. Template-protected files cannot be deleted.
On an AI team that turned on Protected files, changing a protected path (or a folder that contains one) needs files:protected.write on the key and its person: 403 protected_path otherwise.
A service key cannot change the agent configuration at the root (.claude/, .codex/, CLAUDE.md, AGENTS.md, CLAUDE.local.md, AGENTS.override.md, .mcp.json, or a linked folder reaching them): 403 agent_config_protected.
session_idstringrequiredA session id.
pathstringrequiredThe file's path, relative to the team's files (
notes/plan.md).
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
204Deleted.
OtherAn RFC 9457 problem.
Read a text file
/v1/sessions/{session_id}/files/contentfiles:readThe file's text, with any of the team's secret values replaced by [REDACTED], as in the
terminal. A binary file is refused (415).
On an AI team that turned on Protected files, a key that lacks files:protected.read (or whose person lacks it) is refused a protected file with 403 protected_path, also when the path is a link to it, and gets 409 runner_needs_update while the team's Cloud Computer runs an older image.
session_idstringrequiredA session id.
pathstringrequiredThe file's path, relative to the team's files (
notes/plan.md).
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a FileContent object.
200The file and its text.
OtherAn RFC 9457 problem.
Write a text file
/v1/sessions/{session_id}/files/contentfiles:writeCreates or replaces the file's text (at most 2 MB). Pass base_modified_at from your last
read to be refused (409) if it changed since. Writing [REDACTED] back over a secret is
refused. Template-protected files are read-only.
On an AI team that turned on Protected files, changing a protected path (or a folder that contains one) needs files:protected.write on the key and its person: 403 protected_path otherwise.
A service key cannot change the agent configuration at the root (.claude/, .codex/, CLAUDE.md, AGENTS.md, CLAUDE.local.md, AGENTS.override.md, .mcp.json, or a linked folder reaching them): 403 agent_config_protected.
session_idstringrequiredA session id.
pathstringrequiredThe file's path, relative to the team's files (
notes/plan.md).
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
contentstringrequiredUTF-8 text, at most 2 MB.
base_modified_atstring (date-time)The
modified_atyou last read; a newer file is refused (409).
Returns a File object.
200The file as written.
OtherAn RFC 9457 problem.
Objects
FileListing
objectstringsessionstringpathstringdataarray of FileEntryhas_morebooleannext_cursorstring or nulltruncatedboolean
File
objectstringpathstringsizeintegermodified_atstring (date-time)