Orbit Executions API
Workflow runs — trigger pre-deploy executions and observe them as async jobs
Workflow runs — trigger pre-deploy executions and observe them as async jobs
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/orbitapps-io:orbitapps-io-executions-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Orbit Apps Executions API
version: 1.0.0
description: Public REST API for Orbit Apps.
servers:
- url: https://api.orbitapps.io
description: Production
security:
- bearerAuth: []
tags:
- name: Executions
description: Workflow runs — trigger pre-deploy executions and observe them as async jobs
paths:
/api/v1/executions/{id}/cancel:
post:
parameters:
- in: path
name: id
required: true
schema:
type: string
format: uuid
description: Execution id from POST /api/v1/workspaces/{id}/executions
responses:
'200':
description: The execution after the cancel (or its terminal state when already finished).
content:
application/json:
schema:
title: Execution
description: One workflow run — the uniform async-job shape. Poll until `status` turns terminal, or tail /events.
type: object
properties:
workspace_id:
description: The workflow workspace this run executed.
type: string
format: uuid
org_id:
description: Owning org id.
type: string
format: uuid
app_id:
description: Owning app id.
type: string
format: uuid
updated_at:
description: RFC 3339 timestamp.
oneOf:
- type: string
- type: 'null'
status:
description: running | succeeded | failed | cancelled.
type: string
result:
description: The workflow's result once status=succeeded. Null while running.
id:
description: Stable UUIDv7 identifier.
type: string
format: uuid
error:
description: Structured failure ({node_id, message}) once status=failed.
oneOf:
- type: object
additionalProperties: {}
- type: 'null'
seq:
description: Latest event's seq — resume /events with ?after_seq= from here.
type: integer
created_at:
description: RFC 3339 timestamp.
oneOf:
- type: string
- type: 'null'
required:
- id
- org_id
- app_id
- workspace_id
- status
- seq
- created_at
- updated_at
additionalProperties: false
'403':
description: Caller has visibility but lacks the role to cancel.
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
'404':
description: Execution does not exist, or the caller has no visibility.
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
'409':
description: The run is live on another instance — it cannot be stopped from here.
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
tags:
- Executions
summary: Cancel a running execution
description: 'Stops the run and persists `status=cancelled`. Cancelling an already-finished run is idempotent — 200 with the run''s real outcome.
Cancel is process-local: a running row whose handle lives on another api instance (or was orphaned by a restart) answers 409 `execution-not-cancellable`.
Authorization: `[:write :resource]` (owner/admin/member).'
operationId: postApiV1ExecutionsByIdCancel
x-operation-id-source: derived
/api/v1/executions/{id}/events:
get:
parameters:
- in: path
name: id
required: true
schema:
type: string
format: uuid
description: Execution id from POST /api/v1/workspaces/{id}/executions
- in: query
name: after_seq
required: false
schema:
type: integer
description: Return only events with seq greater than this — same number SSE carries as the frame id.
responses:
'200':
description: 'JSON mode: events newer than after_seq, oldest first.'
content:
application/json:
schema:
title: ExecutionEvents
type: object
properties:
data:
type: array
items:
title: ExecutionEvent
description: 'One run event: node-start | node-complete | done | error.'
type: object
properties:
seq:
description: Monotonic event address — resume cursor.
type: integer
at:
description: RFC 3339 timestamp.
oneOf:
- type: string
- type: 'null'
type:
description: node-start | node-complete | done | error.
oneOf:
- type: string
- type: 'null'
node_id:
description: The workflow node the event concerns.
outputs:
description: Node outputs on node-complete.
result:
description: Workflow result on done.
message:
description: Failure message on error.
oneOf:
- type: string
- type: 'null'
required:
- seq
- at
- type
additionalProperties: false
required:
- data
additionalProperties: false
'404':
description: Execution does not exist, or the caller has no visibility.
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
tags:
- Executions
summary: Stream or fetch the execution's events
description: 'The run''s seq-addressed event log (node-start / node-complete / done / error), in two encodings:
• `Accept: application/json` (default) — `{data: [...]}`; pass `?after_seq=N` to fetch only newer events.
• `Accept: text/event-stream` — SSE: replays, then live-tails. Frame `id` = event `seq`; reconnects resume via `Last-Event-ID`. A final `event: done` frame closes the stream at terminal status.
Events are a sliding window of the last 200 entries.
Authorization: any active member (viewer allowed); 404 opacity for non-members.'
operationId: getApiV1ExecutionsByIdEvents
x-operation-id-source: derived
/api/v1/workspaces/{id}/executions:
post:
parameters:
- in: path
name: id
required: true
schema:
type: string
format: uuid
description: Workflow workspace id from GET /api/v1/apps/{app_id}/workspaces?kind=workflow
requestBody:
content:
application/json:
schema:
title: ExecutionTrigger
description: Request body for POST /api/v1/workspaces/{id}/executions.
type: object
properties:
inputs:
description: Initial inputs handed to the workflow's start node. The run also receives a `session` map ($.session.org-id / $.session.profile-id) automatically.
type: object
additionalProperties: {}
additionalProperties: false
responses:
'202':
description: The running execution. Poll the Location header until a terminal status.
content:
application/json:
schema:
title: Execution
description: One workflow run — the uniform async-job shape. Poll until `status` turns terminal, or tail /events.
type: object
properties:
workspace_id:
description: The workflow workspace this run executed.
type: string
format: uuid
org_id:
description: Owning org id.
type: string
format: uuid
app_id:
description: Owning app id.
type: string
format: uuid
updated_at:
description: RFC 3339 timestamp.
oneOf:
- type: string
- type: 'null'
status:
description: running | succeeded | failed | cancelled.
type: string
result:
description: The workflow's result once status=succeeded. Null while running.
id:
description: Stable UUIDv7 identifier.
type: string
format: uuid
error:
description: Structured failure ({node_id, message}) once status=failed.
oneOf:
- type: object
additionalProperties: {}
- type: 'null'
seq:
description: Latest event's seq — resume /events with ?after_seq= from here.
type: integer
created_at:
description: RFC 3339 timestamp.
oneOf:
- type: string
- type: 'null'
required:
- id
- org_id
- app_id
- workspace_id
- status
- seq
- created_at
- updated_at
additionalProperties: false
'403':
description: Caller has visibility but lacks the role to run workflows.
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
'404':
description: Workspace does not exist, or the caller has no visibility.
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
'409':
description: The workspace is not a workflow, or the workflow has no executable nodes.
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
tags:
- Executions
summary: Run a workflow
description: 'Executes the workspace''s workflow against the app''s pre-deploy sandbox and answers 202 immediately with the running execution. Poll GET /api/v1/executions/{id} (the `Location` header) until `status` turns terminal, or tail GET /api/v1/executions/{id}/events.
`inputs` seeds the start node; the run also receives a `session` map ($.session.org-id / $.session.profile-id). Data nodes write to a per-app sandbox database — the same semantics as Studio''s Run button, isolated from platform data and from the deployed app.
Authorization: `[:write :resource]` (owner/admin/member); viewer is rejected with 403. 404 opacity for non-members.
Supports the `Idempotency-Key` header — a retried trigger replays the original 202 instead of starting a second run.'
operationId: postApiV1WorkspacesByIdExecutions
x-operation-id-source: derived
/api/v1/executions/{id}:
get:
parameters:
- in: path
name: id
required: true
schema:
type: string
format: uuid
description: Execution id from POST /api/v1/workspaces/{id}/executions
responses:
'200':
description: The execution row.
content:
application/json:
schema:
title: Execution
description: One workflow run — the uniform async-job shape. Poll until `status` turns terminal, or tail /events.
type: object
properties:
workspace_id:
description: The workflow workspace this run executed.
type: string
format: uuid
org_id:
description: Owning org id.
type: string
format: uuid
app_id:
description: Owning app id.
type: string
format: uuid
updated_at:
description: RFC 3339 timestamp.
oneOf:
- type: string
- type: 'null'
status:
description: running | succeeded | failed | cancelled.
type: string
result:
description: The workflow's result once status=succeeded. Null while running.
id:
description: Stable UUIDv7 identifier.
type: string
format: uuid
error:
description: Structured failure ({node_id, message}) once status=failed.
oneOf:
- type: object
additionalProperties: {}
- type: 'null'
seq:
description: Latest event's seq — resume /events with ?after_seq= from here.
type: integer
created_at:
description: RFC 3339 timestamp.
oneOf:
- type: string
- type: 'null'
required:
- id
- org_id
- app_id
- workspace_id
- status
- seq
- created_at
- updated_at
additionalProperties: false
'404':
description: Execution does not exist, or the caller has no visibility.
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
tags:
- Executions
summary: Get an execution
description: 'The run''s current state — uniform async-job shape. `result` is set once `status=succeeded`; `error` once `failed`. `seq` is the latest event''s address — resume /events with `?after_seq=` from here.
Authorization: any active member of the run''s org (read-only — viewer allowed). 404 opacity for non-members.'
operationId: getApiV1ExecutionsById
x-operation-id-source: derived
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: opaque
description: 'An Orbit api token, sent as `Authorization: Bearer <token>`.
Mint one with the RFC 8628 device-authorization grant (`POST /api/v1/device/code`, then poll `POST /api/v1/device/token`), or from Studio.
Every token carries a scope set from the `[verb resource]` RBAC catalog — `read:app`, `write:deployment`, `manage:secret`, and so on. The full vocabulary is published as `scopes_supported` at `/.well-known/oauth-protected-resource` (RFC 9728) and `/.well-known/oauth-authorization-server` (RFC 8414). Grant an agent the narrowest set that does its job.'
externalDocs:
description: Full documentation
url: https://docs.orbitapps.io
x-id:
- reitit.openapi/default