openapi: 3.1.0
info:
  title: AlphaAgent Studio - Programmatic Workflow API
  version: '2026-09-24'
  description: 'Run workflows in a governed AlphaAgent Studio deployment from your
    own systems.


    Base URL: `https://<app_domain>/api/v1`. Every call (except `/health`) carries
    `Authorization: Bearer ak_<key_id>.<secret>` and `X-AlphaAgent-Key-External-Id`,
    both issued once by your Organisations administrator. Keys are bound to one deployment,
    carry scopes (`workflows:read`, `runs:create`, `runs:read`, `outputs:read`, `runs:delete`),
    an allow-list of workflows, an optional source-CIDR list, an optional UTC time
    window, an expiry, a requests-per-minute limit, a daily run quota and a concurrent-run
    bound.


    Every error is `{error: {code, message, request_id}}`. Request bodies are capped
    at 1 MiB (413 `payload_too_large`). Poll `GET /runs/{run_id}` no more than every
    5 s and honour `Retry-After` on every 429/503. Run inputs are declared per workflow
    version (`parameters`); `s3_prefix` parameters point at objects in YOUR bucket
    that the workflow''s `aws` connector may read. Approvals stay with humans in Studio''s
    Inbox; the API reads them, it never grants them.'
servers:
- url: https://{app_domain}/api/v1
  variables:
    app_domain:
      default: studio.example.com
