curl "https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src?showHidden=false" \
-H "X-API-Key: $RUNTOOLS_API_KEY"
[
{
"id": "/src/index.ts",
"value": "index.ts",
"type": "file",
"date": "2026-05-06T10:00:00.000Z",
"size": 842
},
{
"id": "/src/components",
"value": "components",
"type": "folder",
"date": "2026-05-06T10:00:00.000Z",
"lazy": true,
"count": 12
}
]
Workspaces
Workspace Files
List, upload, download, and mutate files in a workspace
GET
/
v1
/
workspaces
/
{id}
/
files
curl "https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src?showHidden=false" \
-H "X-API-Key: $RUNTOOLS_API_KEY"
[
{
"id": "/src/index.ts",
"value": "index.ts",
"type": "file",
"date": "2026-05-06T10:00:00.000Z",
"size": 842
},
{
"id": "/src/components",
"value": "components",
"type": "folder",
"date": "2026-05-06T10:00:00.000Z",
"lazy": true,
"count": 12
}
]
Workspace file endpoints use the storage API:
All paths are workspace-relative. Use
Path info returns size and entry count:
The default upload limit is 100 MB per request.
https://storage.runtools.ai/v1
/ for the workspace root.
Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /v1/workspaces/{id}/files | files:read | List root directory |
GET | /v1/workspaces/{id}/files/{path} | files:read | List a subdirectory |
GET | /v1/workspaces/{id}/info | files:read | Get organization storage usage for this workspace context |
GET | /v1/workspaces/{id}/info/{path} | files:read | Get size/count for a file or directory |
POST | /v1/workspaces/{id}/files | files:write | Create a file or folder in root |
POST | /v1/workspaces/{id}/files/{path} | files:write | Create a file or folder inside a directory |
POST | /v1/workspaces/{id}/upload | files:write | Upload a multipart file to root or query id |
POST | /v1/workspaces/{id}/upload/{path} | files:write | Upload a multipart file to a directory |
PUT | /v1/workspaces/{id}/files | files:write | Batch copy or move by file IDs |
PUT | /v1/workspaces/{id}/files/{path} | files:write | Rename, copy, or move files |
DELETE | /v1/workspaces/{id}/files | files:write | Delete files by ID |
GET | /v1/workspaces/{id}/direct | files:read | Stream one file inline or as a download |
files:* and * also satisfy file scopes.
List Files
string
required
Workspace ID.
boolean
default:"false"
Include dotfiles and dot directories.
curl "https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src?showHidden=false" \
-H "X-API-Key: $RUNTOOLS_API_KEY"
[
{
"id": "/src/index.ts",
"value": "index.ts",
"type": "file",
"date": "2026-05-06T10:00:00.000Z",
"size": 842
},
{
"id": "/src/components",
"value": "components",
"type": "folder",
"date": "2026-05-06T10:00:00.000Z",
"lazy": true,
"count": 12
}
]
Storage Info
Root info returns drive-style storage usage:curl https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/info \
-H "X-API-Key: $RUNTOOLS_API_KEY"
[
{
"free": 10736993952,
"total": 10737418240,
"used": 424288
}
]
curl https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/info/src \
-H "X-API-Key: $RUNTOOLS_API_KEY"
{
"Size": 8420,
"Count": 17
}
Create Files And Folders
string
required
File or folder name. Names cannot contain path separators.
string
required
file or folder.curl -X POST https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src \
-H "X-API-Key: $RUNTOOLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "notes",
"type": "folder"
}'
{
"result": {
"id": "/src/notes",
"name": "notes"
}
}
Upload Files
Uploads use multipart form data. Thefile field is required. The optional name field overrides the uploaded filename.
curl -X POST https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/upload/src \
-H "X-API-Key: $RUNTOOLS_API_KEY" \
-F "file=@./README.md" \
-F "name=README.md"
{
"id": "/src/README.md",
"name": "README.md"
}
Download Files
string
required
Workspace-relative file ID, such as
/src/README.md.boolean
default:"false"
When
true, return an attachment response. Otherwise, stream inline when possible.curl "https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/direct?id=/src/README.md&download=true" \
-H "X-API-Key: $RUNTOOLS_API_KEY" \
-o README.md
Rename
curl -X PUT https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src/README.md \
-H "X-API-Key: $RUNTOOLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"operation": "rename",
"name": "NOTES.md"
}'
Copy Or Move
Use file IDs from list responses.curl -X PUT https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files \
-H "X-API-Key: $RUNTOOLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"operation": "copy",
"target": "/archive",
"ids": ["/src/NOTES.md"]
}'
operation can be copy or move. Batch copy and move accept up to 250 IDs.
Delete
curl -X DELETE https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files \
-H "X-API-Key: $RUNTOOLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ids": ["/archive/NOTES.md"]
}'
Notes
- Personal workspaces are only visible to the owner and organization admins.
- When a workspace is over its storage quota, write operations return an error until usage is reduced or the org limit is updated.
- Directory listing hides dotfiles unless
showHidden=true.