AxonFlow Unified Executions API

openapi: 3.2.0
info:
  title: Axonflow Unified Executions API
  version: 11.1.0
  contact:
    name: AxonFlow Support
    url: https://getaxonflow.com/support
  license:
    name: Business Source License 1.1
    url: https://github.com/getaxonflow/axonflow/blob/main/LICENSE
  description: 'Operations tagged Unified Executions across 2 of this provider''s published API definitions: axonflow-orchestrator-api.yaml, axonflow-orchestrator-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://orchestrator.getaxonflow.com
  description: Production (SaaS)
- url: http://localhost:8081
  description: Local Development
tags:
- name: Unified Executions
  description: 'Unified execution tracking and real-time streaming for MAP plans and WCP workflows.

    SSE streaming provides real-time status updates. Community: 5 concurrent connections

    per tenant. Enterprise: Unlimited.'
paths:
  /api/v1/unified/executions:
    get:
      tags:
      - Unified Executions
      summary: List executions (MAP plans + WCP workflows)
      description: 'Lists unified executions across both MAP plans and WCP workflows,

        scoped to the tenant/org identified by the `X-Tenant-ID` and

        `X-Org-ID` headers. The page size is capped by the license tier''s

        execution-history limit (at most 100 per page); out-of-range `limit`

        or `offset` values are silently ignored and the defaults used.'
      operationId: listUnifiedExecutions
      parameters:
      - $ref: '#/components/parameters/TenantIDHeader'
      - name: X-Org-ID
        in: header
        required: true
        description: Organization identifier for scoping results
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Page size (default 20, max 100 or the tier history cap, whichever is lower)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: offset
        in: query
        required: false
        description: Number of records to skip
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: execution_type
        in: query
        required: false
        description: Filter by execution type
        schema:
          type: string
          enum:
          - map_plan
          - wcp_workflow
      - name: status
        in: query
        required: false
        description: Filter by execution status
        schema:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          - cancelled
          - aborted
          - expired
      responses:
        '200':
          description: Execution list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedExecutionListResponse'
        '401':
          description: '`UNAUTHORIZED`: the request carried neither a tenant nor an org

            key (#3367). Before v10.0.0 this shape fell through to an

            unscoped `FROM execution_history WHERE 1=1` read of every

            organisation''s executions and answered `200`. It is now refused

            with `Tenant or org identity required`, which is the same status

            the by-id half of this handler already returned for the same

            input. The handler and the execution repository refuse the shape

            independently, so a future caller reaching the repository by

            another route cannot reinstate the unscoped read.

            '
        '500':
          description: "The listing could not be served. Beyond an ordinary query\nfailure, one arm of this status is a deliberate refusal of the\norg-wide read (#3367), reachable only on the org-wide branch\nthat the trusted-hop `X-Axonflow-Tenancy-Scope` header selects:\n\n- **No BYPASSRLS admin pool.** A portal org-wide list on a\n  deployment running `axonflow_app_role` (the default since\n  v9.0.0) with no admin pool installed would be filtered to zero\n  rows by the tenant-keyed RLS predicate on `execution_history`,\n  and a `200` carrying a well-formed empty list is exactly the\n  confident-empty page this refusal exists to remove. **The\n  remedy is to set `AXONFLOW_DB_PLATFORM_ADMIN_URL`.** In\n  practice this arm is defence in depth rather than a shape a\n  running deployment reaches: the orchestrator carries a fatal\n  boot guard on exactly that combination, so a deployment with\n  the app-role posture enabled and this variable unset refuses\n  to boot rather than serving the route at all. The refusal\n  below the guard exists so that relaxing the guard could never\n  silently restore the confident-empty page.\n\n- **A sentinel org key.** The org-wide branch requires a\n  non-empty stamped `X-Org-ID`, but the handler does not check\n  it against the unowned-org sentinel, so a trusted-hop\n  request stamped with the sentinel value reaches the\n  repository's org-key validation and its refusal surfaces as\n  this 500. A real organisation id never takes this arm.\n\nThe execution repository carries two further org-wide refusals\n(an org key with leading or trailing whitespace, and an\norg-wide read that also carries a tenant narrowing), but\nneither is reachable through this endpoint: the handler trims\nthe org key once and clears the tenant narrowing before\nselecting the org-wide branch, so a padded `X-Org-ID` is\nserved after trimming, not refused. The EMPTY half of the\nrepository's org-key validation is also prevented by\nconstruction, because the org-wide branch requires a non-empty\nkey; the SENTINEL half is not, which is why it appears in the\ncause list above. The unreachable refusals stay in the\nrepository as defense in depth against a future caller that\nskips the handler's normalization; today this endpoint's\nhandler is the repository listing's only caller.\n"
    servers:
    - url: https://orchestrator.getaxonflow.com
      description: Production (SaaS)
    - url: http://localhost:8081
      description: Local Development
  /api/v1/unified/executions/{id}:
    get:
      tags:
      - Unified Executions
      summary: Get unified execution status
      description: 'Returns the unified status record for a MAP plan or WCP workflow

        execution. The id is resolved across both subsystems (direct

        execution id, `plan_...` plan ids, `wf_`/`wcp_` workflow ids).

        Requires both `X-Tenant-ID` and `X-Org-ID`; a tenant/org mismatch

        returns 404 (not 403) to avoid a cross-tenant existence oracle.'
      operationId: getUnifiedExecutionStatus
      parameters:
      - name: id
        in: path
        required: true
        description: Execution id (or plan_/wf_/wcp_ prefixed subsystem id)
        schema:
          type: string
      - $ref: '#/components/parameters/TenantIDHeader'
      - name: X-Org-ID
        in: header
        required: true
        description: Organization identifier for scoping results
        schema:
          type: string
      responses:
        '200':
          description: Unified execution status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedExecutionStatus'
        '400':
          description: Missing execution id
        '401':
          description: Missing tenant or org identity headers
        '404':
          description: Execution not found (or belongs to another tenant/org)
        '500':
          description: Failed to resolve execution
    servers:
    - url: https://orchestrator.getaxonflow.com
      description: Production (SaaS)
    - url: http://localhost:8081
      description: Local Development
  /api/v1/unified/executions/{id}/cancel:
    post:
      tags:
      - Unified Executions
      summary: Cancel a unified execution
      description: 'Cancels a running MAP plan or WCP workflow through the unified API.

        The cancellation propagates to the owning subsystem (plan cancel or

        workflow abort). Cancelling an execution already in a terminal state

        returns 409.'
      operationId: cancelUnifiedExecution
      parameters:
      - name: id
        in: path
        required: true
        description: Execution id (or plan_/wf_/wcp_ prefixed subsystem id)
        schema:
          type: string
      - $ref: '#/components/parameters/TenantIDHeader'
      - name: X-Org-ID
        in: header
        required: true
        description: Organization identifier for scoping results
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Cancellation reason (defaults to "cancelled via unified API")
      responses:
        '200':
          description: 'Execution cancelled; returns the refreshed unified status record

            (or a `{execution_id, status: "cancelled", message}` fallback if

            the post-cancel re-read fails).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedExecutionStatus'
        '400':
          description: Missing execution id or unknown execution type
        '401':
          description: Missing tenant or org identity headers
        '404':
          description: Execution not found (or belongs to another tenant/org)
        '409':
          description: Execution is already in a terminal state
        '500':
          description: Cancellation failed
    servers:
    - url: https://orchestrator.getaxonflow.com
      description: Production (SaaS)
    - url: http://localhost:8081
      description: Local Development
  /api/v1/unified/executions/{id}/stream:
    get:
      tags:
      - Unified Executions
      summary: Stream execution status via SSE
      description: 'Server-Sent Events stream for real-time execution status updates.

        Streams events for both MAP plan executions and WCP workflow executions.

        Community: Limited to 5 concurrent connections per tenant.

        Enterprise: Unlimited concurrent connections.'
      operationId: streamExecutionStatus
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: X-Tenant-ID
        in: header
        required: true
        schema:
          type: string
      - name: X-Org-ID
        in: header
        required: true
        description: 'Organization identifier. Like X-Tenant-ID, required by the

          unified-execution tenant-ownership check; missing either header

          is a 401.

          '
        schema:
          type: string
      responses:
        '200':
          description: SSE stream of execution events
          content:
            text/event-stream:
              schema:
                type: string
        '429':
          description: Too many concurrent connections (Community edition limit)
    servers:
    - url: https://orchestrator.getaxonflow.com
      description: Production (SaaS)
    - url: http://localhost:8081
      description: Local Development
components:
  parameters:
    TenantIDHeader:
      name: X-Tenant-ID
      in: header
      required: true
      description: 'Tenant identifier scoping the request. The AxonFlow Agent gateway

        sets this header after authentication; the orchestrator fails closed

        when it is absent (401 on audit/decision endpoints, 400 on others —

        see each operation). Clients cannot widen their scope through it:

        handlers force the tenant filter from this header, never from the

        request body.

        '
      schema:
        type: string
      example: travel-us
  schemas:
    UnifiedStepStatus:
      type: object
      properties:
        step_id:
          type: string
        step_index:
          type: integer
        step_name:
          type: string
        step_type:
          type: string
          enum:
          - llm_call
          - tool_call
          - connector_call
          - human_task
          - synthesis
          - action
          - gate
        status:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          - skipped
          - blocked
          - approval
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        duration:
          type: string
        decision:
          type: string
          enum:
          - allow
          - block
          - require_approval
        decision_reason:
          type: string
        policies_matched:
          type: array
          items:
            type: string
        approval_status:
          type: string
          enum:
          - pending
          - approved
          - rejected
          - expired
        approved_by:
          type: string
        approved_at:
          type: string
          format: date-time
        rejected_by:
          type: string
        rejected_at:
          type: string
          format: date-time
        model:
          type: string
        provider:
          type: string
        cost_usd:
          type: number
          format: double
        tokens_in:
          type: integer
        tokens_out:
          type: integer
        input:
          description: Raw step input (JSON)
        output:
          description: Raw step output (JSON)
        result_summary:
          type: string
        error:
          type: string
    UnifiedExecutionStatus:
      type: object
      description: 'Unified status record covering both MAP plans and WCP workflows.

        Distinct from the replay Execution schema and from the MAP

        StepStatus schema.

        '
      properties:
        execution_id:
          type: string
        execution_type:
          type: string
          enum:
          - map_plan
          - wcp_workflow
        name:
          type: string
        source:
          type: string
        status:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          - cancelled
          - aborted
          - expired
        current_step_index:
          type: integer
        total_steps:
          type: integer
        progress_percent:
          type: number
          format: double
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        duration:
          type: string
        estimated_cost_usd:
          type: number
          format: double
        actual_cost_usd:
          type: number
          format: double
        steps:
          type: array
          items:
            $ref: '#/components/schemas/UnifiedStepStatus'
        error:
          type: string
        tenant_id:
          type: string
        org_id:
          type: string
        user_id:
          type: string
        client_id:
          type: string
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    UnifiedExecutionListResponse:
      type: object
      properties:
        executions:
          type: array
          items:
            $ref: '#/components/schemas/UnifiedExecutionStatus'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        has_more:
          type: boolean
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: OAuth2-style client credentials (clientId:clientSecret)
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enterprise JWT token (see /scripts/generate-jwt.sh)
x-refined-from:
- axonflow-orchestrator-api.yaml
- axonflow-orchestrator-openapi.yml