Overview

Every agent has a private workspace directory on the local filesystem. The Agent Workspaces API lets you bulk-initialize that workspace, list its files, and read or write individual files. All paths are relative to the agent’s workspace and are guarded against directory traversal. The gateway rejects any path that is absolute, contains .., or includes backslashes or NUL bytes.

Base URL

Authentication

All requests must include a valid bearer token in the Authorization header.

File object

Endpoints

Initialize workspace

Creates the agent’s workspace directory and writes a batch of documents. Parent directories are created automatically. This endpoint lives in the main Agents router and is included here for completeness.

Request body

Example request

Example response

List workspace files

Recursively lists all files in the agent’s workspace.

Example request

Example response

Read a workspace file

Reads a single file as UTF-8 text.

Query parameters

Example request

Example response

Write a workspace file

Writes a file to the workspace. Parent directories are created as needed. Existing files are overwritten.

Request body

Example request

Example response

Path safety

The API rejects paths that:
  • Are absolute (start with / or a Windows drive letter).
  • Contain .. components.
  • Contain backslashes (\) or NUL bytes.
Attempts return 400 Bad Request with "error": "invalid_path".

Error codes