Skip to main content
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
  }
]

Documentation Index

Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt

Use this file to discover all available pages before exploring further.

Workspace file endpoints use the storage API: 
https://storage.runtools.ai/v1
All paths are workspace-relative. Use / for the workspace root.

​
Endpoints

MethodPathScopeDescription
GET/v1/workspaces/{id}/filesfiles:readList root directory
GET/v1/workspaces/{id}/files/{path}files:readList a subdirectory
GET/v1/workspaces/{id}/infofiles:readGet organization storage usage for this workspace context
GET/v1/workspaces/{id}/info/{path}files:readGet size/count for a file or directory
POST/v1/workspaces/{id}/filesfiles:writeCreate a file or folder in root
POST/v1/workspaces/{id}/files/{path}files:writeCreate a file or folder inside a directory
POST/v1/workspaces/{id}/uploadfiles:writeUpload a multipart file to root or query id
POST/v1/workspaces/{id}/upload/{path}files:writeUpload a multipart file to a directory
PUT/v1/workspaces/{id}/filesfiles:writeBatch copy or move by file IDs
PUT/v1/workspaces/{id}/files/{path}files:writeRename, copy, or move files
DELETE/v1/workspaces/{id}/filesfiles:writeDelete files by ID
GET/v1/workspaces/{id}/directfiles:readStream one file inline or as a download
files:* and * also satisfy file scopes.

​
List Files

​
id
string
required
Workspace ID.
​
showHidden
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
  }
]
Path info returns size and entry count: 
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

​
name
string
required
File or folder name. Names cannot contain path separators.
​
type
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. The file 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"
}
The default upload limit is 100 MB per request.

​
Download Files

​
id
string
required
Workspace-relative file ID, such as /src/README.md.
​
download
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.