Schedule operations. Substrio docs

`job`

`job.cancel`

Cancel one running background job by id: answers the job; 404 when no such job, and refused when it already ended.

Route: POST /v1/_jobs/{id}/cancel
Auth: App key tenant
MCP tool: substrio_job_cancel
CLI: substrio op job.cancel

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_jobs/$ID/cancel" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`job.get`

Read one background job by id: its status, progress and, for a backup, the backup id.

Route: GET /v1/_jobs/{id}
Auth: App key tenant
MCP tool: substrio_job_get
CLI: substrio op job.get

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The job's id, as `job.list` returned it.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_jobs/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`job.list`

List the app's background jobs (re-embeds and other long operations) and their status and progress, oldest first, a page at a time (limit, cursor; next_cursor).

Route: GET /v1/_jobs
Auth: App key tenant
MCP tool: substrio_job_list
CLI: substrio op job.list

Parameters

Name	In	Type	Required	Description
`limit`	query	`integer (0 or more)`	No	the most items per page (positive); absent returns every item.
`cursor`	query	`string`	No	resume after the previous page: its next_cursor.
`limit`	query	`integer`	No	Rows a page: 100 by default, capped at 1000. Minimum 1.
`cursor`	query	`string`	No	The next_cursor of the page before: the walk resumes past it.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_jobs" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`queue`

Page a queue's dead letters, oldest first: messages that failed more than max_retries times and have no dead_letter_queue; each has its seq, attempts and body. Page with limit and cursor (the answer's next).

Route: GET /v1/_queues/{id}/dead
Auth: App key tenant
MCP tool: substrio_queue_dead_letters
CLI: substrio op queue.dead_letters

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The queue's name, as `queue.list` names it.
`limit`	query	`integer (0 or more)`	No	the most items per page (positive); absent returns every item.
`cursor`	query	`string`	No	resume after the previous page: its next_cursor.

Response

Field	Type	Present	Description
`name`	`string`	Always
`messages`	`array of object`	Always
`count`	`integer`	Always
`next`	`integer or null`	Always	the cursor of the next page; null at the end.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_queues/$ID/dead" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`queue.list`

List the app's durable queues (declared in the version's queues): name, consumer function, dead_letter_queue and every setting in effect. queue.stats counts a queue's messages.

Route: GET /v1/_queues
Auth: App key tenant
MCP tool: substrio_queue_list
CLI: substrio op queue.list

Parameters

No parameters.

Response

Field	Type	Present	Description
`queues`	`array of object`	Always
`count`	`integer`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_queues" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`queue.purge`

Remove a queue's messages for good: scope pending (default: waiting, delayed and in-flight), dead (the dead letters) or all. Answers how many were removed; 404 when the queue is not declared.

Route: POST /v1/_queues/{id}/purge
Auth: App key tenant
MCP tool: substrio_queue_purge
CLI: substrio op queue.purge

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The queue's name, as `queue.list` names it.
`scope`	body	`"pending" \| "dead" \| "all"`	No	pending: waiting, delayed and in-flight messages; dead: the dead letters; all: both. Default `"pending"`.

Response

Field	Type	Present	Description
`success`	`boolean`	Always
`name`	`string`	Always
`purged`	`integer`	Always	messages removed.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_queues/$ID/purge" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`queue.retry_dead`

Send dead letters back to their queue with their attempts reset: one by seq, or every dead message when seq is absent. Answers how many were retried.

Route: POST /v1/_queues/{id}/retry-dead
Auth: App key tenant
MCP tool: substrio_queue_retry_dead
CLI: substrio op queue.retry_dead

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The queue's name, as `queue.list` names it.
`seq`	body	`integer`	No	one dead message, by its seq; absent retries every dead message. Minimum 1.

Response

Field	Type	Present	Description
`success`	`boolean`	Always
`name`	`string`	Always
`retried`	`integer`	Always	dead messages sent back to the queue.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_queues/$ID/retry-dead" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`queue.stats`

Count one queue's messages: ready (deliverable now), in_flight (delivered, visibility timeout not over), delayed (send delay or retry backoff) and dead (past max_retries); 404 when the queue is not declared.

Route: GET /v1/_queues/{id}/stats
Auth: App key tenant
MCP tool: substrio_queue_stats
CLI: substrio op queue.stats

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The queue's name, as `queue.list` names it.

Response

