Docs menu · API
Guides
- Overview
- Connect your assistant
- Asking for automations
- Connections and secrets
- Trigger links
- Looking after automations
- State between runs
- Troubleshooting
- FAQ
- For coding agents
Reference
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 is built on it. Every operation is in the API reference and in 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):
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:
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:
{ "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:
{ "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.