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



{/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */}

<ApiEndpoint>
  <ApiEndpointMain>
    ## List a folder [#list-a-folder]

    <ApiEndpointHeader method="GET" path="/v1/sessions/{session_id}/files" scope="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.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="path" type="string">
        The folder's path, relative to the team's files. Omit for the root.
      </ApiParam>

      <ApiParam name="cursor" type="string">
        The `next_cursor` of the previous page.
      </ApiParam>

      <ApiParam name="limit" type="integer">
        Entries per page, 1 to 2000. Default 1000.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    **Returns** a [FileListing](#filelisting) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The folder's entries.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "session": "sess_0a843Y2wTmED2k3FJPP56X",
      "path": "reports",
      "data": [
        {
          "object": "file_entry",
          "name": "weekly.md",
          "path": "reports/weekly.md",
          "type": "file",
          "size": 4182,
          "modified_at": "2026-10-12T07:06:40.000Z",
          "ignored": false,
          "linked": false,
          "protected": false
        }
      ],
      "has_more": false,
      "next_cursor": null,
      "truncated": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Create an empty file [#create-an-empty-file]

    <ApiEndpointHeader method="POST" path="/v1/sessions/{session_id}/files" scope="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.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="path" type="string" required="true" />
    </ApiParams>

    **Returns** a [File](#file) object.

    <ApiParams title="Responses">
      <ApiParam name="201">
        The new file.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"path":"reports/q4-plan.md"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ path: 'reports/q4-plan.md' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"path": "reports/q4-plan.md"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 201"
    {
      "object": "file",
      "path": "reports/weekly.md",
      "size": 4182,
      "modified_at": "2026-10-12T07:06:40.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Delete a file or a folder [#delete-a-file-or-a-folder]

    <ApiEndpointHeader method="DELETE" path="/v1/sessions/{session_id}/files" scope="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.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="path" type="string" required="true">
        The file's path, relative to the team's files (`notes/plan.md`).
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Responses">
      <ApiParam name="204">
        Deleted.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X DELETE "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files?path=reports%2Fweekly.md" \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files?path=reports%2Fweekly.md', {
          method: 'DELETE',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(res.status);
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.delete(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files?path=reports%2Fweekly.md",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Deleted.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Read a text file [#read-a-text-file]

    <ApiEndpointHeader method="GET" path="/v1/sessions/{session_id}/files/content" scope="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.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="path" type="string" required="true">
        The file's path, relative to the team's files (`notes/plan.md`).
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    **Returns** a [FileContent](#filecontent) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The file and its text.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md" \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "file",
      "path": "reports/weekly.md",
      "size": 4182,
      "modified_at": "2026-10-12T07:06:40.000Z",
      "encoding": "utf-8",
      "content": "# Weekly brief\n\n## Pricing\n\nThree competitors changed their pricing.\n"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Write a text file [#write-a-text-file]

    <ApiEndpointHeader method="PUT" path="/v1/sessions/{session_id}/files/content" scope="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.

    <ApiParams title="Path parameters">
      <ApiParam name="session_id" type="string" required="true">
        A session id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="path" type="string" required="true">
        The file's path, relative to the team's files (`notes/plan.md`).
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="content" type="string" required="true">
        UTF-8 text, at most 2 MB.
      </ApiParam>

      <ApiParam name="base_modified_at" type="string (date-time)">
        The `modified_at` you last read; a newer file is refused (409).
      </ApiParam>
    </ApiParams>

    **Returns** a [File](#file) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The file as written.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X PUT "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md" \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"content":"# Q4 plan\n\nShip the pricing page.\n"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md', {
          method: 'PUT',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ content: '# Q4 plan\n\nShip the pricing page.\n' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.put(
            "https://api-hq.aiworkforceone.com/v1/sessions/sess_0a843Y2wTmED2k3FJPP56X/files/content?path=reports%2Fweekly.md",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"content": "# Q4 plan\n\nShip the pricing page.\n"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "file",
      "path": "reports/weekly.md",
      "size": 4182,
      "modified_at": "2026-10-12T07:06:40.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### FileListing [#filelisting]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="session" type="string" />

      <ApiParam name="path" type="string" />

      <ApiParam name="data" type="array of FileEntry" />

      <ApiParam name="has_more" type="boolean" />

      <ApiParam name="next_cursor" type="string or null" />

      <ApiParam name="truncated" type="boolean" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The FileListing object"
    {
      "object": "list",
      "session": "sess_0a843Y2wTmED2k3FJPP56X",
      "path": "reports",
      "data": [
        {
          "object": "file_entry",
          "name": "weekly.md",
          "path": "reports/weekly.md",
          "type": "file",
          "size": 4182,
          "modified_at": "2026-10-12T07:06:40.000Z",
          "ignored": false,
          "linked": false,
          "protected": false
        }
      ],
      "has_more": false,
      "next_cursor": null,
      "truncated": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### File [#file]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="path" type="string" />

      <ApiParam name="size" type="integer" />

      <ApiParam name="modified_at" type="string (date-time)" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The File object"
    {
      "object": "file",
      "path": "reports/weekly.md",
      "size": 4182,
      "modified_at": "2026-10-12T07:06:40.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### FileContent [#filecontent]

    <ApiParams title="Attributes" />
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The FileContent object"
    {
      "object": "file",
      "path": "reports/weekly.md",
      "size": 4182,
      "modified_at": "2026-10-12T07:06:40.000Z",
      "encoding": "utf-8",
      "content": "# Weekly brief\n\n## Pricing\n\nThree competitors changed their pricing.\n"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