Field	Type	Present	Description
`name`	`string`	Always
`ready`	`integer`	Always	messages deliverable now.
`in_flight`	`integer`	Always	delivered, visibility timeout not yet over.
`delayed`	`integer`	Always	waiting for a send delay or a retry backoff.
`dead`	`integer`	Always	messages that used all their retries and sit in the dead letters.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_queues/$ID/stats" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`schedule`

`schedule.create`

Create a cron schedule: body function (the function to run, which must define a scheduled handler or a default export) and expression (five fields; one that never fires, like 31 February, is refused), optionally timezone (an IANA zone id the expression is evaluated in, default UTC; an unknown id is refused) and catch_up (none, last or all: what fires missed while the server was down do; default last). A run that fails or is refused is retried with backoff (settings cron.max_attempts, cron.backoff_ms), then goes to _dead_letters. Answers {id, success}; the id is what schedule.run, schedule.next, schedule.history, schedule.update and schedule.delete take.

Route: POST /v1/_cron
Auth: App key tenant
MCP tool: substrio_schedule_create
CLI: substrio op schedule.create

Parameters

Name	In	Type	Required	Description
`function`	body	`string`	Yes
`expression`	body	`string`	Yes	Five-field cron expression, evaluated in the schedule's time zone (UTC by default); one that never fires (31 February, minute 60) is refused.
`timezone`	body	`string`	No	IANA time zone id the expression is evaluated in, as Europe/Berlin; default UTC. An unknown id is refused. A wall time the zone skips (the hour a clock jumps over) does not fire; one it repeats fires both times.
`catch_up`	body	`"none" \| "last" \| "all"`	No	What a fire missed while the server was down or busy does: none drops it, last runs the latest missed fire once (the default), all runs every missed fire, oldest first.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_cron" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"function":"function","expression":"expression"}'

`schedule.delete`

Delete one cron schedule by id; 404 when it does not exist.

Route: DELETE /v1/_cron/{id}
Auth: App key tenant
MCP tool: substrio_schedule_delete
CLI: substrio op schedule.delete

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The schedule's id, as `schedule.list` or `schedule.create` returned it (for example 7_1).

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_cron/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`schedule.history`

Page a schedule's stored runs, newest first: start time (Unix seconds and ISO 8601 UTC), duration, outcome and the function.errors entry id of a failed run; every run is kept; page with count and cursor.

Route: GET /v1/_cron/{id}/history
Auth: App key tenant
MCP tool: substrio_schedule_history
CLI: substrio op schedule.history

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The schedule's id, as `schedule.list` or `schedule.create` returned it (for example 7_1).
`cursor`	query	`string`	No	resume after the previous page: its next_cursor.
`count`	query	`integer (0 or more)`	No	`schedule.next`: how many fire times to list (default 5, at most 1000); `schedule.history`: the page size (absent: every run).

Response

Field	Type	Present
`id`	`string`	Always
`runs`	`array of object`	Always
`count`	`integer`	Always
`next_cursor`	`string or null`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_cron/$ID/history" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`schedule.list`

List the app's cron schedules; schedule.next and schedule.history say when they fire and what happened.

Route: GET /v1/_cron
Auth: App key tenant
MCP tool: substrio_schedule_list
CLI: substrio op schedule.list

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_cron" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`schedule.next`

List a schedule's next fire times (in its time zone's wall clock) as Unix seconds and ISO 8601 UTC; an expression that never fires is refused.

Route: GET /v1/_cron/{id}/next
Auth: App key tenant
MCP tool: substrio_schedule_next
CLI: substrio op schedule.next

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The schedule's id, as `schedule.list` or `schedule.create` returned it (for example 7_1).
`count`	query	`integer (0 or more)`	No	`schedule.next`: how many fire times to list (default 5, at most 1000); `schedule.history`: the page size (absent: every run).

Response

Field	Type	Present	Description
`id`	`string`	Always
`expression`	`string`	Always
`enabled`	`boolean`	Always
`timezone`	`string`	Always	the schedule's IANA zone id (UTC when it has none).
`catch_up`	`"none" \| "last" \| "all"`	When set
`fires_at`	`array of integer`	Always	Unix seconds, soonest first.
`fires_at_iso`	`array of string`	Always	the same times as ISO 8601 UTC.
`count`	`integer`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_cron/$ID/next" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`schedule.run`

Run a schedule's function now with its cron event, and record the run in the schedule's history.

Route: POST /v1/_cron/{id}/run
Auth: App key tenant
MCP tool: substrio_schedule_run
CLI: substrio op schedule.run

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The schedule's id, as `schedule.list` or `schedule.create` returned it (for example 7_1).

