Skip to main content

Agent Filesystem API

Read, write, and manage files in an agent’s persistent workspace.

Read File

Get the contents of a file.

Endpoint

GET /agent/:agentId/filesystem/files/:path*

Authentication

Requires JWT token or Platform API key.

Path Parameters

ParameterTypeDescription
agentIdstringAgent UUID
pathstringFile path in workspace

Example Request

curl -X GET https://api.app.shinzo.ai/agent/agt_abc123/filesystem/files/config/settings.json \
  -H "Authorization: Bearer <jwt_token>"

Response

{
  "path": "/config/settings.json",
  "content": "{\"debug\": true}",
  "size": 16,
  "modified_at": "2025-01-20T10:00:00Z"
}

Create File

Create a new file in the workspace.

Endpoint

POST /agent/:agentId/filesystem/files/:path*

Request Body

FieldTypeRequiredDescription
contentstringYesFile content
encodingstringNoContent encoding (utf-8 or base64)

Example Request

curl -X POST https://api.app.shinzo.ai/agent/agt_abc123/filesystem/files/data/output.txt \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, World!"}'

Response

{
  "path": "/data/output.txt",
  "size": 13,
  "created_at": "2025-01-20T10:00:00Z"
}

Update File

Update an existing file.

Endpoint

PUT /agent/:agentId/filesystem/files/:path*

Request Body

FieldTypeRequiredDescription
contentstringYesNew file content
encodingstringNoContent encoding

Delete File

Delete a file from the workspace.

Endpoint

DELETE /agent/:agentId/filesystem/files/:path*

Response

{
  "path": "/data/output.txt",
  "deleted_at": "2025-01-20T11:00:00Z"
}

List Directory

List contents of a directory.

Endpoint

GET /agent/:agentId/filesystem/directories/:path*

Example Request

curl -X GET https://api.app.shinzo.ai/agent/agt_abc123/filesystem/directories/src \
  -H "Authorization: Bearer <jwt_token>"

Response

{
  "path": "/src",
  "entries": [
    {
      "name": "index.js",
      "type": "file",
      "size": 1024,
      "modified_at": "2025-01-20T10:00:00Z"
    },
    {
      "name": "utils",
      "type": "directory",
      "modified_at": "2025-01-19T15:00:00Z"
    }
  ]
}

Create Directory

Create a new directory.

Endpoint

POST /agent/:agentId/filesystem/directories/:path*

Response

{
  "path": "/data/exports",
  "created_at": "2025-01-20T10:00:00Z"
}

Delete Directory

Delete a directory and its contents.

Endpoint

DELETE /agent/:agentId/filesystem/directories/:path*

Bulk Operations

Copy Files

POST /agent/:agentId/filesystem/operations/copy

Move Files

POST /agent/:agentId/filesystem/operations/move

Search Files

POST /agent/:agentId/filesystem/operations/search

Archive Operations

Create Archive

POST /agent/:agentId/filesystem/archives
Create a zip or tar archive from files.

Extract Archive

POST /agent/:agentId/filesystem/archives/extract
Extract an archive to a directory.

File Metadata

Get Metadata

GET /agent/:agentId/filesystem/metadata/:path*

Update Metadata

PATCH /agent/:agentId/filesystem/metadata/:path*
Update file permissions and metadata.