Orbit Executions API

Workflow runs — trigger pre-deploy executions and observe them as async jobs

GitHub OpenAPI

Operations 4

POST /api/v1/executions/{id}/cancel Cancel a running execution #
GET /api/v1/executions/{id}/events Stream or fetch the execution's events #
POST /api/v1/workspaces/{id}/executions Run a workflow #
GET /api/v1/executions/{id} Get an execution #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/orbitapps-io:orbitapps-io-executions-api"
All apis
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.

Get an API 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 Specification

orbitapps-io-executions-api-openapi.yml Raw ↑
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