Response

Field	Type	Present	Description
`success`	`boolean`	Always
`id`	`string`	Always
`outcome`	`"ok" \| "error"`	Always
`started_at`	`integer`	When set	Unix seconds.
`started_at_iso`	`string`	When set	ISO 8601 UTC.
`duration_ms`	`integer`	Always
`error_id`	`string or null`	Always	the `function.errors` entry the run threw, when it did.
`error`	`string or null`	When set
`result`	`any`	When set

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_cron/$ID/run" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`schedule.update`

Enable or disable one cron schedule: body enabled (required boolean), the route's {id}. Answers {success, updated, enabled}; 404 when no such schedule.

Route: PATCH /v1/_cron/{id}
Auth: App key tenant
MCP tool: substrio_schedule_update
CLI: substrio op schedule.update

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes
`enabled`	body	`boolean`	Yes

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_cron/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

`webhook`

`webhook.create`

Create a webhook route; see the schema for its body.

Route: POST /v1/_webhooks
Auth: App key tenant
MCP tool: substrio_webhook_create
CLI: substrio op webhook.create

Parameters

Name	In	Type	Required	Description
`url`	body	`string`	Yes
`collection`	body	`string`	No	Default `"*"`.
`event`	body	`string`	No	The change to deliver; also read as events. Default `"*"`.
`secret`	body	`string`	No	Signs each delivery.
`transform`	body	`string`	No
`app_event`	body	`string`	No	Deliver an event the app publishes itself with substrio.webhooks.emit, by name or * for all; no collection or event with it. Matches `^([A-Za-z0-9._-]+\|\*)$`.
`scope`	body	`string`	No	With app_event: only the events emitted for this part of the app, such as one account.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_webhooks" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"url"}'

`webhook.delete`

Delete one webhook route by its id (the route's {id}, as webhook.list shows it).

Route: DELETE /v1/_webhooks/{id}
Auth: App key tenant
MCP tool: substrio_webhook_delete
CLI: substrio op webhook.delete

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The webhook's id, as `webhook.list` returned it.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_webhooks/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`webhook.get`

Read one webhook route by its id (the route's {id}, as webhook.list shows it).

Route: GET /v1/_webhooks/{id}
Auth: App key tenant
MCP tool: substrio_webhook_get
CLI: substrio op webhook.get

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The webhook's id, as `webhook.list` returned it.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_webhooks/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`webhook.list`

List the app's webhook routes (optionally only those of one scope), oldest first, a page at a time (limit, cursor; next_cursor).

Route: GET /v1/_webhooks
Auth: App key tenant
MCP tool: substrio_webhook_list
CLI: substrio op webhook.list

Parameters

Name	In	Type	Required	Description
`scope`	query	`string`	No	only the app-event webhooks of this scope.
`limit`	query	`integer (0 or more)`	No	the most items per page (positive); absent returns every item.
`cursor`	query	`string`	No	resume after the previous page: its next_cursor.
`scope`	query	`string`	No	Only the app-event webhooks of this scope.
`limit`	query	`integer`	No	Rows a page: 100 by default, capped at 1000. Minimum 1.
`cursor`	query	`string`	No	The next_cursor of the page before: the walk resumes past it.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_webhooks" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`webhook.replay`

Send a stored webhook delivery again under its same delivery id: the route's {id} is the delivery id (the <brand>-Delivery-Id header the receiver saw, or a dead letter's delivery_id). A delivered or dead delivery gets a new attempt count; a pending one is refused.

Route: POST /v1/_webhooks/deliveries/{id}/replay
Auth: App key tenant
MCP tool: substrio_webhook_replay
CLI: substrio op webhook.replay

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The delivery's id (dlv_ and 24 hex digits):the value of the <brand>-Delivery-Id header the receiver saw, or the delivery_id of a dead letter.

Response

Field	Type	Present	Description
`success`	`boolean`	Always
`delivery_id`	`string`	Always	the delivery that was queued again.
`status`	`"queued"`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_webhooks/deliveries/$ID/replay" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`webhook.update`

Enable or disable one webhook route: body id and enabled; the route's {id}.

Route: PATCH /v1/_webhooks/{id}
Auth: App key tenant
MCP tool: substrio_webhook_update
CLI: substrio op webhook.update

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes
`enabled`	body	`boolean`	Yes

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_webhooks/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'