paths:
  /health:
    get:
      tags:
      - public-api
      summary: Liveness of the programmatic API (unauthenticated)
      description: 'The only unauthenticated path: ``{status, deployment_id, api_version}``

        and nothing else. ``status`` is ``ok`` when the API accepts keys here,

        ``disabled`` otherwise (not governed, or PROGRAMMATIC_API_ENABLED false).

        The flag is the LIVE common-config value (re-read at most every 60 s,

        F-OA-K2), so a bank''s start-up self-check sees the Org''s flip without

        waiting for this service to roll.'
      operationId: health_api_v1_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Health Api V1 Health Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      parameters:
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
  /me:
    get:
      tags:
      - public-api
      summary: The calling key and its limits
      operationId: me_api_v1_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Me Api V1 Me Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
      parameters:
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
  /runs:
    get:
      tags:
      - public-api
      summary: This key's runs, newest first
      description: '``items[]`` of ``RunSummary``: run_id, workflow_id, workflow_name,
        version, status, created_at, started_at, finished_at, duration_ms, client_reference,
        labels, counts, ``warnings`` (strings; optional stages that did not land while
        the run still completed, e.g. a knowledge-graph publish that was still building
        when its wait expired) and ``completed_with_warnings`` (true only when status
        is ``completed`` and ``warnings`` is non-empty), links. ``next_cursor`` pages.'
      operationId: list_runs_api_v1_runs_get
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          description: Comma-separated public statuses
          title: Status
        description: Comma-separated public statuses
      - name: workflow_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Workflow Id
      - name: created_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Created After
      - name: created_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Created Before
      - name: client_reference
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Client Reference
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Runs Api V1 Runs Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /runs/{run_id}:
    get:
      tags:
      - public-api
      summary: One run in full
      description: '``RunDetail`` = the ``RunSummary`` fields (incl. ``warnings[]``
        and ``completed_with_warnings``) plus parameters, input_text, inputs_manifest,
        error {code, message} when failed, max_run_hours, triggered_by, key_id, summary_markdown,
        result / result_error / result_schema_version / result_json, data_purged_at,
        pii_redaction, pii_policy. A run whose status is ``completed`` with a non-empty
        ``warnings`` list finished; its outputs are available and ``completed_with_warnings``
        is true.'
      operationId: get_run_api_v1_runs__run_id__get
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Run Id
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Run Api V1 Runs  Run Id  Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /runs/{run_id}/approvals:
    get:
      tags:
      - public-api
      summary: Nodes parked on a human gate (read-only)
      operationId: get_run_approvals_api_v1_runs__run_id__approvals_get
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Run Id
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Run Approvals Api V1 Runs  Run Id  Approvals Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /runs/{run_id}/cancel:
    post:
      tags:
      - public-api
      summary: Cancel a run
      operationId: cancel_run_api_v1_runs__run_id__cancel_post
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Run Id
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelRunRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /runs/{run_id}/data:
    delete:
      tags:
      - public-api
      summary: Erase a finished run's objects (right to erasure)
      operationId: purge_run_data_api_v1_runs__run_id__data_delete
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Run Id
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurgeRunDataRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /runs/{run_id}/events:
    get:
      tags:
      - public-api
      summary: Durable event replay for a run segment
      description: 'Events are per runtime SEGMENT (``runtime_run_ids``; an approval
        starts a

        new one) with a per-segment ``seq``. Poll with ``after_seq=next_after_seq``

        on the same ``segment``; when ``segments`` grows, start the new one at 0.'
      operationId: get_run_events_api_v1_runs__run_id__events_get
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Run Id
      - name: after_seq
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: After Seq
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 200
          title: Limit
      - name: segment
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          description: 'Runtime segment id (default: the latest)'
          title: Segment
        description: 'Runtime segment id (default: the latest)'
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Run Events Api V1 Runs  Run Id  Events Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /runs/{run_id}/outputs:
    get:
      tags:
      - public-api
      summary: Promoted outputs of a finished run
      operationId: list_run_outputs_api_v1_runs__run_id__outputs_get
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Run Id
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Run Outputs Api V1 Runs  Run Id  Outputs Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /runs/{run_id}/outputs.zip:
    get:
      tags:
      - public-api
      summary: All outputs as one zip (<= 500 MB / 2,000 files); an empty zip when
        the run produced no files
      operationId: get_run_outputs_zip_api_v1_runs__run_id__outputs_zip_get
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Run Id
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /runs/{run_id}/outputs/{output_id}/content:
    get:
      tags:
      - public-api
      summary: One output's bytes (<= 25 MB)
      operationId: get_run_output_content_api_v1_runs__run_id__outputs__output_id__content_get
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Run Id
      - name: output_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 2048
          title: Output Id
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /runs/{run_id}/pii-redaction:
    get:
      tags:
      - public-api
      summary: The run's PII redaction manifest (counts only, never a value)
      description: 'WS-N (§3.4): ``inputs/PII_REDACTION.json`` - mode, model, stages,

        categories and counts. 404 ``pii_redaction_not_applied`` when the run''s

        policy was off (no manifest exists).'
      operationId: get_run_pii_redaction_api_v1_runs__run_id__pii_redaction_get
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Run Id
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Run Pii Redaction Api V1 Runs  Run Id  Pii Redaction
                  Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /runs/{run_id}/steps:
    get:
      tags:
      - public-api
      summary: Per-node state from the run's board
      operationId: get_run_steps_api_v1_runs__run_id__steps_get
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Run Id
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Run Steps Api V1 Runs  Run Id  Steps Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /workflows:
    get:
      tags:
      - public-api
      summary: Workflows this key may run (active only)
      operationId: list_workflows_api_v1_workflows_get
      parameters:
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          description: Prefix match on the name (case-insensitive)
          title: Q
        description: Prefix match on the name (case-insensitive)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Workflows Api V1 Workflows Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /workflows/{workflow_id}:
    get:
      tags:
      - public-api
      summary: 'One workflow: versions, parameters, nodes, readiness'
      operationId: get_workflow_api_v1_workflows__workflow_id__get
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Workflow Id
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Workflow Api V1 Workflows  Workflow Id  Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /workflows/{workflow_id}/parameters:
    get:
      tags:
      - public-api
      summary: The input contract of a version
      operationId: get_workflow_parameters_api_v1_workflows__workflow_id__parameters_get
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Workflow Id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          title: Version
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Workflow Parameters Api V1 Workflows  Workflow
                  Id  Parameters Get
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
  /workflows/{workflow_id}/runs:
    post:
      tags:
      - public-api
      summary: Start a run
      description: '202 ``RunSummary`` for a new run; 200 + the SAME run when the

        ``Idempotency-Key`` replays an identical request (24 h window). The

        orchestrator launches inline, so the body reflects the post-launch row

        (``running``, or ``failed`` with ``error`` when the runtime refused).'
      operationId: create_run_api_v1_workflows__workflow_id__runs_post
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Workflow Id
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Optional correlation id; echoed on the response (one is minted
          when absent)
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          maxLength: 128
        description: Required. Same key + same body within 24 h replays the same run
          (200); a different body is 409 idempotency_conflict
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRunRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: invalid_request / invalid_parameters / invalid_filter / invalid_cursor
            / policy_not_tightening / invalid_pii_policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: unauthorized (key or external id missing / wrong / revoked
            / expired / wrong deployment)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: forbidden (source IP, scope) / outside_time_window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: workflow_not_found / run_not_found / output_not_found / segment_not_found
            / pii_redaction_not_applied / not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: idempotency_conflict / workflow_not_active / workflow_not_ready
            / run_not_terminal / redaction_pending / already_terminal / already_purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: payload_too_large (request body over 1 MiB) / use_bundle /
            bundle_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '416':
          description: range_not_satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: version_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: rate_limited / quota_exceeded / too_many_active_runs (honour
            Retry-After)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '451':
          description: license_unavailable (the deployment's licence is on hold; details
            {state, reason, enforcement_status, license_id})
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: internal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: runtime_error / runtime_unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: deployment_updating (not governed, not enabled, keys table
            unreachable, or the service is rolling)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - ApiKey: []
        KeyExternalId: []
