Automations
Roads between apps: schedules, webhooks, forms and heartbeats, pausing them and running them now. 14 routes, from the API’s own OpenAPI document.
14 routes. Every path starts at https://cloud-api.qaldy.com. Sign-in, tokens, errors and limits are on the overview.
Routes#
| Method | Path | What it does |
|---|---|---|
| GET | /v1/automations/{id} | One automation with its recent runs |
| PATCH | /v1/automations/{id} | Rename an automation, change its trigger or schedule, or redraw its stops |
| DELETE | /v1/automations/{id} | Delete an automation: its road leaves the City, its past runs stay |
| GET | /v1/automations/{id}/heartbeat | The heartbeat: what is expected, how it is doing, runs per day and who is told |
| PUT | /v1/automations/{id}/heartbeat | Set how often it must run (at least N per hour or day) and who hears when it is quiet |
| POST | /v1/automations/{id}/pause | Pause an automation: its road stays, nothing drives it |
| POST | /v1/automations/{id}/resume | Resume a paused automation: it comes back as healthy or failing as its gates, app and last run say |
| POST | /v1/automations/{id}/runs | Run an automation now: a car drives its road |
| GET | /v1/automations/{id}/webhook | The webhook: its address, switches, secret hint and the last ten deliveries |
| POST | /v1/automations/{id}/webhook | Set the webhook up: creates its secret (or token), shown once |
| PATCH | /v1/automations/{id}/webhook | Switch the webhook on or off, change its proof mode or its rate limit |
| POST | /v1/automations/{id}/webhook/rotate | Rotate the secret: a new one, shown once; the old one stops working at once |
| POST | /v1/automations/{id}/webhook/test | Send a signed sample event through the real webhook path (a run starts) |
| GET | /v1/workspaces/{ws}/automations | Every automation (road) in a workspace you can see, with this week’s numbers |
Reference#
GET /v1/automations/{id}#
One automation with its recent runs.
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
readscope. - Who:
can_viewon every app it stops at, else 404
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | at least 1 characters |
name | string | yes | at least 1 characters |
from | object | yes | |
from.kind | "gate" · "building" | yes | |
from.id | string | yes | at least 1 characters |
via | object[] | yes | up to 6 items |
via[].kind | "gate" · "building" | yes | |
via[].id | string | yes | at least 1 characters |
to | object | yes | |
to.kind | "gate" · "building" | yes | |
to.id | string | yes | at least 1 characters |
category | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes | |
status | "active" · "paused" · "failing" | yes | |
trigger | object | yes | |
appId | string or null | yes | |
webhookUrl | string or null | yes | |
webhookLive | boolean | ||
nextRunAt | string (date-time) or null | yes | |
stats | object | yes | |
stats.runsWeek | integer | yes | at least 0 |
stats.failedWeek | integer | yes | at least 0 |
stats.minutesSavedWeek | number | yes | at least 0 |
stats.lastRunAt | string (date-time) or null | yes | |
stats.lastRunStatus | "queued" · "running" · "waiting_approval" · "succeeded" · "failed" · "blocked" · null or null | yes | |
heartbeat | object or null | ||
heartbeat.state | "healthy" · "quiet" · "alerting" · "off" | yes | |
heartbeat.expect | object | yes | |
heartbeat.quietSince | string (date-time) or null | yes | |
canEdit | boolean | yes | |
createdAt | string (date-time) | yes |
…and 2 more fields. The full schema is in openapi.json.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
PATCH /v1/automations/{id}#
Rename an automation, change its trigger or schedule, or redraw its stops.
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who:
can_editon the driving app (+ every app when redrawn)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | 1 to 60 characters | |
trigger | object | ||
via | object[] | up to 6 items | |
via[].kind | "gate" · "building" | yes | |
via[].id | string | yes | at least 1 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | at least 1 characters |
name | string | yes | at least 1 characters |
from | object | yes | |
from.kind | "gate" · "building" | yes | |
from.id | string | yes | at least 1 characters |
via | object[] | yes | up to 6 items |
via[].kind | "gate" · "building" | yes | |
via[].id | string | yes | at least 1 characters |
to | object | yes | |
to.kind | "gate" · "building" | yes | |
to.id | string | yes | at least 1 characters |
category | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes | |
status | "active" · "paused" · "failing" | yes | |
trigger | object | yes | |
appId | string or null | yes | |
webhookUrl | string or null | yes | |
webhookLive | boolean | ||
nextRunAt | string (date-time) or null | yes | |
stats | object | yes | |
stats.runsWeek | integer | yes | at least 0 |
stats.failedWeek | integer | yes | at least 0 |
stats.minutesSavedWeek | number | yes | at least 0 |
stats.lastRunAt | string (date-time) or null | yes | |
stats.lastRunStatus | "queued" · "running" · "waiting_approval" · "succeeded" · "failed" · "blocked" · null or null | yes | |
heartbeat | object or null | ||
heartbeat.state | "healthy" · "quiet" · "alerting" · "off" | yes | |
heartbeat.expect | object | yes | |
heartbeat.quietSince | string (date-time) or null | yes | |
canEdit | boolean | yes | |
createdAt | string (date-time) | yes |
…and 1 more fields. The full schema is in openapi.json.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
DELETE /v1/automations/{id}#
Delete an automation: its road leaves the City, its past runs stay.
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who:
can_editon the driving app
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
ok | true | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
GET /v1/automations/{id}/heartbeat#
The heartbeat: what is expected, how it is doing, runs per day and who is told.
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
settings | object or null | yes | |
settings.enabled | boolean | yes | |
settings.expect | object | yes | |
settings.notify | object[] | yes | up to 4 items |
status | object or null | yes | |
status.state | "healthy" · "quiet" · "alerting" · "off" | yes | |
status.expect | object | yes | |
status.quietSince | string (date-time) or null | yes | |
series | integer[] | yes | |
expectedPerDay | number or null | yes | at least 0 |
windowCount | integer | yes | at least 0 |
alertedAt | string (date-time) or null | yes | |
channels | object | yes | |
channels.telegram | object[] | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
PUT /v1/automations/{id}/heartbeat#
Set how often it must run (at least N per hour or day) and who hears when it is quiet.
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | yes | |
expect | object | yes | |
expect.atLeast | integer | yes | 1 to 10000 |
expect.per | "hour" · "day" | yes | |
notify | object[] | yes | up to 4 items |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
settings | object or null | yes | |
settings.enabled | boolean | yes | |
settings.expect | object | yes | |
settings.notify | object[] | yes | up to 4 items |
status | object or null | yes | |
status.state | "healthy" · "quiet" · "alerting" · "off" | yes | |
status.expect | object | yes | |
status.quietSince | string (date-time) or null | yes | |
series | integer[] | yes | |
expectedPerDay | number or null | yes | at least 0 |
windowCount | integer | yes | at least 0 |
alertedAt | string (date-time) or null | yes | |
channels | object | yes | |
channels.telegram | object[] | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/automations/{id}/pause#
Pause an automation: its road stays, nothing drives it.
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who:
can_editon the driving app
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Request body (application/json)
An empty object: {}.
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | at least 1 characters |
name | string | yes | at least 1 characters |
from | object | yes | |
from.kind | "gate" · "building" | yes | |
from.id | string | yes | at least 1 characters |
via | object[] | yes | up to 6 items |
via[].kind | "gate" · "building" | yes | |
via[].id | string | yes | at least 1 characters |
to | object | yes | |
to.kind | "gate" · "building" | yes | |
to.id | string | yes | at least 1 characters |
category | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes | |
status | "active" · "paused" · "failing" | yes | |
trigger | object | yes | |
appId | string or null | yes | |
webhookUrl | string or null | yes | |
webhookLive | boolean | ||
nextRunAt | string (date-time) or null | yes | |
stats | object | yes | |
stats.runsWeek | integer | yes | at least 0 |
stats.failedWeek | integer | yes | at least 0 |
stats.minutesSavedWeek | number | yes | at least 0 |
stats.lastRunAt | string (date-time) or null | yes | |
stats.lastRunStatus | "queued" · "running" · "waiting_approval" · "succeeded" · "failed" · "blocked" · null or null | yes | |
heartbeat | object or null | ||
heartbeat.state | "healthy" · "quiet" · "alerting" · "off" | yes | |
heartbeat.expect | object | yes | |
heartbeat.quietSince | string (date-time) or null | yes | |
canEdit | boolean | yes | |
createdAt | string (date-time) | yes |
…and 1 more fields. The full schema is in openapi.json.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/automations/{id}/resume#
Resume a paused automation: it comes back as healthy or failing as its gates, app and last run say.
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token). - Who:
can_editon the driving app
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Request body (application/json)
An empty object: {}.
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | at least 1 characters |
name | string | yes | at least 1 characters |
from | object | yes | |
from.kind | "gate" · "building" | yes | |
from.id | string | yes | at least 1 characters |
via | object[] | yes | up to 6 items |
via[].kind | "gate" · "building" | yes | |
via[].id | string | yes | at least 1 characters |
to | object | yes | |
to.kind | "gate" · "building" | yes | |
to.id | string | yes | at least 1 characters |
category | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes | |
status | "active" · "paused" · "failing" | yes | |
trigger | object | yes | |
appId | string or null | yes | |
webhookUrl | string or null | yes | |
webhookLive | boolean | ||
nextRunAt | string (date-time) or null | yes | |
stats | object | yes | |
stats.runsWeek | integer | yes | at least 0 |
stats.failedWeek | integer | yes | at least 0 |
stats.minutesSavedWeek | number | yes | at least 0 |
stats.lastRunAt | string (date-time) or null | yes | |
stats.lastRunStatus | "queued" · "running" · "waiting_approval" · "succeeded" · "failed" · "blocked" · null or null | yes | |
heartbeat | object or null | ||
heartbeat.state | "healthy" · "quiet" · "alerting" · "off" | yes | |
heartbeat.expect | object | yes | |
heartbeat.quietSince | string (date-time) or null | yes | |
canEdit | boolean | yes | |
createdAt | string (date-time) | yes |
…and 1 more fields. The full schema is in openapi.json.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/automations/{id}/runs#
Run an automation now: a car drives its road.
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
writescope. - Who:
can_runon the driving app
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Request body (application/json)
An empty object: {}.
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
runId | string | yes | at least 1 characters |
held | boolean |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
GET /v1/automations/{id}/webhook#
The webhook: its address, switches, secret hint and the last ten deliveries.
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
webhook | object | yes | |
webhook.configured | boolean | yes | |
webhook.url | string or null | yes | |
webhook.enabled | boolean | yes | |
webhook.mode | "signed" · "github" · "token" · "telegram" · "form" · "unsigned" | yes | |
webhook.secretHint | string or null | yes | |
webhook.ratePerMin | integer | yes | 1 to 600 |
webhook.createdAt | string (date-time) or null | yes | |
webhook.rotatedAt | string (date-time) or null | yes | |
webhook.form | object or null | default null | |
deliveries | object[] | yes | up to 50 items |
deliveries[].id | string | yes | at least 1 characters |
deliveries[].at | string (date-time) | yes | |
deliveries[].outcome | "accepted" · "duplicate" · "rejected" | yes | |
deliveries[].status | integer | yes | 100 to 599 |
deliveries[].reason | string or null | yes | |
deliveries[].runId | string or null | yes | |
deliveries[].bytes | integer | yes | at least 0 |
deliveries[].sample | boolean | yes | |
deliveries[].deadLetterId | string or null | default null |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/automations/{id}/webhook#
Set the webhook up: creates its secret (or token), shown once.
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
mode | "signed" · "github" · "token" · "telegram" · "form" · "unsigned" |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
webhook | object | yes | |
webhook.configured | boolean | yes | |
webhook.url | string or null | yes | |
webhook.enabled | boolean | yes | |
webhook.mode | "signed" · "github" · "token" · "telegram" · "form" · "unsigned" | yes | |
webhook.secretHint | string or null | yes | |
webhook.ratePerMin | integer | yes | 1 to 600 |
webhook.createdAt | string (date-time) or null | yes | |
webhook.rotatedAt | string (date-time) or null | yes | |
webhook.form | object or null | default null | |
secret | string or null | yes | at least 1 characters |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
PATCH /v1/automations/{id}/webhook#
Switch the webhook on or off, change its proof mode or its rate limit.
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | ||
mode | "signed" · "github" · "token" · "telegram" · "form" · "unsigned" | ||
ratePerMin | integer | 1 to 600 | |
acknowledgeUnsigned | boolean | ||
form | object | ||
form.honeypot | string | yes | |
form.redirect | string or null | yes | up to 500 characters |
form.origins | string[] | yes | up to 5 items |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
webhook | object | yes | |
webhook.configured | boolean | yes | |
webhook.url | string or null | yes | |
webhook.enabled | boolean | yes | |
webhook.mode | "signed" · "github" · "token" · "telegram" · "form" · "unsigned" | yes | |
webhook.secretHint | string or null | yes | |
webhook.ratePerMin | integer | yes | 1 to 600 |
webhook.createdAt | string (date-time) or null | yes | |
webhook.rotatedAt | string (date-time) or null | yes | |
webhook.form | object or null | default null | |
secret | string or null | yes | at least 1 characters |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/automations/{id}/webhook/rotate#
Rotate the secret: a new one, shown once; the old one stops working at once.
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Request body (application/json)
An empty object: {}.
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
webhook | object | yes | |
webhook.configured | boolean | yes | |
webhook.url | string or null | yes | |
webhook.enabled | boolean | yes | |
webhook.mode | "signed" · "github" · "token" · "telegram" · "form" · "unsigned" | yes | |
webhook.secretHint | string or null | yes | |
webhook.ratePerMin | integer | yes | 1 to 600 |
webhook.createdAt | string (date-time) or null | yes | |
webhook.rotatedAt | string (date-time) or null | yes | |
webhook.form | object or null | default null | |
secret | string or null | yes | at least 1 characters |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
POST /v1/automations/{id}/webhook/test#
Send a signed sample event through the real webhook path (a run starts).
- Authentication: the console’s session cookie.
- Token: not available. This route is for a signed-in person in the console (
403 console_onlyfor a token).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
id | path | string | yes | 1 to 128 characters |
Request body (application/json)
An empty object: {}.
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
delivery | object | yes | |
delivery.id | string | yes | at least 1 characters |
delivery.at | string (date-time) | yes | |
delivery.outcome | "accepted" · "duplicate" · "rejected" | yes | |
delivery.status | integer | yes | 100 to 599 |
delivery.reason | string or null | yes | |
delivery.runId | string or null | yes | |
delivery.bytes | integer | yes | at least 0 |
delivery.sample | boolean | yes | |
delivery.deadLetterId | string or null | default null | |
runId | string or null | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
GET /v1/workspaces/{ws}/automations#
Every automation (road) in a workspace you can see, with this week’s numbers.
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
readscope. - Who: member (only roads whose apps you can view)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
ws | path | string | yes | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
items | object[] | yes | |
items[].id | string | yes | at least 1 characters |
items[].name | string | yes | at least 1 characters |
items[].from | object | yes | |
items[].via | object[] | yes | up to 6 items |
items[].to | object | yes | |
items[].category | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes | |
items[].status | "active" · "paused" · "failing" | yes | |
items[].trigger | object | yes | |
items[].appId | string or null | yes | |
items[].webhookUrl | string or null | yes | |
items[].webhookLive | boolean | ||
items[].nextRunAt | string (date-time) or null | yes | |
items[].stats | object | yes | |
items[].heartbeat | object or null | ||
items[].canEdit | boolean | yes | |
items[].createdAt | string (date-time) | yes | |
items[].updatedAt | string (date-time) | yes |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).