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

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 metadata endpoints use the orchestrator API: 
https://api.runtools.ai/v1

​
Endpoints

MethodPathScopeDescription
GET/v1/workspacesfiles:readList workspaces visible to the caller
POST/v1/workspacesfiles:writeCreate an organization workspace
GET/v1/workspaces/{id}files:readGet one workspace
GET/v1/workspaces/{id}/usagefiles:readCheck sandbox and agent references
PATCH/v1/workspaces/{id}files:writeRename a workspace
DELETE/v1/workspaces/{id}files:writeDelete a workspace
files:* and * also satisfy workspace scopes.

​
List Workspaces

​
all
boolean
Admin-only: include all organization workspaces, including rows outside the caller’s normal visibility.
​
data.workspaces
array
Workspaces visible to the caller.
​
data.storage
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

​
name
string
required
Display name.
​
slug
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

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

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

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