components:
  schemas:
    CancelRunRequest:
      properties:
        reason:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Reason
      type: object
      title: CancelRunRequest
    CreateRunRequest:
      properties:
        input_text:
          anyOf:
          - type: string
            maxLength: 20000
          - type: 'null'
          title: Input Text
          description: Free-text goal for the run
        parameters:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Parameters
          description: Values for the version's declared parameters
        version:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Version
          description: 'Workflow version to run (default: the active version)'
        client_reference:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Reference
          description: Opaque identifier, <= 256 printable ASCII chars, never PII;
            echoed
        labels:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Labels
          description: <= 10 opaque key/value labels; never PII
        pii_policy_override:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pii Policy Override
          description: 'WS-N: a PII policy that may only TIGHTEN the workflow''s (400
            policy_not_tightening otherwise)'
      type: object
      title: CreateRunRequest
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - request_id
          properties:
            code:
              type: string
              description: Stable machine-readable code (see the failure table)
            message:
              type: string
            request_id:
              type: string
              nullable: true
              description: Echoed X-Request-Id; quote it to support
            details:
              description: Optional structured detail, e.g. invalid_parameters ->
                [{name, reason}]
    PurgeRunDataRequest:
      properties:
        reason:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Reason
      type: object
      title: PurgeRunDataRequest
  securitySchemes:
    ApiKey:
      type: http
      description: '`Authorization: Bearer ak_<key_id>.<secret>` - the key shown once
        at creation'
      scheme: bearer
    KeyExternalId:
      type: apiKey
      description: The key's external id (`ake_…`), shown once beside the key; mandatory
        on every call
      in: header
      name: X-AlphaAgent-Key-External-Id
security:
- ApiKey: []
  KeyExternalId: []
x-error-codes:
- http: '400'
  codes: invalid_request / invalid_parameters / invalid_filter / invalid_cursor /
    policy_not_tightening / invalid_pii_policy
- http: '401'
  codes: unauthorized (key or external id missing / wrong / revoked / expired / wrong
    deployment)
- http: '403'
  codes: forbidden (source IP, scope) / outside_time_window
- http: '404'
  codes: workflow_not_found / run_not_found / output_not_found / segment_not_found
    / pii_redaction_not_applied / not_found
- http: '409'
  codes: idempotency_conflict / workflow_not_active / workflow_not_ready / run_not_terminal
    / redaction_pending / already_terminal / already_purged
- http: '413'
  codes: payload_too_large (request body over 1 MiB) / use_bundle / bundle_too_large
- http: '416'
  codes: range_not_satisfiable
- http: '422'
  codes: version_not_found
- http: '429'
  codes: rate_limited / quota_exceeded / too_many_active_runs (honour Retry-After)
- http: '451'
  codes: license_unavailable (the deployment's licence is on hold; details {state,
    reason, enforcement_status, license_id})
- http: '500'
  codes: internal
- http: '502'
  codes: runtime_error / runtime_unreachable
- http: '503'
  codes: deployment_updating (not governed, not enabled, keys table unreachable, or
    the service is rolling)