# ClickRuntime API

> The REST API behind the CLI: sign-in, errors and next steps, confirmations, idempotency, pagination, rate limits and versions.

The ClickRuntime API is a JSON API with the same operations and rules as the ClickRuntime MCP server. It's for coding agents and tools that make HTTP requests; the [CLI](/docs/cli) is built on it. Every operation is in the [API reference](/docs/api-reference) and in [openapi.json](/api/v1/openapi.json).

Base URL: `https://clickruntime.com/api/v1`. Send `Authorization: Bearer <access token>` with every request except `/docs/runtime` and `/openapi.json`.

## Sign in

The API uses OAuth 2.1. The same sign-in works for the MCP server and the API. Use the public `client_id` `clickruntime-cli`; there is nothing to register and no secret.

**With a browser on the same machine**: authorization code with PKCE and a loopback redirect, such as `http://127.0.0.1:53123/callback` on any port. Scope: `openid email workspace:read automations:draft automations:control offline_access`.

**Without a browser** (device sign-in, RFC 8628):

```bash
curl -s https://clickruntime.com/oauth/device_authorization \
  -d client_id=clickruntime-cli \
  -d "scope=openid email workspace:read automations:draft automations:control offline_access"
```

The answer has `device_code`, `user_code`, `verification_uri` and `interval`. Give the person the link and the code: "Open https://clickruntime.com/device and enter BCDF-GHJK to connect ClickRuntime." The person types the code on that page; the link never carries it. Then poll every `interval` seconds:

```bash
curl -s https://clickruntime.com/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=clickruntime-cli \
  -d device_code=<device_code>
```

Until the person approves, the answer is `authorization_pending`; poll more slowly after `slow_down`. `access_denied` and `expired_token` end the attempt. The code expires after 10 minutes.

Access tokens last an hour. Refresh them with `grant_type=refresh_token`; each refresh token works once. Store tokens where the CLI does (`~/.config/clickruntime/credentials.json`) or in `CLICKRUNTIME_TOKEN`, so the CLI and your own calls share a sign-in. `DELETE /session` signs out, and so does signing it out in the ClickRuntime dashboard.

## Responses and next steps

Responses are JSON with snake_case fields, ids as strings and ISO 8601 times. Links for the person are in `links`. When the person has to do something, such as add a key, connect an account or confirm, the response has `next`:

```json
{ "next": { "action": "open_link", "url": "https://clickruntime.com/connections?add=OPENAI_API_KEY", "say": "One setup step is left: add the key OPENAI_API_KEY in the ClickRuntime dashboard." } }
```

Give the person `url` exactly as returned and repeat `say`. Never build or change a ClickRuntime link.

## Errors

Every error has the same shape and a stable code:

```json
{ "error": "setup_incomplete", "message": "…", "next": { "action": "fix_request", "say": "…" }, "details": { } }
```

| Status | Codes |
|---|---|
| 400 | `invalid_argument`, `invalid_schedule`, `script_rejected`, `secret_in_argument`, … |
| 401 | `unauthenticated`, `invalid_token`: sign in again |
| 403 | `insufficient_scope`, `forbidden`, `email_not_verified` |
| 404 | `not_found`, also for anything in another workspace |
| 409 | `not_draft`, `setup_incomplete`, `confirmation_expired`, … |
| 429 | `rate_limited`, with `Retry-After` |

The API never takes a key, token or password. A request that contains one is refused with `secret_in_argument`; the person saves keys in the ClickRuntime dashboard.

## Confirmations

Turning on, resuming, running now, applying a change to a live automation and deleting all need the person. `POST /confirmations` with `automation_id` and `action` returns `links.confirm` and `confirmation_ref`. Give the person the link, then poll `GET /confirmations/{ref}` until `state` is `confirmed`, `cancelled` or `expired`. After a deploy, `GET /automations/{id}/deploy` waits for it to finish. There is no way for the agent to confirm. Pausing needs no confirmation.

## Retries and idempotency

Send an `Idempotency-Key` header (any unique string up to 255 characters) with POST requests. A retry with the same key within 24 hours gets the first answer, marked `Idempotent-Replayed: true`, instead of doing the work twice. The same key with a different request is refused with `idempotency_key_reused`.

## Pagination

List routes take `?limit=` and `?cursor=`. Pass `next_cursor` from one page as `cursor` for the next; it is `null` on the last page.

## Rate limits

Each sign-in can make 120 requests a minute per workspace. Every response has `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds). Over the limit, the answer is 429 with `Retry-After`. Deploys and manual runs also have the workspace limits they have on MCP, and runs count toward your plan, including on the free plan.

## Versions

The version is in the path (`/api/v1`). Within v1 changes only add things: new routes, new optional fields, new error codes. Anything removed is announced first and marked with a `Deprecation` header.
