AI Workforce OneHQDocs

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

GET/v1/sessions/{session_id}/files
Permission files:read

One 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.

Path parameters
session_idstringrequired

A session id.

Query parameters
pathstring

The folder's path, relative to the team's files. Omit for the root.

cursorstring

The next_cursor of the previous page.

limitinteger

Entries per page, 1 to 2000. Default 1000.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The folder's entries.

Other

An RFC 9457 problem.

Create an empty file

POST/v1/sessions/{session_id}/files
Permission files:write

Never 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.

Path parameters
session_idstringrequired

A session id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
pathstringrequired

Returns a File object.

Responses
201

The new file.

Other

An RFC 9457 problem.

Delete a file or a folder

DELETE/v1/sessions/{session_id}/files
Permission files:write

A 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.

Path parameters
session_idstringrequired

A session id.

Query parameters
pathstringrequired

The file's path, relative to the team's files (notes/plan.md).

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
204

Deleted.

Other

An RFC 9457 problem.

Read a text file

GET/v1/sessions/{session_id}/files/content
Permission files:read

The 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.

Path parameters
session_idstringrequired

A session id.

Query parameters
pathstringrequired

The file's path, relative to the team's files (notes/plan.md).

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The file and its text.

Other

An RFC 9457 problem.

Write a text file

PUT/v1/sessions/{session_id}/files/content
Permission files:write

Creates 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.

Path parameters
session_idstringrequired

A session id.

Query parameters
pathstringrequired

The file's path, relative to the team's files (notes/plan.md).

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
contentstringrequired

UTF-8 text, at most 2 MB.

base_modified_atstring (date-time)

The modified_at you last read; a newer file is refused (409).

Returns a File object.

Responses
200

The file as written.

Other

An RFC 9457 problem.

Objects

FileListing

Attributes
objectstring
sessionstring
pathstring
dataarray of FileEntry
has_moreboolean
next_cursorstring or null
truncatedboolean

File

Attributes
objectstring
pathstring
sizeinteger
modified_atstring (date-time)

FileContent

Attributes