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

# Manage Workspaces

> Create, list, inspect, rename, and delete persistent workspaces

Workspace metadata endpoints use the orchestrator API:

```text theme={null}
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

<ParamField query="all" type="boolean">
  Admin-only: include all organization workspaces, including rows outside the caller's normal visibility.
</ParamField>

<ResponseField name="data.workspaces" type="array">
  Workspaces visible to the caller.
</ResponseField>

<ResponseField name="data.storage" type="object">
  Organization storage summary with `usedBytes`, `quotaBytes`, and `unlimited`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.runtools.ai/v1/workspaces" \
    -H "X-API-Key: $RUNTOOLS_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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
      }
    }
  }
  ```
</ResponseExample>

## Create Workspace

<ParamField body="name" type="string" required>
  Display name.
</ParamField>

<ParamField body="slug" type="string">
  Optional URL-safe slug. When omitted, Runtools derives one from `name`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

## Get Workspace

<ParamField path="id" type="string" required>
  Workspace ID.
</ParamField>

```bash theme={null}
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.

```bash theme={null}
curl https://api.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/usage \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

```json theme={null}
{
  "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

<ParamField body="name" type="string">
  New display name.
</ParamField>

```bash theme={null}
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

<ParamField query="force" type="boolean">
  Delete even when usage references still exist. Without `force=true`, an in-use workspace returns `409 WORKSPACE_IN_USE`.
</ParamField>

```bash theme={null}
curl -X DELETE "https://api.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e?force=true" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

<Warning>
  Personal workspaces cannot be deleted through this public delete endpoint, and they cannot be mounted into sandboxes.
</Warning>