# Workspaces

Workspaces are named persistent disks scoped to an account. Each workspace is locked to a session type (`browser` or `sandbox`) and stores files across session restarts.

## Create a workspace

Two creation modes: **fresh** and **cloned**.

### Fresh workspace

```bash
curl -sS "$CHASER_API_URL/v1/workspaces" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_type": "sandbox",
    "name": "my-project",
    "image": "ghcr.io/example/dev:latest"
  }' | jq
```

| Field | Required | Description |
|-------|----------|-------------|
| `session_type` | Yes | `browser` or `sandbox` |
| `name` | No | Human-readable name (auto-generated if omitted) |
| `image` | No | OCI image, sandbox only |
| `template` | No | Flag as a template workspace |

### Cloned workspace

```bash
curl -sS "$CHASER_API_URL/v1/workspaces" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clone_from": "my-project",
    "name": "my-project-feature"
  }' | jq
```

Cloning copies workspace metadata and filesystem state. `session_type` and `image` are inherited from the source. Cloning is blocked while the source has an active session.

### Import from GitHub

```bash
curl -sS "$CHASER_API_URL/v1/workspaces/import" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"github_repo": "owner/repo"}' | jq
```

The repository is cloned into `/workspace` and the repo selector is persisted on the workspace.

## List workspaces

```bash
curl -sS "$CHASER_API_URL/v1/workspaces" \
  -H "Authorization: Bearer $CHASER_API_KEY" | jq
```

Each workspace includes: `id`, `name`, `session_type`, `status`, `image`, `template`, `active_session_id`, `last_session_id`, and persistence metadata.

## Naming

```bash
# Set a name
curl -sS -X PUT "$CHASER_API_URL/v1/workspaces/<workspace>/name" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "new-name"}' | jq

# Clear the name
curl -sS -X PUT "$CHASER_API_URL/v1/workspaces/<workspace>/name" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": null}' | jq
```

Names are unique per account, case-insensitive, max 64 characters. Ambiguous name matches return `workspace_name_ambiguous`.

## Templates

```bash
# Enable template mode
curl -sS -X PUT "$CHASER_API_URL/v1/workspaces/<workspace>/template" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": true}' | jq
```

Any workspace can be flagged as a template. Templates can be cloned with `clone_from`.

## Snapshots

Create filesystem-level restore points:

```bash
# Create
curl -sS -X POST "$CHASER_API_URL/v1/workspaces/<workspace>/snapshots" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "before-upgrade"}' | jq

# List
curl -sS "$CHASER_API_URL/v1/workspaces/<workspace>/snapshots" \
  -H "Authorization: Bearer $CHASER_API_KEY" | jq

# Restore (force terminates active sessions)
curl -sS -X POST "$CHASER_API_URL/v1/workspaces/<workspace>/snapshots/before-upgrade/restore" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"force": true}' | jq

# Delete
curl -sS -X DELETE "$CHASER_API_URL/v1/workspaces/<workspace>/snapshots/before-upgrade" \
  -H "Authorization: Bearer $CHASER_API_KEY"
```

Snapshot create and restore operations are blocked while a session is active, unless `force=true` is passed (which terminates the session first).

## Delete

```bash
# Single workspace
curl -sS -X DELETE "$CHASER_API_URL/v1/workspaces/<workspace>?force=true" \
  -H "Authorization: Bearer $CHASER_API_KEY"

# Bulk delete
curl -sS -X POST "$CHASER_API_URL/v1/workspaces/bulk-delete" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace_ids": ["ws_1", "ws_2"], "force": true}' | jq
```

Without `force`, deletion fails if sessions are actively attached.

## Workspace selectors

Anywhere the API accepts a workspace reference, you can use:
- **Workspace name** (preferred)
- **Workspace UUID**

Selectors are resolved within the active account boundary.

## API reference

| Endpoint | Description |
|----------|-------------|
| `GET /v1/workspaces` | List workspaces |
| `POST /v1/workspaces` | Create workspace (fresh or cloned) |
| `POST /v1/workspaces/import` | Import from GitHub |
| `PUT /v1/workspaces/{workspace}/name` | Set or clear name |
| `PUT /v1/workspaces/{workspace}/template` | Toggle template mode |
| `GET /v1/workspaces/{workspace}/snapshots` | List snapshots |
| `POST /v1/workspaces/{workspace}/snapshots` | Create snapshot |
| `POST /v1/workspaces/{workspace}/snapshots/{name}/restore` | Restore snapshot |
| `DELETE /v1/workspaces/{workspace}/snapshots/{name}` | Delete snapshot |
| `DELETE /v1/workspaces/{workspace}` | Delete workspace |
| `POST /v1/workspaces/bulk-delete` | Bulk delete workspaces |