# Jobs

The jobs API provides queued, retriable execution for sandbox commands, browser automation, pipelines, and lifecycle operations.

Jobs are scoped to the active account (selected via `X-Chaser-Account`), so organization queues act as shared automation state.

## Create a job

```bash
curl -sS "$CHASER_API_URL/v1/jobs" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "sandbox.exec",
    "input": {"workspace": "my-project", "command": "npm test"}
  }' | jq
```

## Job kinds

| Kind | Description |
|------|-------------|
| `sandbox.exec` | Run a command in a sandbox (workspace-backed or ephemeral) |
| `pipeline.run` | Execute ordered steps on a shared workspace |
| `browser.action` | Execute sequential CDP method calls |
| `browser.scrape` | Navigate to a URL and optionally extract content |
| `github.runner` | Execute GitHub Actions workflow jobs via self-hosted runner labels |
| `session.terminate` | Terminate a session |
| `session.bulk_terminate` | Terminate multiple sessions |
| `workspace.delete` | Delete a workspace |
| `workspace.bulk_delete` | Delete multiple workspaces |

Use `GET /v1/jobs/kinds` to get the authoritative list with input schemas for your deployment.

## Examples

### Sandbox exec

```bash
# Workspace-backed
curl -sS "$CHASER_API_URL/v1/jobs" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "sandbox.exec",
    "input": {"workspace": "my-project", "command": "npm ci && npm test"}
  }' | jq

# Ephemeral with image
curl -sS "$CHASER_API_URL/v1/jobs" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "sandbox.exec",
    "input": {"ephemeral": true, "image": "node:20", "command": "node -v"}
  }' | jq
```

### Pipeline

Run ordered steps on a shared workspace. Steps execute sequentially and share filesystem state.

```bash
curl -sS "$CHASER_API_URL/v1/jobs" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "pipeline.run",
    "input": {
      "workspace": "my-project",
      "steps": [
        {"command": "npm ci", "timeout_ms": 300000},
        {"command": "npm run lint", "timeout_ms": 120000},
        {"command": "npm test", "timeout_ms": 600000}
      ]
    }
  }' | jq
```

### Browser scrape

```bash
curl -sS "$CHASER_API_URL/v1/jobs" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "browser.scrape",
    "input": {"url": "https://example.com", "selector": "h1"}
  }' | jq
```

## Scheduling and idempotency

Jobs accept optional scheduling and deduplication parameters:

- `run_at` -- RFC 3339 timestamp for delayed execution
- `idempotency_key` -- prevents duplicate job creation on retries

```bash
curl -sS "$CHASER_API_URL/v1/jobs" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "sandbox.exec",
    "input": {"workspace": "my-project", "command": "npm test"},
    "run_at": "2025-03-15T10:00:00Z",
    "idempotency_key": "nightly-test-2025-03-15"
  }' | jq
```

## Manage jobs

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

# Get a specific job
curl -sS "$CHASER_API_URL/v1/jobs/<job_id>" \
  -H "Authorization: Bearer $CHASER_API_KEY" | jq

# Cancel a job
curl -sS -X POST "$CHASER_API_URL/v1/jobs/<job_id>/cancel" \
  -H "Authorization: Bearer $CHASER_API_KEY" | jq

# Retry a failed job
curl -sS -X POST "$CHASER_API_URL/v1/jobs/<job_id>/retry" \
  -H "Authorization: Bearer $CHASER_API_KEY" | jq
```

## CLI

```bash
chaser jobs exec --workspace my-project "npm test" --wait --json
chaser jobs exec --ephemeral --image node:20 "node -v" --wait --json
chaser jobs scrape <session_id> --url "https://example.com" --wait --json
chaser jobs kinds --json
```

## API reference

| Endpoint | Description |
|----------|-------------|
| `POST /v1/jobs` | Create a job |
| `GET /v1/jobs` | List jobs |
| `GET /v1/jobs/{id}` | Get job details |
| `GET /v1/jobs/kinds` | List available job kinds with input schemas |
| `POST /v1/jobs/{id}/cancel` | Cancel a job |
| `POST /v1/jobs/{id}/retry` | Retry a failed job |