Manage Workspaces - Runtools.ai

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

GET

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.

Channels Workspace Files

​Endpoints

​List Workspaces

​Create Workspace

​Get Workspace

​Usage Summary

​Rename Workspace

​Delete Workspace

Endpoints

List Workspaces

Create Workspace

Get Workspace

Usage Summary

Rename Workspace

Delete Workspace