Workspace Files - Runtools.ai

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
  }
]

GET

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:

https://storage.runtools.ai/v1

All paths are workspace-relative. Use / 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
  }
]

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

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

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.

Manage Workspaces RunMesh

​Endpoints

​List Files

​Storage Info

​Create Files And Folders

​Upload Files

​Download Files

​Rename

​Copy Or Move

​Delete

​Notes

Endpoints

List Files

Storage Info

Create Files And Folders

Upload Files

Download Files

Rename

Copy Or Move

Delete

Notes