Filesystem Management

Overview

Every agent on the Shinzo Platform has a persistent workspace — an isolated filesystem where it can store configuration, data, and generated artifacts. The Filesystem API gives you full programmatic access to read, write, search, and organize files within any agent’s workspace. All filesystem endpoints follow the pattern:

/v1/agent/:agentId/filesystem/...

File and directory paths are specified as wildcard parameters in the URL. For example, to read a file at workspace/config.json, you would call:

GET /v1/agent/:agentId/filesystem/files/workspace/config.json

File Operations

Read a File

Retrieve the contents of a file from an agent’s workspace:

curl -X GET "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/files/workspace/config.json" \
  -H "Authorization: Bearer YOUR_TOKEN"

You can request the response in utf-8 (default) or base64 encoding by passing the encoding query parameter. Use base64 for binary files such as images or compiled assets.

Create a File

Create a new file in the agent workspace:

curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/files/workspace/notes.txt" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "These are my notes.",
    "encoding": "utf-8",
    "overwrite": false
  }'

Parameter	Type	Required	Default	Description
`content`	string	✅	—	File content
`encoding`	enum	❌	`"utf-8"`	`"utf-8"` or `"base64"`
`overwrite`	boolean	❌	`false`	Whether to overwrite an existing file at the same path

Update a File

Replace the contents of an existing file:

curl -X PUT "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/files/workspace/notes.txt" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated notes content.",
    "encoding": "utf-8"
  }'

Delete a File

Remove a file from the workspace:

curl -X DELETE "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/files/workspace/notes.txt" \
  -H "Authorization: Bearer YOUR_TOKEN"

Patch a File

Apply partial updates to a file without replacing its entire contents. Supported operations are append, prepend, insert, and replace.

curl -X PATCH "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/files/workspace/log.txt" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "append",
    "content": "\nNew log entry at 2026-02-18T10:00:00Z"
  }'

curl -X PATCH "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/files/workspace/data.txt" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "insert",
    "content": "inserted text",
    "position": 128
  }'

curl -X PATCH "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/files/workspace/data.txt" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "replace",
    "content": "replacement text",
    "position": 64,
    "length": 20
  }'

Parameter	Type	Required	Description
`operation`	enum	✅	`"append"`, `"prepend"`, `"insert"`, or `"replace"`
`content`	string	✅	Content to apply
`position`	number	For `insert`/`replace`	Byte offset for the operation
`length`	number	For `replace`	Number of bytes to replace

Directory Operations

List a Directory

List the contents of a directory in the agent workspace:

curl -X GET "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/directories/workspace?recursive=false&includeHidden=false" \
  -H "Authorization: Bearer YOUR_TOKEN"

Parameter	Type	Default	Description
`recursive`	boolean	`false`	List contents recursively
`includeHidden`	boolean	`false`	Include hidden files (dotfiles)

Create a Directory

curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/directories/workspace/data/exports" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recursive": true
  }'

Set recursive to true to create parent directories that do not exist yet.

Delete a Directory

curl -X DELETE "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/directories/workspace/temp" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recursive": true
  }'

Deleting a directory with recursive: true permanently removes all files and subdirectories within it. This cannot be undone.

Bulk Operations

Copy

Copy a file or directory to a new location within the workspace:

curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/copy" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "workspace/config.json",
    "destination": "workspace/config.backup.json",
    "overwrite": false
  }'

Move

Move or rename a file or directory:

curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/move" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "workspace/old-name.txt",
    "destination": "workspace/new-name.txt",
    "overwrite": false
  }'

Parameter	Type	Required	Description
`source`	string	✅	Source path
`destination`	string	✅	Destination path
`overwrite`	boolean	❌	Whether to overwrite if the destination already exists

Search

Search for files by name, content, or both within an agent’s workspace:

curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database",
    "type": "both",
    "path": "workspace",
    "filePattern": "*.json",
    "caseSensitive": false,
    "maxResults": 50
  }'

Parameter	Type	Required	Default	Description
`query`	string	✅	—	Search term
`type`	enum	❌	`"both"`	`"filename"`, `"content"`, or `"both"`
`path`	string	❌	—	Base directory to search from
`filePattern`	string	❌	—	Glob pattern to filter files (e.g., `*.json`)
`caseSensitive`	boolean	❌	`false`	Whether the search is case-sensitive
`maxResults`	number	❌	—	Maximum number of results to return

File Metadata

Get Metadata

Retrieve metadata for a file or directory, including size, permissions, and timestamps:

curl -X GET "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/metadata/workspace/config.json" \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Metadata

Update file permissions, ownership, or tags:

curl -X PUT "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/metadata/workspace/config.json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": "644",
    "tags": ["config", "production"]
  }'

Practical Examples

Seeding an Agent Workspace

After creating an agent, populate its workspace with configuration and data files:

# Create directory structure
curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/directories/workspace/config" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recursive": true}'

# Upload configuration
curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/files/workspace/config/settings.json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "{\"env\": \"production\", \"debug\": false}",
    "encoding": "utf-8"
  }'

You can also seed files at agent creation time using the initial_files parameter. See the Agent Configuration guide for details.

Backing Up Agent Data

Create a compressed archive of important workspace data:

curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/archive" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["workspace/data", "workspace/config"],
    "outputPath": "workspace/backups/backup-2026-02-18.tar.gz",
    "format": "tar.gz"
  }'

Best Practices

Use initial_files for bootstrapping. Provide configuration and seed data at agent creation time rather than making separate API calls afterward.
Use base64 encoding for binary files. Text files work with the default utf-8, but images, compiled assets, and other binary content require base64.
Prefer patch over full updates for large files. Appending log entries or inserting content at a specific position is more efficient than re-uploading the entire file.
Set overwrite: false as a safety measure. This prevents accidental data loss when creating or copying files.
Organize workspaces with clear directory structures. Use consistent paths like config/, data/, and output/ across your agents.

Shinzo Agents

Overview

File Operations

Read a File

Create a File

Update a File

Delete a File

Patch a File

Directory Operations

List a Directory

Create a Directory

Delete a Directory

Bulk Operations

Copy

Move

Search

Archives

Create an Archive

Extract an Archive

File Metadata

Get Metadata

Update Metadata

Practical Examples

Seeding an Agent Workspace

Backing Up Agent Data

Best Practices

Next Steps

Agent Configuration

Agent Messaging

​Overview

​File Operations

​Read a File

​Create a File

​Update a File

​Delete a File

​Patch a File

​Directory Operations

​List a Directory

​Create a Directory

​Delete a Directory

​Bulk Operations

​Copy

​Move

​Search

​Archives

​Create an Archive

​Extract an Archive

​File Metadata

​Get Metadata

​Update Metadata

​Practical Examples

​Seeding an Agent Workspace

​Backing Up Agent Data

​Best Practices

​Next Steps

Agent Configuration

Agent Messaging

Overview

File Operations

Read a File

Create a File

Update a File

Delete a File

Patch a File

Directory Operations

List a Directory

Create a Directory

Delete a Directory

Bulk Operations

Copy

Move

Search

Archives

Create an Archive

Extract an Archive

File Metadata

Get Metadata

Update Metadata

Practical Examples

Seeding an Agent Workspace

Backing Up Agent Data

Best Practices

Next Steps