# API reference

> Every ClickRuntime API route with its parameters, body and response fields, from openapi.json.

Every route of the [ClickRuntime API](/docs/api), generated from [openapi.json](/api/v1/openapi.json). Base URL: `https://clickruntime.com/api/v1`. Request body fields follow the MCP tool of the same name.

## Routes

### GET /apps

Apps with ready-made connections.

MCP tool: `list_app_catalog`.

Returns 200 with [AppCatalog](#appcatalog).

### GET /automations

List automations.

MCP tool: `list_automations`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `status` | query | string | draft, live or paused. |
| `cursor` | query | string | next_cursor from the previous page. |
| `limit` | query | integer | Page size. |

Returns 200 with [AutomationList](#automationlist).

### POST /automations

Save a new draft automation.

MCP tool: `save_draft`.

| Body field | Type | Required | Description |
|---|---|---|---|
| `dependencies` | array of object |  | Extra PyPI packages the script imports that are not built in, such as [{"name": "tenacity", "version": "==9.0.0"}]. Pin an exact version. At most 15. Leave it out to keep the current list; [] removes them all. They install when the script deploys. |
| `deploy` | boolean |  | true deploys the change in the same call and waits for the deploy result. Setup must be complete. Leave out to only save. |
| `how_it_works` | object | yes | How the script works, for someone who cannot read code. Required whenever you send a script. steps: 2 to 8 short plain sentences in run order, covering what it reads, what it decides, and what it changes or sends, naming each service it uses. notes: up to 4 sentences for branches that matter, such as what happens when there is nothing to do or a service fails. No code, variable names, or jargon. It must match the script exactly; the card shows it next to the services the server detects in the script. |
| `name` | string | yes | A short name the person will recognise, such as "Morning summary". |
| `pattern` | string: schedule, incoming, remember_then_schedule | yes | schedule: runs on the schedule. incoming: runs when an event arrives at the trigger link. remember_then_schedule: events are stored in state and a scheduled run acts on them. |
| `retry` | object |  | incoming only: how a failed run on an event is retried. Platform errors and timeouts are retried up to max_attempts attempts in total; script errors only when retry_script_errors is true. The default is 3 attempts without script errors. It replaces the whole policy. |
| `schedule` | object |  | When the automation runs. Prefer every_minutes, hourly, daily, weekdays, weekly, or monthly; use cron only when none of them fits, such as the second Tuesday of the month or every 15 minutes during business hours. timezone is an IANA name, required for daily, weekdays, weekly, monthly, and cron; it defaults to UTC for every_minutes and hourly. |
| `script` | string | yes | The complete Python script. Before writing it, you must read the script reference, the MCP resource clickruntime://docs/runtime (read it with resources/read; it is not a tool), or, if you cannot read MCP resources, the same text at https://clickruntime.com/docs/runtime.md; the script must follow them. It needs a @on_trigger (schedule) or @on_event (incoming) handler decorated from clickruntime. Read secrets and connections with clickruntime.credentials; credentials.connection and credentials.secret each return a plain str (the token or value itself, with no .access_token), and the script never gets a refresh token; never write a key's value into the script. Outbound calls are HTTPS only; no subprocess, os.system, multiprocessing or ctypes. |
| `setup_needs` | array of object | yes | Every connection account and saved key the script reads through clickruntime.credentials. Before writing the script, call list_connections and ask the person which existing account to use for each service (or confirm the one there is); set up a new account only if they ask or none fits. For a service with no account yet, call list_app_catalog and use a ready-made app whose scopes and limits fit, without asking; draft an app of their own only when none fits. Never pick or invent an account name yourself. A script can read only what is declared here. An empty list means nothing to set up. Never put a key's value here. |
| `signature` | object |  | incoming and remember_then_schedule only: how the platform checks the sender's signature before a run. It replaces all signature settings at once. Use a named provider when the sender is one of them; use hmac_sha256 for any other sender that signs the raw body with HMAC-SHA256, and set header, encoding, and prefix from the sender's docs. The secret's value is never sent here: name it in secret_name and list the same name in setup_needs so the person saves the value in the application. provider none turns the check off. |
| `summary` | string | yes | One or two plain sentences saying what happens and when. It appears on the cards. |
| `template_id` | string |  | The starter id when the draft follows a starter from the get-started skill (for example page-summary-email). Leave out otherwise. |

Returns 201 with [Automation](#automation).

### GET /automations/{automation_id}

Get an automation.

MCP tool: `get_automation`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `automation_id` | path | string | Automation id (aut_...). |

Returns 200 with [Automation](#automation).

### PATCH /automations/{automation_id}

Change an automation. A draft is updated in place (update_draft); a live or paused one gets a pending change (change_automation). deploy: true deploys a draft, or asks the person to confirm a live change.

MCP tool: `update_draft|change_automation`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `automation_id` | path | string | Automation id (aut_...). |

| Body field | Type | Required | Description |
|---|---|---|---|
| `dependencies` | array of object |  | Extra PyPI packages the script imports that are not built in, such as [{"name": "tenacity", "version": "==9.0.0"}]. Pin an exact version. At most 15. Leave it out to keep the current list; [] removes them all. They install when the script deploys. |
| `deploy` | boolean |  | true deploys the change in the same call and waits for the deploy result. Setup must be complete. Leave out to only save. |
| `how_it_works` | object |  | How the script works, for someone who cannot read code. Required whenever you send a script. steps: 2 to 8 short plain sentences in run order, covering what it reads, what it decides, and what it changes or sends, naming each service it uses. notes: up to 4 sentences for branches that matter, such as what happens when there is nothing to do or a service fails. No code, variable names, or jargon. It must match the script exactly; the card shows it next to the services the server detects in the script. |
| `name` | string |  | A short name the person will recognise, such as "Morning summary". |
| `retry` | object |  | incoming only: how a failed run on an event is retried. Platform errors and timeouts are retried up to max_attempts attempts in total; script errors only when retry_script_errors is true. The default is 3 attempts without script errors. It replaces the whole policy. |
| `schedule` | object |  | When the automation runs. Prefer every_minutes, hourly, daily, weekdays, weekly, or monthly; use cron only when none of them fits, such as the second Tuesday of the month or every 15 minutes during business hours. timezone is an IANA name, required for daily, weekdays, weekly, monthly, and cron; it defaults to UTC for every_minutes and hourly. |
| `script` | string |  | The complete Python script. Before writing it, you must read the script reference, the MCP resource clickruntime://docs/runtime (read it with resources/read; it is not a tool), or, if you cannot read MCP resources, the same text at https://clickruntime.com/docs/runtime.md; the script must follow them. It needs a @on_trigger (schedule) or @on_event (incoming) handler decorated from clickruntime. Read secrets and connections with clickruntime.credentials; credentials.connection and credentials.secret each return a plain str (the token or value itself, with no .access_token), and the script never gets a refresh token; never write a key's value into the script. Outbound calls are HTTPS only; no subprocess, os.system, multiprocessing or ctypes. |
| `setup_needs` | array of object |  | Every connection account and saved key the script reads through clickruntime.credentials. Before writing the script, call list_connections and ask the person which existing account to use for each service (or confirm the one there is); set up a new account only if they ask or none fits. For a service with no account yet, call list_app_catalog and use a ready-made app whose scopes and limits fit, without asking; draft an app of their own only when none fits. Never pick or invent an account name yourself. A script can read only what is declared here. An empty list means nothing to set up. Never put a key's value here. |
| `signature` | object |  | incoming and remember_then_schedule only: how the platform checks the sender's signature before a run. It replaces all signature settings at once. Use a named provider when the sender is one of them; use hmac_sha256 for any other sender that signs the raw body with HMAC-SHA256, and set header, encoding, and prefix from the sender's docs. The secret's value is never sent here: name it in secret_name and list the same name in setup_needs so the person saves the value in the application. provider none turns the check off. |
| `summary` | string |  | One or two plain sentences saying what happens and when. It appears on the cards. |

Returns 200 with [Automation](#automation).

### GET /automations/{automation_id}/deploy

Wait for the latest deploy to finish (long poll, about 45 seconds).

MCP tool: `wait_for_deploy`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `automation_id` | path | string | Automation id (aut_...). |

Returns 200 with [Automation](#automation).

### GET /automations/{automation_id}/events

List events received on the trigger link.

MCP tool: `list_incoming_events`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `automation_id` | path | string | Automation id (aut_...). |
| `cursor` | query | string | next_cursor from the previous page. |
| `limit` | query | integer | Page size. |

Returns 200 with [EventList](#eventlist).

### GET /automations/{automation_id}/events/latest

The latest event received on the trigger link.

MCP tool: `get_latest_event`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `automation_id` | path | string | Automation id (aut_...). |

Returns 200 with [LatestEvent](#latestevent).

### POST /automations/{automation_id}/events/{event_id}/replay

Run a live or paused automation again on an event it received.

MCP tool: `replay_event`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `automation_id` | path | string | Automation id (aut_...). |
| `event_id` | path | string | Event id from the events list. |

Returns 200 with [Run](#run).

### POST /automations/{automation_id}/pause

Pause a live automation. Needs no confirmation.

MCP tool: `pause_automation`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `automation_id` | path | string | Automation id (aut_...). |

Returns 200 with [Automation](#automation).

### GET /automations/{automation_id}/runs

List runs.

MCP tool: `list_runs`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `automation_id` | path | string | Automation id (aut_...). |
| `status` | query | string | Filter by run status. |
| `cursor` | query | string | next_cursor from the previous page. |
| `limit` | query | integer | Page size. |

Returns 200 with [RunList](#runlist).

### GET /automations/{automation_id}/script

Get the automation's script.

MCP tool: `get_script`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `automation_id` | path | string | Automation id (aut_...). |
| `version` | query | string | A version number, or omit for the current one. |

Returns 200 with [Script](#script).

### GET /automations/{automation_id}/setup

Setup steps left for the person (connections and keys), each with its link.

MCP tool: `get_setup_status`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `automation_id` | path | string | Automation id (aut_...). |

Returns 200 with [SetupStatus](#setupstatus).

### POST /automations/{automation_id}/test-event

Send a sample event to an incoming automation. Body: {"body": {...}}.

MCP tool: `send_test_event`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `automation_id` | path | string | Automation id (aut_...). |

| Body field | Type | Required | Description |
|---|---|---|---|
| `body` | object |  | A realistic sample of the sender's JSON payload. Never include a real key. |
| `confirmation_id` | string |  | Set by the confirm card from its own result metadata. |

Returns 200 with [Run](#run).

### POST /confirmations

Ask the person to confirm turning on, resuming, running, applying a change or deleting. Returns a link for the person; the agent can never confirm.

MCP tool: `prepare_confirmation`.

| Body field | Type | Required | Description |
|---|---|---|---|
| `action` | string: enable, resume, run_now, apply_change, delete, send_test_event_live | yes | What the person wants to do. |
| `automation_id` | string | yes | The automation id, starting with aut_ (from list_automations or a previous result). |
| `expected_state` | string |  | Set by a card: the state it showed. Leave it out. |
| `test_body` | object |  | send_test_event_live only: the sample JSON body to send. |

Returns 201 with [Confirmation](#confirmation).

### GET /confirmations/{confirmation_ref}

Whether the person confirmed, cancelled, or the link expired.

MCP tool: `get_confirmation_status`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `confirmation_ref` | path | string | confirmation_ref from POST /confirmations. |

Returns 200 with [ConfirmationStatus](#confirmationstatus).

### GET /connections

Connected accounts and saved key names (never values).

MCP tool: `list_connections`.

Returns 200 with [Connections](#connections).

### POST /connections

Get a consent link for the person to connect an account.

MCP tool: `begin_connection`.

| Body field | Type | Required | Description |
|---|---|---|---|
| `automation_id` | string |  | The automation id, starting with aut_ (from list_automations or a previous result). |
| `name` | string |  | The account name the person chose, such as work or personal. Required unless purpose is notifications. |
| `provider` | string | yes | The id of a ready-made app from list_app_catalog, the slug of an app from draft_oauth_provider, such as slack or google, or slack with purpose notifications. |
| `purpose` | string: automation, notifications |  | automation (default): a named account scripts fetch. notifications: the single Slack connection used by notify.slack and alerts. |

Returns 201 with [Connect](#connect).

### GET /docs/runtime

The script reference (also at https://clickruntime.com/docs/runtime.md).

Returns 200 with [RuntimeDoc](#runtimedoc).

### GET /issues

Support issues.

MCP tool: `list_issues`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `status` | query | string |  |
| `limit` | query | integer |  |

Returns 200 with [IssueList](#issuelist).

### POST /issues

Report a problem to ClickRuntime support.

MCP tool: `report_issue`.

| Body field | Type | Required | Description |
|---|---|---|---|
| `automation_id` | string |  | The automation id, starting with aut_ (from list_automations or a previous result). |
| `body` | string | yes | What happened, steps, error codes and messages. No keys or tokens. |
| `category` | string: bug, connection, billing, other | yes | What the issue is about. |
| `run_id` | string |  | The run id, when one run shows the problem. |
| `title` | string | yes | One-line summary. |

Returns 201 with [Issue](#issue).

### GET /issues/{issue_id}

A support issue with its messages.

MCP tool: `get_issue`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `issue_id` | path | string |  |

Returns 200 with [Issue](#issue).

### POST /issues/{issue_id}/messages

Add a message to a support issue.

MCP tool: `add_issue_message`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `issue_id` | path | string |  |

| Body field | Type | Required | Description |
|---|---|---|---|
| `body` | string | yes | The message. |

Returns 200 with [Issue](#issue).

### GET /me

Who is signed in, in which workspace.

MCP tool: `get_profile`.

Returns 200 with [Profile](#profile).

### POST /oauth-providers

Draft a custom OAuth app the person finishes in the ClickRuntime dashboard.

MCP tool: `draft_oauth_provider`.

| Body field | Type | Required | Description |
|---|---|---|---|
| `auth_params` | object |  | Extra authorize parameters the docs require, such as owner=user or access_type=offline. |
| `authorize_url` | string | yes | The service's OAuth 2.0 authorization endpoint (https), from its docs. |
| `docs_url` | string |  | The docs page that explains creating an OAuth app (https). |
| `name` | string | yes | Display name, such as Notion. |
| `scope_separator` | string: space, comma |  | How the service joins scopes. Most use space. |
| `scopes` | array of string |  | The fewest scopes the script needs, one per item. |
| `setup_notes` | string |  | The setup guide shown on the setup page, written from the service's docs. One step per '## Step title' heading, then plain sentences. Use **Exact button or menu name** for anything to click, [link text](https://...) for pages to open (link straight to the console page), and `value` for text to paste (shown with a copy icon). Placeholders: {{redirect_url}} (the callback URL with a copy icon, usable inside a sentence), {{scopes}} (every scope with a copy icon, on its own line), {{client_id}} and {{client_secret}} (required: the input boxes where the person pastes them, on their own lines, in the step where the service shows those values). {{redirect_url}} is required and goes only where the service asks for a redirect or callback URL. The person reads this guide on the ClickRuntime setup page, so never tell them to open it, and do not number titles ('Step 3:'). An optional final '## After connecting' section is shown with the Connect step (for example inviting a bot to channels). ClickRuntime adds the Connect step itself. Never include keys. |
| `slug` | string | yes | Short id for the app, such as notion or hubspot. Used as the provider in setup_needs. |
| `supports_refresh` | boolean |  | true when the service issues refresh tokens; the token is then refreshed before runs. Default true. |
| `token_auth` | string: body, basic |  | How the token request sends the client credentials: body (form fields) or basic (HTTP Basic). Use what the docs say; body is the default. |
| `token_url` | string | yes | The service's OAuth 2.0 token endpoint (https), from its docs. |
| `use_pkce` | boolean |  | true when the service requires or supports PKCE (S256). |

Returns 201 with [OAuthProvider](#oauthprovider).

### GET /runs/{run_id}

Get a run with its logs.

MCP tool: `get_run`.

| Parameter | In | Type | Description |
|---|---|---|---|
| `run_id` | path | string | Run id (run_...). |
| `wait` | query | boolean | Wait up to about 45 seconds for a running run to finish. |

Returns 200 with [Run](#run).

### DELETE /session

Sign out: ends this sign-in for this workspace (MCP and the API), as disconnecting it in the ClickRuntime dashboard does.

Returns 200 with [SignedOut](#signedout).

### POST /setup-runs

Run a one-off discovery or setup script with the person's connections. Nothing is kept.

MCP tool: `run_setup_script`.

| Body field | Type | Required | Description |
|---|---|---|---|
| `changes` | string |  | Required for setup: one plain sentence on what the script creates or changes outside ClickRuntime. Leave out for discover. |
| `dependencies` | array of object |  | Extra PyPI packages the script imports that are not built in, such as [{"name": "tenacity", "version": "==9.0.0"}]. Pin an exact version. At most 15. Leave it out to keep the current list; [] removes them all. They install when the script deploys. |
| `purpose` | string: discover, setup | yes | discover: only reads, to find out something an automation needs. setup: creates or changes something outside ClickRuntime, once. |
| `script` | string | yes | The complete Python script with an @on_trigger handler from clickruntime. Read the script reference first. |
| `setup_needs` | array of object | yes | Every connection account and saved key the script reads through clickruntime.credentials. Before writing the script, call list_connections and ask the person which existing account to use for each service (or confirm the one there is); set up a new account only if they ask or none fits. For a service with no account yet, call list_app_catalog and use a ready-made app whose scopes and limits fit, without asking; draft an app of their own only when none fits. Never pick or invent an account name yourself. A script can read only what is declared here. An empty list means nothing to set up. Never put a key's value here. |
| `title` | string | yes | A short name the person will recognise, such as "Find the Tally form's fields". |

Returns 200 with [SetupRun](#setuprun).

## Response types

### AppCatalog

| Field | Type | Present | Description |
|---|---|---|---|
| `apps` | array of object or null | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `next` | Next or null |  | Present when the person must act before the agent continues. |

### Automation

| Field | Type | Present | Description |
|---|---|---|---|
| `automation_id` | string | always |  |
| `changes` | object or null |  |  |
| `connections_used` | array of string | always |  |
| `dependencies` | array of any | always |  |
| `deploy` | object or null |  | Deploy state once it has been turned on. |
| `effect` | string |  | What turning it on does, in one sentence. |
| `how_it_works` | object or null | always |  |
| `how_it_works_gaps` | array of any | always |  |
| `last_run` | Run or null |  |  |
| `layer` | object or null | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `message` | string |  |  |
| `name` | string | always |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `notes` | array of string | always |  |
| `outbound_hosts` | array of string | always |  |
| `pattern` | string: schedule, incoming, remember_then_schedule | always |  |
| `pending_change` | object or null |  |  |
| `retry` | object or null |  |  |
| `schedule` | Schedule or null |  |  |
| `script` | ScriptInfo or null |  |  |
| `setup` | Setup or null |  |  |
| `state` | string | always | Opaque version of the automation; pass as expected_state to POST /confirmations. |
| `status` | string: draft, live, paused | always |  |
| `summary` | string | always |  |
| `trigger` | Trigger or null |  |  |

### AutomationList

| Field | Type | Present | Description |
|---|---|---|---|
| `automations` | array of AutomationListItem | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `next_cursor` | string or null | always | Pass as ?cursor= for the next page; null on the last page. |
| `total` | integer | always |  |

### AutomationListItem

| Field | Type | Present | Description |
|---|---|---|---|
| `automation_id` | string | always |  |
| `dependency_count` | integer | always |  |
| `last_run` | Run or null | always |  |
| `name` | string | always |  |
| `pattern` | string: schedule, incoming, remember_then_schedule | always |  |
| `schedule` | Schedule or null |  |  |
| `status` | string: draft, live, paused | always |  |
| `summary` | string | always |  |
| `trigger` | Trigger or null |  |  |

### Confirmation

| Field | Type | Present | Description |
|---|---|---|---|
| `action` | string: enable, resume, run_now, apply_change, delete, send_test_event_live | always |  |
| `automation_id` | string | always |  |
| `confirmation_ref` | string | always | Poll GET /confirmations/{ref} with it. |
| `effect` | string |  |  |
| `expires_at` | string | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `name` | string | always |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `outbound_hosts` | array of string |  |  |
| `schedule` | Schedule or null |  |  |

### ConfirmationStatus

| Field | Type | Present | Description |
|---|---|---|---|
| `action` | string | always |  |
| `automation` | object or null | always |  |
| `automation_id` | string | always |  |
| `confirmation_ref` | string | always |  |
| `decided_at` | string or null | always |  |
| `decided_via` | string or null | always |  |
| `deleted` | boolean |  |  |
| `deploy` | object or null | always |  |
| `expires_at` | string | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `name` | string | always |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `run` | object or null | always |  |
| `state` | string: pending, confirmed, cancelled, expired, used | always | pending until the person decides. |

### Connect

| Field | Type | Present | Description |
|---|---|---|---|
| `account_label` | string |  |  |
| `already_connected` | boolean | always |  |
| `display_name` | string | always |  |
| `granted_scopes` | array of string | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `name` | string | always |  |
| `new_scopes` | array of string | always |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `provider` | string | always |  |
| `purpose` | string: automation, notifications | always |  |
| `scopes_plain` | array of string | always |  |
| `used_by` | array of string | always |  |
| `why_needed` | string |  |  |

### Connections

| Field | Type | Present | Description |
|---|---|---|---|
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `notifications` | object or null | always |  |
| `providers` | array of object or null | always |  |
| `secret_names` | array of string | always | Names of saved keys. Values are never returned. |

### Error

| Field | Type | Present | Description |
|---|---|---|---|
| `details` | object or null |  | Extra fields for the error code, for example missing or retry_after_seconds. |
| `error` | string | always | Stable error code. |
| `message` | string | always | What went wrong, in plain words. |
| `next` | Next or null |  |  |

### EventList

| Field | Type | Present | Description |
|---|---|---|---|
| `automation_id` | string | always |  |
| `events` | array of object or null | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `name` | string | always |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `next_cursor` | string or null | always |  |

### Issue

| Field | Type | Present | Description |
|---|---|---|---|
| `category` | string: bug, connection, billing, other | always |  |
| `created_at` | string | always |  |
| `has_support_reply` | boolean | always |  |
| `id` | string | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `messages` | array of object or null |  |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `run_id` | string |  |  |
| `source` | string | always |  |
| `status` | string: open, waiting_on_user, resolved, closed | always |  |
| `title` | string | always |  |
| `updated_at` | string | always |  |

### IssueList

| Field | Type | Present | Description |
|---|---|---|---|
| `issues` | array of Issue | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `next` | Next or null |  | Present when the person must act before the agent continues. |

### LatestEvent

| Field | Type | Present | Description |
|---|---|---|---|
| `automation_id` | string | always |  |
| `event` | object or null | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `name` | string | always |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `status` | string | always |  |
| `trigger` | Trigger or null |  |  |

### Next

| Field | Type | Present | Description |
|---|---|---|---|
| `action` | string: open_link, login, wait, retry, fix_request |  | Machine-readable step. |
| `say` | string | always | One sentence to tell the person. |
| `url` | string |  | Link for the person. Give it exactly as returned; never build or change it. |

### OAuthProvider

| Field | Type | Present | Description |
|---|---|---|---|
| `auth_params` | object or null | always |  |
| `authorize_url` | string | always |  |
| `callback_url` | string | always |  |
| `client_id_last4` | string |  |  |
| `has_secret` | boolean | always | True once the person saved the app's secret in the ClickRuntime dashboard. |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `missing` | array of string |  |  |
| `name` | string | always |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `provider_id` | string | always |  |
| `scope_separator` | string | always |  |
| `scopes` | array of string | always |  |
| `slug` | string | always |  |
| `status` | string | always |  |
| `supports_refresh` | boolean | always |  |
| `token_auth` | string | always |  |
| `token_url` | string | always |  |
| `use_pkce` | boolean | always |  |
| `warning` | string |  |  |

### Profile

| Field | Type | Present | Description |
|---|---|---|---|
| `email` | string | always |  |
| `id` | string | always | Stable id for this person in this workspace. |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `name` | string | always |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `nickname` | string | always |  |

### Run

| Field | Type | Present | Description |
|---|---|---|---|
| `attempt` | integer | always |  |
| `automation_id` | string | always |  |
| `automation_name` | string |  |  |
| `connection` | object or null |  |  |
| `counted` | boolean | always | True when the run counts toward the plan's runs. |
| `created_at` | string | always |  |
| `duration_ms` | integer or null | always |  |
| `error` | string or null | always |  |
| `error_kind` | string |  |  |
| `event` | object or null |  |  |
| `fetched` | any | always |  |
| `finished_at` | string or null | always |  |
| `id` | string | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `logs` | array of any |  |  |
| `logs_truncated` | boolean |  |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `scheduled_time` | string or null | always |  |
| `started_at` | string or null | always |  |
| `status` | string: queued, running, succeeded, failed, timed_out, skipped | always |  |
| `summary` | any | always |  |
| `trigger` | string | always | What started the run, for example schedule, incoming or manual. |
| `unbilled_reason` | string or null | always |  |

### RunList

| Field | Type | Present | Description |
|---|---|---|---|
| `automation_id` | string | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `name` | string | always |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `next_cursor` | string or null | always |  |
| `runs` | array of Run | always |  |

### RuntimeDoc

| Field | Type | Present | Description |
|---|---|---|---|
| `content` | string | always | The script reference: handlers, the event object, state, notify, http, and allowed packages. |
| `format` | string: markdown | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `next` | Next or null |  | Present when the person must act before the agent continues. |

### Schedule

| Field | Type | Present | Description |
|---|---|---|---|
| `armed` | boolean | always | True when the schedule is active. |
| `description` | string | always |  |
| `next_runs` | array of string | always | Next run times, ISO 8601. |
| `spec` | object or null | always | The schedule as saved: kind, time, timezone. |

### Script

| Field | Type | Present | Description |
|---|---|---|---|
| `automation_id` | string | always |  |
| `code` | string | always |  |
| `lines` | integer | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `redacted` | boolean | always |  |
| `sha256` | string | always |  |
| `version` | any | always |  |

### ScriptInfo

| Field | Type | Present | Description |
|---|---|---|---|
| `lines` | integer | always |  |
| `sha256` | string | always |  |

### Setup

| Field | Type | Present | Description |
|---|---|---|---|
| `items` | array of SetupItem | always |  |
| `ready` | boolean | always |  |

### SetupItem

| Field | Type | Present | Description |
|---|---|---|---|
| `account` | string |  |  |
| `builtin` | boolean |  |  |
| `hint` | string |  |  |
| `id` | string | always |  |
| `kind` | string: connection, secret | always |  |
| `name` | string | always |  |
| `provider` | string |  |  |
| `ready` | boolean | always |  |
| `scopes_plain` | array of string |  |  |
| `url` | string |  | Where the person does this step in the ClickRuntime dashboard. Keys are only ever entered there. |
| `why_needed` | string |  |  |

### SetupRun

| Field | Type | Present | Description |
|---|---|---|---|
| `attempt` | integer | always |  |
| `automation_id` | string | always |  |
| `automation_name` | string |  |  |
| `connection` | object or null |  |  |
| `counted` | boolean | always | True when the run counts toward the plan's runs. |
| `created_at` | string | always |  |
| `duration_ms` | integer or null | always |  |
| `error` | string or null | always |  |
| `error_kind` | string |  |  |
| `event` | object or null |  |  |
| `fetched` | any | always |  |
| `finished_at` | string or null | always |  |
| `id` | string | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `logs` | array of any |  |  |
| `logs_truncated` | boolean |  |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `purpose` | string: discover, setup | always |  |
| `scheduled_time` | string or null | always |  |
| `setup_run_id` | string | always |  |
| `started_at` | string or null | always |  |
| `status` | string: queued, running, succeeded, failed, timed_out, skipped | always |  |
| `summary` | any | always |  |
| `trigger` | string | always | What started the run, for example schedule, incoming or manual. |
| `unbilled_reason` | string or null | always |  |

### SetupStatus

| Field | Type | Present | Description |
|---|---|---|---|
| `automation_id` | string | always |  |
| `current_step` | object or null |  |  |
| `items` | array of SetupItem | always |  |
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `name` | string | always |  |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `ready` | boolean | always | True when every setup step is done. |
| `status` | string: draft, live, paused | always |  |
| `steps` | array of string | always | Steps left for the person, in order. |

### SignedOut

| Field | Type | Present | Description |
|---|---|---|---|
| `links` | object or null |  | Links for the person (ClickRuntime dashboard pages, confirm pages, consent pages). Give them exactly as returned. |
| `next` | Next or null |  | Present when the person must act before the agent continues. |
| `signed_out` | boolean | always |  |

### Trigger

| Field | Type | Present | Description |
|---|---|---|---|
| `armed` | boolean | always |  |
| `last_event_at` | string or null |  |  |
| `require_signature` | boolean | always |  |
| `signature` | object or null |  |  |
| `url` | string | always | Trigger link. An event POSTed to it starts a run. |
