Skip to main content

​
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
  }'
ParameterTypeRequiredDefaultDescription
contentstring✅—File content
encodingenum❌"utf-8""utf-8" or "base64"
overwriteboolean❌falseWhether 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"
  }'
ParameterTypeRequiredDescription
operationenum✅"append", "prepend", "insert", or "replace"
contentstring✅Content to apply
positionnumberFor insert/replaceByte offset for the operation
lengthnumberFor replaceNumber 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"
ParameterTypeDefaultDescription
recursivebooleanfalseList contents recursively
includeHiddenbooleanfalseInclude 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
  }'
ParameterTypeRequiredDescription
sourcestring✅Source path
destinationstring✅Destination path
overwriteboolean❌Whether to overwrite if the destination already exists
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
  }'
ParameterTypeRequiredDefaultDescription
querystring✅—Search term
typeenum❌"both""filename", "content", or "both"
pathstring❌—Base directory to search from
filePatternstring❌—Glob pattern to filter files (e.g., *.json)
caseSensitiveboolean❌falseWhether the search is case-sensitive
maxResultsnumber❌—Maximum number of results to return

​
Archives

​
Create an Archive

Package files and directories into a compressed archive: 
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.json"],
    "outputPath": "workspace/backup.tar.gz",
    "format": "tar.gz",
    "compressionLevel": 6
  }'
Supported formats: zip, tar, tar.gz, tar.bz2.

​
Extract an Archive

Extract an archive into a target directory: 
curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/filesystem/extract" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "archivePath": "workspace/backup.tar.gz",
    "outputPath": "workspace/restored",
    "overwrite": false
  }'

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

​
Next Steps

Agent Configuration

Configure agent workspaces, memory, and initial files.

Agent Messaging

Send messages to agents and retrieve conversation history.