curl "https://api.runtools.ai/v1/workspaces" \
-H "X-API-Key: $RUNTOOLS_API_KEY"
{
"data": {
"workspaces": [
{
"id": "9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e",
"slug": "docs-project",
"name": "Docs Project",
"sizeBytes": 524288,
"quotaBytes": 10737418240,
"createdAt": "2026-05-06T10:00:00Z",
"updatedAt": "2026-05-06T10:00:00Z",
"lastAccessedAt": null,
"isPersonal": false,
"ownerUserId": null,
"ownerDisplayName": null,
"ownerEmail": null
}
],
"storage": {
"usedBytes": 524288,
"quotaBytes": 10737418240,
"unlimited": false
}
}
}
Workspaces
Manage Workspaces
Create, list, inspect, rename, and delete persistent workspaces
GET
/
v1
/
workspaces
curl "https://api.runtools.ai/v1/workspaces" \
-H "X-API-Key: $RUNTOOLS_API_KEY"
{
"data": {
"workspaces": [
{
"id": "9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e",
"slug": "docs-project",
"name": "Docs Project",
"sizeBytes": 524288,
"quotaBytes": 10737418240,
"createdAt": "2026-05-06T10:00:00Z",
"updatedAt": "2026-05-06T10:00:00Z",
"lastAccessedAt": null,
"isPersonal": false,
"ownerUserId": null,
"ownerDisplayName": null,
"ownerEmail": null
}
],
"storage": {
"usedBytes": 524288,
"quotaBytes": 10737418240,
"unlimited": false
}
}
}
Workspace metadata endpoints use the orchestrator API:
https://api.runtools.ai/v1
Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /v1/workspaces | files:read | List workspaces visible to the caller |
POST | /v1/workspaces | files:write | Create an organization workspace |
GET | /v1/workspaces/{id} | files:read | Get one workspace |
GET | /v1/workspaces/{id}/usage | files:read | Check sandbox and agent references |
PATCH | /v1/workspaces/{id} | files:write | Rename a workspace |
DELETE | /v1/workspaces/{id} | files:write | Delete a workspace |
files:* and * also satisfy workspace scopes.
List Workspaces
boolean
Admin-only: include all organization workspaces, including rows outside the caller’s normal visibility.
array
Workspaces visible to the caller.
object
Organization storage summary with
usedBytes, quotaBytes, and unlimited.curl "https://api.runtools.ai/v1/workspaces" \
-H "X-API-Key: $RUNTOOLS_API_KEY"
{
"data": {
"workspaces": [
{
"id": "9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e",
"slug": "docs-project",
"name": "Docs Project",
"sizeBytes": 524288,
"quotaBytes": 10737418240,
"createdAt": "2026-05-06T10:00:00Z",
"updatedAt": "2026-05-06T10:00:00Z",
"lastAccessedAt": null,
"isPersonal": false,
"ownerUserId": null,
"ownerDisplayName": null,
"ownerEmail": null
}
],
"storage": {
"usedBytes": 524288,
"quotaBytes": 10737418240,
"unlimited": false
}
}
}
Create Workspace
string
required
Display name.
string
Optional URL-safe slug. When omitted, Runtools derives one from
name.curl -X POST https://api.runtools.ai/v1/workspaces \
-H "X-API-Key: $RUNTOOLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Docs Project",
"slug": "docs-project"
}'
{
"data": {
"id": "9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e",
"slug": "docs-project",
"name": "Docs Project",
"sizeBytes": 0,
"quotaBytes": 10737418240,
"createdAt": "2026-05-06T10:00:00Z",
"updatedAt": "2026-05-06T10:00:00Z",
"lastAccessedAt": null,
"isPersonal": false,
"ownerUserId": null
}
}
Get Workspace
string
required
Workspace ID.
curl https://api.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e \
-H "X-API-Key: $RUNTOOLS_API_KEY"
Usage Summary
Use usage before deleting a workspace to see active sandbox mounts and agent references.curl https://api.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/usage \
-H "X-API-Key: $RUNTOOLS_API_KEY"
{
"data": {
"workspaceId": "9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e",
"workspaceName": "Docs Project",
"inUse": true,
"counts": {
"mountedSandboxes": 1,
"installableAgents": 0,
"customAgents": 0
},
"mountedSandboxes": [
{
"sandboxId": "sandbox-abc123",
"sandboxName": "repo-env",
"sandboxStatus": "running",
"mountPath": "/workspace",
"readOnly": false
}
],
"installableAgents": [],
"customAgents": []
}
}
Rename Workspace
string
New display name.
curl -X PATCH https://api.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e \
-H "X-API-Key: $RUNTOOLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Docs Project Archive"}'
Delete Workspace
boolean
Delete even when usage references still exist. Without
force=true, an in-use workspace returns 409 WORKSPACE_IN_USE.curl -X DELETE "https://api.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e?force=true" \
-H "X-API-Key: $RUNTOOLS_API_KEY"
Personal workspaces cannot be deleted through this public delete endpoint, and they cannot be mounted into sandboxes.