openapi: 3.0.3
info:
  title: StackGen External API
  version: 0.1.0
  description: Allowlisted StackGen API surface for the public SDK. Managed via api-docs/product/allowlists/external.yaml.
servers:
- url: https://app.stackgen.com
  description: StackGen cloud (override per environment)
tags:
- name: Aiden
  description: Platform automations, sessions, artifacts
- name: SRE
  description: Alerts and investigations
- name: Vault
  description: Secrets
paths:
  /app/sre/api/v1/alerts:
    get:
      summary: List or count alerts with filters and summary totals
      description: 'Returns a paginated alert inventory plus summary totals. Use this
        operation for "list alerts", "count alerts", firing-alert inventory, queue
        filtering, and alert searches. Read the response summary for counts instead
        of counting the current page. The summary is always for status=active; use
        `status` to switch the returned list between the Active tab (default) and
        Ignored tab. When listing titles and the tool result is truncated or compressed,
        read visible `id` values and call GET /api/v1/alerts/{id} (getAlertV1) per
        alert — do not invent titles.

        '
      operationId: listAlerts
      parameters:
      - name: status
        in: query
        required: false
        description: Filter by alert lifecycle status. Defaults to "active".
        schema:
          $ref: '#/components/schemas/AlertStatus'
          default: active
      - name: attention
        in: query
        required: false
        description: Optional filter by triage attention category.
        schema:
          $ref: '#/components/schemas/AlertAttention'
      - name: source_type
        in: query
        required: false
        description: Optional filter by alert source (e.g. "grafana").
        schema:
          type: string
      - name: integration_names
        in: query
        required: false
        description: 'Optional filter by one or more integration instance names (e.g.
          prod-grafana, sandbox-prometheus). Summary counts and the alert list are
          scoped to these integrations when provided.

          '
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            minLength: 1
      - name: storm_id
        in: query
        required: false
        description: 'Optional filter by correlated incident storm UUID. Returns all
          active alerts in the same ingest storm (for linked-alert navigation).

          '
        schema:
          type: string
          format: uuid
      - name: q
        in: query
        required: false
        description: Optional case-insensitive search across alert titles and descriptions.
        schema:
          type: string
      - name: signal_severity
        in: query
        required: false
        description: 'Optional filter by normalized monitor signal severity (Critical,
          High, Medium, Low, info). Matches raw upstream source_severity values in
          each bucket before pagination.

          '
        schema:
          $ref: '#/components/schemas/SignalSeverity'
      - name: alert_role
        in: query
        required: false
        description: 'Optional filter by correlated alert role (root signal vs downstream
          effect).

          '
        schema:
          $ref: '#/components/schemas/AlertRole'
      - name: sort_by
        in: query
        required: false
        description: 'List ordering. `severity` (default) ranks by monitor display_priority.
          `impact` ranks by persisted blast-radius impact (env, scope, storm fanout)
          before severity as a tie-break.

          '
        schema:
          $ref: '#/components/schemas/AlertSortBy'
          default: severity
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 500
      responses:
        '200':
          description: Paginated alerts and summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAlertsResponse'
      x-stackgen-namespace: sre
      tags:
      - SRE
  /app/sre/api/v1/alerts/{id}:
    get:
      summary: Get a single alert by id (alert detail / per-alert read)
      description: 'Returns one alert by internal UUID or by source external_uid (e.g.
        Grafana fingerprint). Use this for alert detail, per-alert reads, and recovering
        a full title when a list payload is truncated or compressed. Use external_uid
        for shareable deep links; pagination is not required.

        '
      operationId: getAlertV1
      parameters:
      - name: id
        in: path
        required: true
        description: Internal alert UUID or stable source external_uid.
        schema:
          type: string
      responses:
        '200':
          description: Alert details including linked investigation summary when present
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertV1'
        '404':
          description: Alert not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-stackgen-namespace: sre
      tags:
      - SRE
  /app/sre/api/v1/alerts/{id}/investigate:
    post:
      summary: Start or retrieve a deep-dive investigation
      description: 'If no investigation exists for this alert, creates an investigations
        row and launches a Aiden workflow. If one already exists (any status), returns
        it unchanged.

        '
      operationId: investigateAlert
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvestigateAlertRequest'
      responses:
        '200':
          description: Investigation started or existing investigation returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvestigateResponse'
        '404':
          description: Alert not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-stackgen-namespace: sre
      tags:
      - SRE
  /app/sre/api/v1/investigations:
    get:
      summary: List or count investigations by status for the caller
      description: Returns a paginated investigation inventory ordered by start time
        (most recent first) and scoped to the caller's tenant/owner. Use this operation
        for "list investigations", "count investigations", queued or completed investigation
        questions, and status re-checks. Read `total` for the full filtered count
        instead of counting the current page. Optional `status` narrows the result
        to one lifecycle bucket.
      operationId: listInvestigations
      parameters:
      - name: status
        in: query
        required: false
        description: Optional status filter.
        schema:
          $ref: '#/components/schemas/InvestigationStatus'
      - name: alert_id
        in: query
        required: false
        description: Filter to investigations for a single alert (UUID).
        schema:
          type: string
          format: uuid
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 200
      responses:
        '200':
          description: Paginated investigation list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInvestigationsResponse'
      x-stackgen-namespace: sre
      tags:
      - SRE
  /app/sre/api/v1/investigations/{id}:
    get:
      summary: Get investigation details, evidence, and RCA by ID
      description: 'Returns the complete caller-scoped investigation identified by
        its UUID, including lifecycle state, result summary, evidence, and RCA fields
        when available. Use this operation for investigation details or status when
        the investigation ID is already known; use listInvestigations first when the
        ID is unknown.

        '
      operationId: getInvestigation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Investigation found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Investigation'
        '404':
          description: Investigation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-stackgen-namespace: sre
      tags:
      - SRE
  /guild/api/v1/sessions:
    get:
      summary: List conversation sessions
      description: |
        Returns a paginated list of conversation sessions. Each item includes the
        first user prompt, who started the session, when it was active, total cost,
        and what responded (agent, workflow, or installed app).

        Optional `q` searches title, prompt, initiator, responder names, session id,
        and source metadata. Use this to look up runs by correlation or incident id
        stored in `source_metadata`.
      operationId: listSessions
      parameters:
      - name: q
        in: query
        required: false
        description: Full-text search across session fields and source metadata.
        schema:
          type: string
      - name: source_app
        in: query
        required: false
        description: Filter by initiating application name.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of items to return.
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
      - name: offset
        in: query
        required: false
        description: Number of items to skip.
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: orgId
        in: query
        required: false
        description: Organization / project UUID (orgId query parameter).
        schema:
          type: string
      responses:
        '200':
          description: Session list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionListResponse'
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/sessions/{session_id}:
    get:
      description: 'Retrieves profound details about a specific session, including
        dynamic computations, cost aggregations, and AI-generated summaries.

        '
      operationId: getSessionByID
      parameters:
      - description: Session ID (e.g. session-{tenant}-{agent}-{channel}).
        in: path
        name: session_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
          description: Detailed session object
        '404':
          description: Session not found
        '500':
          description: Unexpected error
      summary: Get session by ID
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/sessions/{session_id}/artifacts:
    get:
      operationId: listSessionArtifacts
      parameters:
      - description: Session ID (e.g. session-{tenant}-{agent}-{channel}).
        explode: false
        in: path
        name: session_id
        required: true
        schema:
          type: string
        style: simple
      - description: The organization ID to scope the request to. If not provided,
          the personal namespace is assumed.
        explode: true
        in: query
        name: orgId
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ArtifactInfo'
                type: array
          description: List of artifacts
        default:
          description: Unexpected error
      summary: List artifacts for a session
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/sessions/{session_id}/artifacts/{artifact_id}/download:
    get:
      operationId: downloadSessionArtifact
      parameters:
      - description: Session ID
        explode: false
        in: path
        name: session_id
        required: true
        schema:
          type: string
        style: simple
      - description: Artifact UUID or filename (case-insensitive)
        explode: false
        in: path
        name: artifact_id
        required: true
        schema:
          type: string
        style: simple
      - description: The organization ID to scope the request to. If not provided,
          the personal namespace is assumed.
        explode: true
        in: query
        name: orgId
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: File contents
        '404':
          description: Artifact not found
        default:
          description: Unexpected error
      summary: Download an artifact by ID or filename
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/sessions/{session_id}/export:
    get:
      summary: Export a session as a composable bundle of parts
      description: |
        Returns selected parts of a session as a single JSON manifest. Use this when
        you need the write-up and do not have a downloaded artifact file yet.

        Supported part kinds: `notes`, `report` (chat-friendly equivalent of a
        workflow `session-report.md`), and `evidence`. Omitting `parts` returns all
        three. Unknown part kinds are ignored.
      operationId: exportSession
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
        description: Session ID to export.
      - name: parts
        in: query
        required: false
        schema:
          type: string
        description: >
          Comma-separated part kinds (e.g. `report` or `notes,report,evidence`).
          Omit for the default set.
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum: [json]
          default: json
        description: Response format. `json` returns a manifest with each part inline.
      - name: orgId
        in: query
        required: false
        schema:
          type: string
        description: Organization / project UUID (orgId query parameter).
      responses:
        '200':
          description: Session export manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionExport'
        '400':
          description: Unsupported export format requested.
        '404':
          description: Session not found or not owned by caller.
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/sessions/{session_id}/terminate:
    post:
      summary: Terminate a session by cancelling active runs
      description: |
        Cancels running work for this session. Idempotent: a session with nothing
        running returns 200 with `cancelled_workflows: 0`. Returns 503 if a running
        execution could not be cancelled.
      operationId: terminateSession
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
        description: Session ID whose active runs should be terminated.
      - name: orgId
        in: query
        required: false
        schema:
          type: string
        description: Organization / project UUID (orgId query parameter).
      - name: reason
        in: query
        required: false
        schema:
          type: string
        description: Optional human-readable reason for termination.
      responses:
        '200':
          description: Termination request processed (may be a no-op if nothing was running).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminateSessionResponse'
        '404':
          description: Session not found or not owned by caller.
        '503':
          description: At least one running execution could not be cancelled.
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/webhooks/trigger:
    post:
      description: 'Public endpoint authenticated by a webhook token.

        Provide the token via the `apiKey` query parameter or the

        Authorization header (`Bearer <token>`).

        This endpoint is NOT behind session authentication.


        The 202 body includes webhook_id, invocation_id, and target

        identity. Newer motherships may also return session_id and trace_id on the

        202 body. When those fields are absent, poll GET

        /api/v1/webhooks/{webhook_id}/runs/{invocation_id} until they are populated.

        '
      operationId: triggerWebhook
      parameters:
      - description: The organization ID to scope the request to. If not provided,
          the personal namespace is assumed.
        in: query
        name: orgId
        required: false
        schema:
          type: string
      - description: Webhook token. Use this when the sender cannot set custom HTTP
          headers.
        in: query
        name: apiKey
        schema:
          type: string
      requestBody:
        content:
          text/plain:
            schema:
              type: string
        required: false
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerWebhook202Response'
          description: Webhook triggered successfully.
        '401':
          description: Invalid or missing webhook token.
        '404':
          description: Webhook not found or disabled.
        '423':
          content:
            application/json:
              example:
                msg: target not ready for scheduling
                errCode: WORKFLOW_HAS_UNBOUND_STAGE
                extras:
                - target_type: workflow
                  target_name: incident-response
                  unbound_stage_id: triage
                  total_stages: 3
                  resolution_hint: set stage_bindings[*].agent_ref, parallel_agents,
                    or action_type
              schema:
                $ref: '#/components/schemas/JsonError'
          description: "The schedule or webhook target (agent or workflow) is not\
            \ safe to\ninvoke unattended. Returned at create / update time with HTTP\
            \ 400 so\noperators discover misconfiguration before any cron tick or\n\
            webhook delivery, and re-checked at trigger time with HTTP 423 to\nshort-circuit\
            \ dispatch when a previously-ready target became\nunready after creation\
            \ (e.g. an operator removed the agent's\nlast integration). Body is **JsonError**\
            \ with one of the\nstable `errCode` values below; the `extras` object\
            \ carries the\nmachine-actionable context the UI uses to highlight the\n\
            offending stage or surface a remediation hint.\n\n`errCode` values:\n\n\
            * `TARGET_NOT_FOUND` — the agent or workflow named in the\n  request does\
            \ not exist. (Schedules also surface this as 404\n  via their dedicated\
            \ ownership check; webhooks newly enforce\n  it here.)\n* `NO_INTEGRATIONS`\
            \ — the agent target exists but has zero\n  integrations attached. Scheduling\
            \ or webhook-triggering it\n  would produce empty unattended runs.\n*\
            \ `WORKFLOW_HAS_NO_STAGES` — the workflow target has an empty\n  stage\
            \ list.\n* `WORKFLOW_HAS_UNBOUND_STAGE` — at least one stage has neither\n\
            \  a pre-attached `agent_ref`, a non-empty `parallel_agents`\n  list,\
            \ nor an `action_type`. `extras.unbound_stage_id` names\n  the offending\
            \ stage so the UI can deep-link to it.\n"
        default:
          description: Unexpected error
      summary: Trigger a webhook to start a session
      tags:
      - Aiden
      x-rbac-exempt: true
      x-stackgen-namespace: aiden
      security:
      - WebhookToken: []
  /guild/api/v1/webhooks/{webhook_id}/runs:
    get:
      description: 'Returns a paginated history of incoming named webhook invocations,

        ordered newest-first. Payload bodies are not included in this list

        response; use the run detail endpoint for the stored payload.

        '
      operationId: listWebhookRuns
      parameters:
      - explode: false
        in: path
        name: webhook_id
        required: true
        schema:
          format: uuid
          type: string
        style: simple
      - description: Maximum number of items to return.
        explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 10
          maximum: 100
          minimum: 1
          type: integer
        style: form
      - description: Number of items to skip.
        explode: true
        in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          type: integer
        style: form
      - description: The organization ID to scope the request to. If not provided,
          the personal namespace is assumed.
        explode: true
        in: query
        name: orgId
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRunListResponse'
          description: Paginated webhook invocation history.
        '404':
          description: Webhook not found
        default:
          description: Unexpected error
      summary: List invocation history for a webhook
      tags:
      - Aiden
      x-required-scope: aios_automation_read
      x-stackgen-namespace: aiden
  /guild/api/v1/webhooks/{webhook_id}/runs/{run_id}:
    get:
      description: 'Returns one webhook invocation with the stored request payload.
        The

        run_id path segment accepts either the invocation ID or the downstream

        execution run ID when one has been recorded.

        '
      operationId: getWebhookRun
      parameters:
      - explode: false
        in: path
        name: webhook_id
        required: true
        schema:
          format: uuid
          type: string
        style: simple
      - explode: false
        in: path
        name: run_id
        required: true
        schema:
          type: string
        style: simple
      - description: The organization ID to scope the request to. If not provided,
          the personal namespace is assumed.
        explode: true
        in: query
        name: orgId
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRunDetail'
          description: Webhook invocation details.
        '404':
          description: Webhook invocation not found
        default:
          description: Unexpected error
      summary: Get a single webhook invocation
      tags:
      - Aiden
      x-required-scope: aios_automation_read
      x-stackgen-namespace: aiden
  /guild/api/v1/guild/ask/start:
    post:
      summary: Start an Ask execution (returns trace ID for polling)
      description: |
        Matches workflows from a natural-language message and starts execution.
        Returns JSON immediately; poll GET /guild/api/v1/executions/{traceId}
        until execution.status is terminal and trace_settled is true.
        Pin a workflow with entity_refs in the request body.
      operationId: startAskGuild
      parameters:
      - description: Organization / project UUID (orgId query parameter).
        in: query
        name: orgId
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskGuildRequest'
      responses:
        '200':
          description: Execution started or inputs required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskGuildStartResponse'
        '400':
          description: Missing or invalid message
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/executions:
    get:
      summary: List recent executions
      description: |
        Returns recent execution traces for status, duration, and cost. Filter by
        `session_id` to list executions for one conversation.
      operationId: listExecutions
      parameters:
      - name: session_id
        in: query
        required: false
        schema:
          type: string
        description: Filter executions by session ID.
      - name: agent_name
        in: query
        required: false
        schema:
          type: string
        description: Filter by agent name.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
        description: Maximum number of items to return.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
        description: Number of items to skip.
      - name: orgId
        in: query
        required: false
        schema:
          type: string
        description: Organization / project UUID (orgId query parameter).
      responses:
        '200':
          description: Execution list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExecutionListItem'
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/executions/{traceId}:
    get:
      summary: Get execution trace status
      description: |
        Returns execution metadata including status and trace_settled.
        Poll until status is completed or error and trace_settled is true.
      operationId: getExecutionTrace
      parameters:
      - description: Execution trace ID from startAskGuild.
        in: path
        name: traceId
        required: true
        schema:
          type: string
      - description: Organization / project UUID (orgId query parameter).
        in: query
        name: orgId
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Execution trace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceDAGResponse'
        '400':
          description: Missing or invalid trace ID
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/agents:
    post:
      summary: Register an agent
      operationId: registerAgent
      parameters:
      - description: Organization / project UUID (orgId query parameter).
        in: query
        name: orgId
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterAgentRequest'
      responses:
        '201':
          description: Agent registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentStatus'
        '409':
          description: Agent already exists
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/agents/{name}:
    put:
      summary: Update an agent
      operationId: updateAgent
      parameters:
      - description: Agent name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Organization / project UUID (orgId query parameter).
        in: query
        name: orgId
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterAgentRequest'
      responses:
        '200':
          description: Agent updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentStatus'
        '404':
          description: Agent not found
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/workflows:
    post:
      summary: Create workflow draft
      operationId: createWorkflow
      parameters:
      - description: Organization / project UUID (orgId query parameter).
        in: query
        name: orgId
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowWrite'
      responses:
        '201':
          description: Workflow created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          description: Invalid request
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/workflows/{name}:
    get:
      summary: Get workflow by name
      operationId: getWorkflow
      parameters:
      - description: Workflow name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Organization / project UUID (orgId query parameter).
        in: query
        name: orgId
        required: false
        schema:
          type: string
      - description: Include draft versions
        in: query
        name: includeDrafts
        required: false
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Workflow details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '404':
          description: Not found
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
    put:
      summary: Update workflow draft or routing status
      operationId: updateWorkflow
      parameters:
      - description: Workflow name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Organization / project UUID (orgId query parameter).
        in: query
        name: orgId
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowWrite'
      responses:
        '200':
          description: Updated workflow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '404':
          description: Not found
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/workflows/{name}/versions:
    post:
      summary: Create a new draft version of a workflow
      operationId: createWorkflowVersion
      parameters:
      - description: Workflow name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Organization / project UUID (orgId query parameter).
        in: query
        name: orgId
        required: false
        schema:
          type: string
      responses:
        '201':
          description: Draft version created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '409':
          description: Draft already exists
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/workflows/{name}/versions/{version}:
    put:
      summary: Update a draft workflow version
      operationId: updateWorkflowVersion
      parameters:
      - description: Workflow name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Version number
        in: path
        name: version
        required: true
        schema:
          type: integer
      - description: Organization / project UUID (orgId query parameter).
        in: query
        name: orgId
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowWrite'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          description: Not a draft or invalid request
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
  /guild/api/v1/workflows/{name}/versions/{version}/approve:
    post:
      summary: Approve a workflow version
      operationId: approveWorkflowVersion
      parameters:
      - description: Workflow name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Version number
        in: path
        name: version
        required: true
        schema:
          type: integer
      - description: Organization / project UUID (orgId query parameter).
        in: query
        name: orgId
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          description: Version is already approved
        default:
          description: Unexpected error
      tags:
      - Aiden
      x-stackgen-namespace: aiden
components:
  schemas:
    AskGuildRequest:
      type: object
      description: Payload for starting an Ask execution.
      required:
      - message
      properties:
        message:
          type: string
          description: Natural-language task description
        candidate_type:
          $ref: '#/components/schemas/CandidateType'
        session_id:
          type: string
          description: Session ID to continue a conversation
        inputs:
          type: object
          additionalProperties:
            type: string
          description: Workflow input key-value pairs
        entity_refs:
          type: array
          description: Pin a workflow, agent, or integration by name and type
          items:
            $ref: '#/components/schemas/EntityRef'
        source_app:
          type: string
          description: Calling application name for audit provenance
        source_metadata:
          type: object
          additionalProperties:
            type: string
          description: Arbitrary metadata from the calling application
        prior_session:
          allOf:
          - $ref: '#/components/schemas/PriorSessionPolicy'
          nullable: true
    AskGuildStartResponse:
      type: object
      description: Response from starting an Ask execution.
      properties:
        trace_id:
          type: string
          description: Execution trace ID (empty when inputs_required)
        run_id:
          type: string
          description: Workflow run ID
        session_id:
          type: string
          description: Conversation session ID
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/QualifiedCandidate'
        inputs_required:
          type: array
          items:
            type: string
          description: Missing required inputs; no workflow started yet
        extracted:
          type: object
          additionalProperties:
            type: string
        fallback_agent:
          type: string
        plan:
          type: string
          description: Name of the matched execution plan
    CandidateType:
      type: string
      enum:
      - any
      - agent
      - workflow
      - integration
      - knowledge
    DAGEdge:
      type: object
      required:
      - source
      - target
      properties:
        source:
          type: string
        target:
          type: string
    DAGNode:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        label:
          type: string
        status:
          type: string
          enum:
          - success
          - running
          - error
    EntityRef:
      type: object
      required:
      - name
      - type
      properties:
        name:
          type: string
          description: Entity name (for example workflow skill name)
        type:
          $ref: '#/components/schemas/CandidateType'
    ExecutionMeta:
      type: object
      description: Top-level metadata for an execution trace.
      properties:
        trace_id:
          type: string
        run_id:
          type: string
        agent_name:
          type: string
        status:
          type: string
          description: running, completed, or error
        started_at:
          type: string
          format: date-time
        duration_ms:
          type: integer
          format: int64
        total_cost:
          type: number
          format: double
        trace_settled:
          type: boolean
          description: True when trace metrics are final; poll until true
    ExecutionStructuredOutput:
      type: object
      properties:
        summary:
          type: string
        impact:
          type: string
        recommendations:
          type: string
        confidence:
          type: string
    PriorSessionPolicy:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
        match_mode:
          type: string
          enum:
          - exact_normalized_text
        max_summary_chars:
          type: integer
        max_age_hours:
          type: integer
        same_agent_only:
          type: boolean
          nullable: true
    QualifiedCandidate:
      type: object
      properties:
        name:
          type: string
        confidence:
          type: number
          format: double
        candidate_type:
          $ref: '#/components/schemas/CandidateType'
    TraceDAGResponse:
      type: object
      description: Execution trace with status metadata for polling.
      properties:
        truncated:
          type: boolean
        structured_output:
          $ref: '#/components/schemas/ExecutionStructuredOutput'
        execution:
          $ref: '#/components/schemas/ExecutionMeta'
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/DAGNode'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/DAGEdge'
    AlertAnalysisStatus:
      type: string
      description: Progress of Aiden auto-analysis on an alert. Never set by the operator.
      enum:
      - none
      - queued
      - running
      - completed
      - failed
    AlertAttention:
      type: string
      description: Triage classification for an alert, set by Aiden auto-analysis
        or an analyst.
      enum:
      - needs_attention
      - needs_review
      - false_positive
      - others
    AlertCategorizationSummary:
      type: object
      description: Progress counts for Aiden alert categorization across active alerts.
        Use is_running to show the loading state while categorization workflows are
        queued or running, and failed to explain alerts that could not be categorized
        automatically.
      required:
      - total_active
      - not_started
      - in_progress
      - completed
      - failed
      - is_running
      properties:
        total_active:
          type: integer
          description: Total number of alerts with status=active.
        not_started:
          type: integer
          description: Count of active alerts with analysis_status=none.
        in_progress:
          type: integer
          description: Count of active alerts with analysis_status=queued or running.
        completed:
          type: integer
          description: Count of active alerts with analysis_status=completed.
        failed:
          type: integer
          description: Count of active alerts with analysis_status=failed.
        is_running:
          type: boolean
          description: True when at least one active alert is queued or running categorization.
    AlertRole:
      type: string
      description: Cause-effect role for an alert in a correlated storm. Symptom alerts
        (latency, 5xx) surface user impact; cause alerts (pool exhaustion, CPU, restarts)
        point to upstream failure modes. Set by ingest heuristics or refined by Aiden
        triage.
      enum:
      - symptom
      - cause
      - unknown
    AlertSortBy:
      type: string
      description: 'Ordering for the alert inbox. severity keeps monitor-rank sort;
        impact surfaces estimated blast radius (env, scope, storm) first.

        '
      enum:
      - severity
      - impact
    AlertStatus:
      type: string
      description: Lifecycle status of an alert.
      enum:
      - active
      - resolved
      - ignored
    AlertSummary:
      type: object
      description: Fixed counts for active alerts by triage attention category.
      required:
      - total_active
      - needs_attention
      - others
      - needs_review
      - false_positive
      properties:
        total_active:
          type: integer
          description: Total number of alerts with status=active.
        needs_attention:
          type: integer
          description: Count of active alerts with attention=needs_attention.
        others:
          type: integer
          description: Count of active alerts with attention=others.
        needs_review:
          type: integer
          description: Count of active alerts with attention=needs_review.
        false_positive:
          type: integer
          description: Count of active alerts with attention=false_positive.
    AlertSyncRunStatus:
      type: string
      description: Status of an alert sync run (manual, scheduled, or webhook-triggered).
      enum:
      - running
      - completed
      - failed
    AlertV1:
      type: object
      description: A single alert with its current lifecycle, analysis, and triage
        state.
      required:
      - id
      - external_uid
      - source_type
      - title
      - description
      - source_severity
      - display_priority
      - impact_score
      - status
      - analysis_status
      - attention
      - triggered_at
      - created_at
      - refire_count
      properties:
        id:
          type: string
          format: uuid
          description: Internal alert UUID.
        external_uid:
          type: string
          description: Stable identifier from the alert source (e.g. Grafana fingerprint).
        source_type:
          type: string
          description: Alert source system (e.g. "grafana").
        integration_name:
          type: string
          nullable: true
          description: Human-readable name of the integration that produced this alert.
        title:
          type: string
          description: Short human-readable alert title.
        description:
          type: string
          description: Longer description or message from the alert source.
        source_severity:
          type: string
          description: Raw severity string from the source (e.g. "critical", "high").
        display_priority:
          type: integer
          description: Numeric sort key derived from severity (lower = more urgent).
        impact_score:
          type: integer
          description: 'Estimated blast-radius impact (0–100, higher = greater impact).
            Derived at ingest from environment criticality, label scope breadth, and
            co-firing storm fanout — not from monitor severity.

            '
          minimum: 0
          maximum: 100
        impact_explanation:
          type: string
          nullable: true
          description: 'Plain-English rationale for impact_score (e.g. prod environment,
            three co-firing peers) so operators can trust impact sorting.

            '
        status:
          $ref: '#/components/schemas/AlertStatus'
          description: Lifecycle status. "ignored" is set by the operator via PATCH.
        analysis_status:
          $ref: '#/components/schemas/AlertAnalysisStatus'
        attention:
          $ref: '#/components/schemas/AlertAttention'
          description: Triage classification. Set by Aiden auto-analysis once completed.
        attention_reason:
          type: string
          nullable: true
          description: Plain-English explanation for the attention classification.
        ignore_reason:
          type: string
          nullable: true
          description: Plain-English reason the operator provided when ignoring this
            alert.
        short_summary:
          type: string
          nullable: true
          description: One-liner produced by Aiden auto-analysis (sre_classify_alert_criticality)
            summarising what is happening with this alert. Rendered inline in the
            alerts list and queue ahead of the full investigation result.
        initial_investigation:
          type: string
          nullable: true
          description: First-pass write-up produced by Aiden auto-analysis. Multi-line
            text with hypotheses, related signals, and suggested next steps; rendered
            as the headline body in the alert detail drawer before the deep-dive investigation
            completes.
        triggered_at:
          type: string
          format: date-time
          description: When the alert last fired (most recent trigger from the source).
        created_at:
          type: string
          format: date-time
          description: When the alert was first triggered and ingested into SRE (unchanged
            on re-fires).
        resolved_at:
          type: string
          format: date-time
          nullable: true
          description: When the alert was last resolved.
        refire_count:
          type: integer
          description: Number of times this alert has re-fired after being resolved.
        last_resolved_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the most recent resolution (before a re-fire).
        investigation:
          $ref: '#/components/schemas/InvestigationRef'
          nullable: true
        labels:
          type: object
          description: User-facing alert labels from the monitoring source (e.g. Grafana
            Prometheus labels). Internal system keys are stripped before persistence.
          additionalProperties:
            type: string
        alert_role:
          $ref: '#/components/schemas/AlertRole'
          description: Cause-effect classification — symptom (downstream impact),
            cause (upstream failure), or unknown when heuristics are inconclusive.
        storm_id:
          type: string
          format: uuid
          nullable: true
          description: UUID grouping co-firing alerts in the same incident storm.
            Null when the alert is isolated or not yet correlated.
        likely_upstream:
          type: string
          nullable: true
          description: For symptom alerts, a plain-English hint naming the most likely
            upstream cause alert or service in the same storm.
        ingested_via:
          type: string
          nullable: true
          description: 'Ingestion-mode tag for this alert''s current episode: "push"
            (webhook) or "pull" (scheduled/manual sync). Set on first ingest and on
            re-fire from resolved; left unchanged on plain updates.'
        raw_payload:
          type: string
          nullable: true
          description: Source-native payload the ingestion/auto-investigate filters
            run on, stored verbatim as JSON text — the raw webhook body for push,
            or the marshalled source object for pull. Null on legacy rows ingested
            before raw-payload capture.
    ArtifactInfo:
      description: Information about a session artifact generated and uploaded.
      example:
        size_bytes: 1
        mime_type: mime_type
        name: name
        session_id: session_id
        created_at: 2000-01-23 04:56:07+00:00
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
      properties:
        id:
          format: uuid
          type: string
        session_id:
          type: string
        name:
          type: string
        mime_type:
          type: string
        size_bytes:
          format: int64
          type: integer
        created_at:
          format: date-time
          type: string
      required:
      - id
      - mime_type
      - name
      - session_id
      - size_bytes
      type: object
    ErrorResponse:
      type: object
      description: Standard error response body.
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Machine-readable error code.
        details:
          type: object
          description: Additional structured details about the error.
          additionalProperties: true
    InvestigateAlertRequest:
      type: object
      description: Optional parameters for starting or retrieving an alert investigation.
      properties:
        force_new:
          type: boolean
          description: Force a new investigation to be created.
          default: false
        remediation_requested:
          type: boolean
          description: When true, satisfy on_request remediation mode for this run
            (attempt a HITL-gated fix PR when evidence supports a durable code change).
            Ignored when remediation mode is off.
          default: false
        operator_message:
          type: string
          description: Optional operator text for this investigation. When it explicitly
            asks to open a fix PR or remediate, it satisfies on_request remediation
            mode the same as remediation_requested.
    InvestigateResponse:
      type: object
      description: Investigation started or existing investigation returned.
      required:
      - investigation
      properties:
        investigation:
          $ref: '#/components/schemas/InvestigationRef'
    Investigation:
      type: object
      description: Full investigation record returned by /api/v1/investigations.
      required:
      - id
      - alert_id
      - guild_trace_id
      - status
      - started_at
      properties:
        id:
          type: string
          format: uuid
        alert_id:
          type: string
          format: uuid
        guild_trace_id:
          type: string
        guild_session_id:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/InvestigationStatus'
        result_summary:
          type: string
          nullable: true
        parent_investigation_id:
          type: string
          format: uuid
          nullable: true
          description: When this investigation was created by forking another, the
            parent investigation it was forked from. Null for normal investigations.
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
          nullable: true
        evidence:
          type: array
          description: Clickable evidence URLs attached to this investigation, in
            capture order. Empty when the agent has not submitted any citations.
          items:
            $ref: '#/components/schemas/InvestigationEvidence'
        structured_rca:
          $ref: '#/components/schemas/InvestigationStructuredRCA'
          nullable: true
        hypotheses:
          type: array
          description: Ranked investigation hypotheses produced during structured
            triage. Empty when the agent has not submitted hypothesis rows.
          items:
            $ref: '#/components/schemas/InvestigationHypothesis'
        prior_incidents:
          type: array
          description: Similar prior incidents matched from memory or history. Empty
            when none were found or submitted.
          items:
            $ref: '#/components/schemas/InvestigationPriorIncident'
        triage_metadata:
          $ref: '#/components/schemas/InvestigationTriageMetadata'
          nullable: true
    InvestigationEvidence:
      type: object
      description: A single clickable citation attached to an investigation. Submitted
        by the Aiden agent via the `sre_update_investigation_status` or `sre_submit_investigation_evidence`
        MCP callbacks. `verified` and `captured_at` are always set server-side regardless
        of what the caller passes.
      required:
      - kind
      - title
      - url
      - source
      - verified
      - captured_at
      properties:
        kind:
          $ref: '#/components/schemas/InvestigationEvidenceKind'
        title:
          type: string
          description: Short, human-readable label for the evidence row.
        url:
          type: string
          format: uri
          description: Absolute http(s) URL the user can open.
        description:
          type: string
          nullable: true
          description: 'Plain DevOps context shown below the title: what this link
            shows and why it matters for triage (breach timing, firing condition,
            upstream dependency, prior incident match, etc.). Set by the agent when
            submitting evidence; the server may infer a default from kind or tool
            when omitted.'
        source:
          $ref: '#/components/schemas/InvestigationEvidenceSource'
        tool_name:
          type: string
          nullable: true
          description: Name of the tool invocation that produced this URL (only set
            when source=tool_trace).
        verified:
          type: boolean
          description: True when the URL host matches the per-tenant active-integration
            allowlist. Always set server-side; clients cannot mark a URL verified.
        captured_at:
          type: string
          format: date-time
          description: Server timestamp when the URL was persisted.
    InvestigationEvidenceKind:
      type: string
      description: Categorises an evidence URL so the UI can pick the right icon and
        group items by signal type.
      enum:
      - dashboard
      - metric
      - log
      - trace
      - runbook
      - alert_rule
      - console
      - code
      - other
    InvestigationEvidenceSource:
      type: string
      description: 'Provenance of an evidence URL. Drives UI trust labelling: `runbook`
        and `tool_trace` are treated as grounded citations, `llm` items are accepted
        but optionally labelled if outside the active-integration host allowlist,
        and `prior_knowledge` items render as non-clickable suggestions unless the
        host is verified.'
      enum:
      - llm
      - tool_trace
      - runbook
      - prior_knowledge
    InvestigationHypothesis:
      type: object
      description: A single ranked hypothesis explored during triage.
      required:
      - statement
      properties:
        statement:
          type: string
          description: Plain-language hypothesis statement.
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          nullable: true
          description: Confidence in this hypothesis (0–1).
        status:
          type: string
          enum:
          - open
          - confirmed
          - rejected
          nullable: true
          description: Lifecycle status of the hypothesis after evidence review.
    InvestigationPlainSummary:
      type: object
      description: Plain-language investigation answer and reasoning path for developers.
        Answer fields summarize the conclusion; how_we_got_here lists the short ordered
        steps that led there. No agent-internal vocabulary. When present, callers
        should populate verdict, what_broke, what_to_do, and how_we_got_here; fields
        are not OpenAPI-required so omitted plain_summary does not fail nested Assert
        on zero-value StructuredRCA.
      properties:
        verdict:
          type: string
          description: High-level answer class for the investigation.
          enum:
          - real_problem
          - alert_is_misconfigured
          - not_enough_information
        what_broke:
          type: string
          description: One sentence a developer who has never seen this service can
            understand. Name the service and what users saw or what the alert claimed.
            No internal agent vocabulary.
        what_to_do:
          type: string
          description: One concrete next action on the customer system (fix the alert,
            check a dependency, roll back a deploy). Never an action on the investigation
            agent itself such as rehydrating a signal cache.
        how_we_got_here:
          type: array
          description: 'Ordered path of 2–5 short plain-language steps. Each step
            is one sentence: what we checked and what it showed. Developer vocabulary
            only — no snapshot SHAs, plane names, or ledger jargon.'
          minItems: 2
          maxItems: 5
          items:
            type: string
            description: One plain-language reasoning step in the investigation path.
    InvestigationPriorIncident:
      type: object
      description: A prior incident similar to the current alert context.
      required:
      - title
      properties:
        alert_id:
          type: string
          format: uuid
          nullable: true
          description: Internal alert UUID when the prior incident is known.
        title:
          type: string
          description: Short title of the prior incident.
        similarity:
          type: number
          format: float
          minimum: 0
          maximum: 1
          nullable: true
          description: Similarity score to the current alert (0–1).
        confidence_boost:
          type: number
          format: float
          minimum: 0
          maximum: 1
          nullable: true
          description: How much this match should boost downstream hypothesis confidence.
    InvestigationRecommendedNextStep:
      type: object
      description: One tiered remediation action with risk, verification, and optional
        operator commands for kubectl or gh.
      required:
      - tier
      - action
      properties:
        tier:
          type: string
          description: Mitigation tier such as immediate_containment, immediate_app,
            restore_observability, secondary_cluster, or preventive.
        action:
          type: string
          description: Plain-language remediation action for operators.
        risk:
          type: string
          description: Risk level such as low, medium, or high.
        approval_required:
          type: boolean
          description: Whether operator approval is required before execution.
        expected_impact:
          type: string
          description: Expected outcome after the action succeeds.
        verify:
          type: string
          description: Metric or log check that confirms success.
        rollback:
          type: string
          description: How to undo the action if verification fails.
        operator_commands:
          type: array
          description: Copy-paste kubectl or gh commands for operators.
          items:
            type: string
    InvestigationRef:
      type: object
      description: Minimal reference to a Aiden investigation linked to an alert.
      required:
      - id
      - alert_id
      - guild_trace_id
      - status
      properties:
        id:
          type: string
          format: uuid
          description: Investigation UUID.
        alert_id:
          type: string
          format: uuid
          description: Alert UUID that triggered this investigation.
        guild_trace_id:
          type: string
          description: Aiden trace ID used to stream live investigation output.
        guild_session_id:
          type: string
          nullable: true
          description: Aiden session ID for the in-progress chat run. Populated by
            Aiden MCP callbacks once the session is created. Used by the UI to deep
            link into the conversation view.
        status:
          $ref: '#/components/schemas/InvestigationStatus'
          description: Current investigation status.
        result_summary:
          type: string
          nullable: true
          description: Short summary of the investigation result, once completed.
        parent_investigation_id:
          type: string
          format: uuid
          nullable: true
          description: When this investigation was created by forking another, the
            parent investigation it was forked from. Null for normal investigations.
        evidence_count:
          type: integer
          description: Number of evidence URLs persisted on the investigation. Computed
            server-side via jsonb_array_length so it stays consistent with the full
            list returned by /api/v1/investigations/{id}.
          minimum: 0
          default: 0
    InvestigationStatus:
      type: string
      description: Lifecycle status of a Aiden investigation. `draft` means triage
        was persisted with gaps (more info requested) and is not operator-final.
      enum:
      - queued
      - running
      - draft
      - completed
      - failed
      - cancelled
      - resolved
    InvestigationStructuredHypothesisEntry:
      type: object
      description: A ruled-out or unverified hypothesis recorded in structured RCA.
      required:
      - statement
      properties:
        statement:
          type: string
          description: Plain-language hypothesis statement.
        falsifier:
          type: string
          description: Evidence that would falsify the hypothesis.
          nullable: true
        reason:
          type: string
          description: Why the hypothesis was ruled out or left unverified.
          nullable: true
        missing_capability:
          type: string
          description: Tool or integration gap that blocked verification.
          nullable: true
        what_would_falsify:
          type: string
          description: Concrete signal that would confirm or reject the hypothesis.
          nullable: true
    InvestigationStructuredLimitationEntry:
      type: object
      description: An observability or integration limitation recorded during triage.
      properties:
        plane:
          type: string
          description: Observability plane (metrics, logs, traces, etc.).
          nullable: true
        datasource_uid_or_tool:
          type: string
          description: Datasource UID or tool name that was unavailable.
          nullable: true
        error_verbatim:
          type: string
          description: Raw error text from the failed probe.
          nullable: true
        operator_action:
          type: string
          description: Suggested operator follow-up.
          nullable: true
        status:
          type: string
          description: Structured limitation outcome (e.g. selector_recovery_exhausted
            when logs recovery ran but the plane is still empty).
          nullable: true
    InvestigationStructuredRCA:
      type: object
      description: Structured root-cause analysis fields attached to an investigation
        after triage completes.
      required:
      - root_cause
      - impact
      - mitigation
      - confidence
      properties:
        root_cause:
          type: string
          description: Identified or suspected root cause in plain language.
        impact:
          type: string
          description: User or system impact summary.
        mitigation:
          type: string
          description: Recommended mitigation or next steps.
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Agent confidence in the RCA (0–1).
        unverified_hypotheses:
          type: array
          description: Hypotheses that could not be confirmed or ruled out during
            triage.
          items:
            $ref: '#/components/schemas/InvestigationStructuredHypothesisEntry'
        ruled_out_hypotheses:
          type: array
          description: Hypotheses falsified during investigation.
          items:
            $ref: '#/components/schemas/InvestigationStructuredHypothesisEntry'
        investigation_limitations:
          type: array
          description: Observability or integration gaps encountered during triage.
          items:
            $ref: '#/components/schemas/InvestigationStructuredLimitationEntry'
        recommended_next_steps:
          type: array
          description: Tiered remediation steps with verification, rollback, and operator
            commands. Required when triage status is completed; also required for
            HTTP error incidents.
          items:
            $ref: '#/components/schemas/InvestigationRecommendedNextStep'
        plain_summary:
          $ref: '#/components/schemas/InvestigationPlainSummary'
          nullable: true
          description: 'Developer-facing puzzle solve: a clear Answer (verdict, what
            broke, what to do) plus a short Path (how we got there). Prefer this over
            technical root_cause for operators who are not SREs.'
    InvestigationTriageMetadata:
      type: object
      description: Opaque-but-typed metadata about how structured triage was produced
        (classifier version, storm context, timestamps, draft follow-ups).
      properties:
        alert_role:
          $ref: '#/components/schemas/AlertRole'
          nullable: true
        storm_context:
          type: string
          enum:
          - single
          - correlated
          nullable: true
          description: Whether triage ran on a lone alert or a correlated storm.
        classifier_version:
          type: string
          nullable: true
          description: Version tag of the heuristic or agent classifier used.
        classified_at:
          type: string
          format: date-time
          nullable: true
          description: When cause-effect classification was last applied.
        more_info_requested:
          type: array
          nullable: true
          description: Gaps requested when triage was accepted as draft instead of
            completed. Operators and follow-up submits should address every entry.
          items:
            type: string
        more_info_notes:
          type: string
          nullable: true
          description: Plain-English note for operators explaining why the investigation
            is still draft. Agent-facing gap codes stay in more_info_requested.
    ListAlertsResponse:
      type: object
      description: Paginated alert list with summary counts.
      required:
      - summary
      - categorization
      - alerts
      - pagination
      properties:
        summary:
          $ref: '#/components/schemas/AlertSummary'
        categorization:
          $ref: '#/components/schemas/AlertCategorizationSummary'
        alerts:
          type: array
          description: Current page of alerts.
          items:
            $ref: '#/components/schemas/AlertV1'
        pagination:
          $ref: '#/components/schemas/Pagination'
        active_sync:
          $ref: '#/components/schemas/SyncResponse'
          nullable: true
          description: 'The currently running alert sync run for any integration,
            if one is in progress at the time of this request. Null when no pull is
            active. The UI must use this to show a loading/syncing indicator without
            needing a separate GET /api/v1/alerts/sync?status=running call on every
            poll cycle.

            '
    ListInvestigationsResponse:
      type: object
      description: Paginated investigation list.
      required:
      - investigations
      - pagination
      properties:
        investigations:
          type: array
          items:
            $ref: '#/components/schemas/Investigation'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      description: Pagination metadata for a list response.
      required:
      - page
      - page_size
      - total
      properties:
        page:
          type: integer
          description: Current page number (1-based).
        page_size:
          type: integer
          description: Number of items per page.
        total:
          type: integer
          format: int64
          description: Total number of matching items.
    ScheduleRunStatus:
      description: Status of a schedule execution run.
      enum:
      - running
      - success
      - failed
      - skipped
      type: string
    ScheduleTargetType:
      description: 'Whether the schedule or webhook targets an agent, a workflow,
        or an

        installed app. App targets POST a fixed payload to endpoint_path on the

        catalog install URL (schedules on cron; webhooks on inbound trigger).

        '
      enum:
      - agent
      - workflow
      - app
      type: string
    Session:
      description: Detailed, rich view of a conversation session offering profound
        insights and a 'wow' factor for users.
      example:
        summary: summary
        responder_kind: agent
        agent_name: agent_name
        total_cost: 6.027456183070403
        workflow_name: workflow_name
        source_metadata:
          key: source_metadata
        session_id: session_id
        title: title
        tags:
        - tags
        - tags
        duration_ms: 0
        archived: true
        last_activity: 2000-01-23 04:56:07+00:00
        event_counts:
          key: 5
        starred: true
        source_app: source_app
        started_at: 2000-01-23 04:56:07+00:00
        primary_query: primary_query
        responder_name: responder_name
        required_completion_tools:
        - upload_artifacts
        started_by: started_by
        started_by_id: started_by_id
        prompt: prompt
        artifacts:
        - size_bytes: 1
          mime_type: mime_type
          name: name
          session_id: session_id
          created_at: 2000-01-23 04:56:07+00:00
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        - size_bytes: 1
          mime_type: mime_type
          name: name
          session_id: session_id
          created_at: 2000-01-23 04:56:07+00:00
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
      properties:
        session_id:
          description: Logical session identifier.
          type: string
        agent_name:
          description: Agent that handled this session.
          type: string
        started_by:
          description: User email of the person who initiated the session.
          type: string
        started_by_id:
          description: ID of the person who initiated the session.
          type: string
        started_at:
          description: Timestamp of the first event.
          format: date-time
          type: string
        last_activity:
          description: Timestamp of the most recent event.
          format: date-time
          type: string
        duration_ms:
          description: Total active duration of the session in milliseconds.
          format: int32
          type: integer
        primary_query:
          description: The full initial request or primary prompt that started the
            session.
          type: string
        summary:
          description: AI-generated, rich-text summary of the session's overall outcome,
            key decisions, or final state.
          type: string
        total_cost:
          description: Total estimated cost in USD for this session. Returns -1 if
            the cost is not yet calculated or the session is actively running.
          format: double
          type: number
        artifacts:
          description: List of artifacts (files, images, etc.) uploaded or generated
            during the session.
          items:
            $ref: '#/components/schemas/ArtifactInfo'
          type: array
        event_counts:
          additionalProperties:
            format: int32
            type: integer
          description: Dictionary mapping event types (e.g., 'chat_request', 'tool_call',
            'error') to their respective counts within the session.
          type: object
        tags:
          description: AI-generated labels categorizing the session for quick filtering
            (e.g., 'Security', 'Database', 'High Cost').
          items:
            type: string
          type: array
        workflow_name:
          description: Name of the workflow that was executed in this session. Empty
            for direct agent chat sessions.
          type: string
        prompt:
          description: Short snippet of the original user request (max 120 chars).
            Mirrors the list view's prompt so detail and list agree.
          type: string
        source_app:
          description: Installed application that initiated the session, when applicable.
          type: string
        responder_kind:
          $ref: '#/components/schemas/SessionResponderKind'
        responder_name:
          description: Display name of the primary responder (agent name, workflow
            name, or app id).
          type: string
        title:
          description: User-assigned display name for this session. When set, shown
            instead of the prompt snippet.
          type: string
        starred:
          description: Whether the user has starred (favourited) this session.
          type: boolean
        archived:
          description: Whether the conversation is archived and omitted from active
            history.
          type: boolean
        source_metadata:
          additionalProperties:
            type: string
          description: 'Arbitrary key-value metadata from the initiating app. Examples:
            alert_id, dashboard_url, severity, etc.

            '
          type: object
        required_completion_tools:
          description: 'Immutable session policy listing tool names that must SUCCESSFULLY

            execute at least once before each Plan/ReAcTree Chat may finish.

            Empty when no completion gate was set for this session.

            '
          example:
          - upload_artifacts
          items:
            type: string
          type: array
      type: object
    SessionResponderKind:
      description: Kind of primary responder for a session.
      enum:
      - agent
      - workflow
      - app
      - schedule
      - webhook
      type: string
    SignalSeverity:
      type: string
      description: Normalized monitor signal severity used for alerts table badges
        and severity filtering. Maps multiple upstream source_severity strings into
        a single bucket (for example warning and medium both map to Medium).
      enum:
      - Critical
      - High
      - Medium
      - Low
      - info
    SyncResponse:
      type: object
      description: State of an alert sync run — returned immediately on start and
        updated on poll.
      required:
      - sync_run_id
      - triggered_by
      - status
      - alerts_created
      - alerts_updated
      - alerts_resolved
      properties:
        sync_run_id:
          type: string
          format: uuid
          description: UUID of the alert_sync_runs row. Use this to poll GET /api/v1/alerts/sync/{id}.
        triggered_by:
          type: string
          description: What triggered this sync (manual, schedule, webhook, or chat_correlate).
          enum:
          - manual
          - schedule
          - webhook
          - chat_correlate
        source:
          type: string
          nullable: true
          description: Alert source type being synced (e.g. "grafana"). Null means
            the default source.
        integration_name:
          type: string
          nullable: true
          description: Integration instance name being synced (e.g. "prod-grafana").
            Null means the first available.
        started_at:
          type: string
          format: date-time
          description: When the sync run started.
        finished_at:
          type: string
          format: date-time
          nullable: true
          description: When the sync run completed or failed. Null while still running.
        status:
          $ref: '#/components/schemas/AlertSyncRunStatus'
          description: Current run status — "running", "completed", or "failed".
        alerts_created:
          type: integer
          description: Number of new alert rows created (0 while running).
        alerts_updated:
          type: integer
          description: Number of existing alert rows updated (0 while running).
        alerts_resolved:
          type: integer
          description: Number of alerts marked resolved (0 while running).
        error:
          type: string
          nullable: true
          description: Error message when status is "failed".
    TriggerWebhook202Response:
      description: 'Acknowledgement returned when a public webhook trigger starts
        dispatch.

        Newer motherships may include session_id and trace_id on the 202 body.

        When they are absent, poll GET /api/v1/webhooks/{webhook_id}/runs/{invocation_id}

        until those fields are populated.

        '
      example:
        run_id: run_id
        target_name: target_name
        webhook_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        invocation_id: invocation_id
        session_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee92
        trace_id: trace-abc
        target_type: agent
        message: message
      properties:
        run_id:
          description: Temporal dispatch workflow run ID.
          type: string
        message:
          description: Human-readable trigger status message.
          type: string
        webhook_id:
          description: Webhook configuration that accepted this trigger.
          format: uuid
          type: string
        invocation_id:
          description: 'Invocation row ID for GET /api/v1/webhooks/{webhook_id}/runs/{invocation_id}.

            Empty when invocation history is unavailable or the target does not

            record invocations (for example app-forward webhooks).

            '
          type: string
        session_id:
          description: 'Session workspace when dispatch attaches one synchronously
            on newer builds. When omitted, poll the webhook run detail until session_id
            appears.

            '
          format: uuid
          type: string
        trace_id:
          description: 'Execution trace when available on the 202 body. When omitted,
            poll the webhook run detail until trace_id appears.

            '
          type: string
        target_type:
          $ref: '#/components/schemas/ScheduleTargetType'
        target_name:
          description: Target agent, workflow, or app name snapshot at trigger time.
          type: string
      type: object
    WebhookRun:
      description: 'A single named webhook invocation. List responses include metadata
        and

        payload size/truncation information but omit the payload body.

        '
      example:
        webhook_name: webhook_name
        trace_id: trace_id
        run_id: run_id
        subscribe_url: subscribe_url
        target_name: target_name
        finished_at: 2000-01-23 04:56:07+00:00
        payload_bytes: 6
        payload_truncated: true
        target_type: agent
        session_id: session_id
        error: error
        payload_preview: payload_preview
        duration_ms: 0
        webhook_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        started_at: 2000-01-23 04:56:07+00:00
        client_ip: client_ip
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        status: running
      properties:
        id:
          description: Unique webhook invocation identifier.
          format: uuid
          type: string
        webhook_id:
          description: Webhook configuration that received this invocation.
          format: uuid
          type: string
        webhook_name:
          description: Webhook name snapshot at invocation time.
          type: string
        target_type:
          $ref: '#/components/schemas/ScheduleTargetType'
        target_name:
          description: Target agent or workflow name snapshot at invocation time.
          type: string
        status:
          $ref: '#/components/schemas/ScheduleRunStatus'
        started_at:
          description: Timestamp when the webhook was accepted.
          format: date-time
          type: string
        finished_at:
          description: Timestamp when dispatch completed, if known.
          format: date-time
          nullable: true
          type: string
        duration_ms:
          description: Dispatch duration in milliseconds when finished_at is present.
          format: int64
          type: integer
        error:
          description: Error message if dispatch failed.
          type: string
        run_id:
          description: Downstream Temporal execution run ID, empty until available.
          type: string
        trace_id:
          description: Execution trace identifier used by the subscribe endpoint.
          type: string
        session_id:
          description: 'Downstream session identifier for the dispatched run. Used
            to

            correlate this invocation with execution_agent_summaries and

            the NATS session stream. Empty until dispatch starts a run.

            '
          type: string
        subscribe_url:
          description: Relative SSE subscribe URL for the execution trace.
          type: string
        client_ip:
          description: Source IP address observed by the webhook handler.
          type: string
        payload_bytes:
          description: Original serialized payload size in bytes.
          format: int64
          type: integer
        payload_truncated:
          description: Whether the stored payload was replaced by a bounded preview.
          type: boolean
        payload_preview:
          description: Bounded payload preview, populated when payload_truncated is
            true.
          type: string
      type: object
    WebhookRunDetail:
      allOf:
      - $ref: '#/components/schemas/WebhookRun'
      - description: Webhook invocation detail including the stored request payload.
        properties:
          payload:
            additionalProperties: true
            description: Stored JSON request payload, omitted or replaced with preview
              metadata when truncated.
            nullable: true
            type: object
        type: object
      example:
        webhook_name: webhook_name
        trace_id: trace_id
        run_id: run_id
        subscribe_url: subscribe_url
        target_name: target_name
        finished_at: 2000-01-23 04:56:07+00:00
        payload_bytes: 6
        payload_truncated: true
        target_type: agent
        session_id: session_id
        error: error
        payload_preview: payload_preview
        duration_ms: 0
        webhook_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        payload:
          key: ''
        started_at: 2000-01-23 04:56:07+00:00
        client_ip: client_ip
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        status: running
    WebhookRunListResponse:
      description: Paginated webhook invocation history.
      example:
        total: 1
        items:
        - webhook_name: webhook_name
          trace_id: trace_id
          run_id: run_id
          subscribe_url: subscribe_url
          target_name: target_name
          finished_at: 2000-01-23 04:56:07+00:00
          payload_bytes: 6
          payload_truncated: true
          target_type: agent
          session_id: session_id
          error: error
          payload_preview: payload_preview
          duration_ms: 0
          webhook_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          started_at: 2000-01-23 04:56:07+00:00
          client_ip: client_ip
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: running
        - webhook_name: webhook_name
          trace_id: trace_id
          run_id: run_id
          subscribe_url: subscribe_url
          target_name: target_name
          finished_at: 2000-01-23 04:56:07+00:00
          payload_bytes: 6
          payload_truncated: true
          target_type: agent
          session_id: session_id
          error: error
          payload_preview: payload_preview
          duration_ms: 0
          webhook_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          started_at: 2000-01-23 04:56:07+00:00
          client_ip: client_ip
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          status: running
      properties:
        items:
          description: Array of webhook invocation records ordered newest-first.
          items:
            $ref: '#/components/schemas/WebhookRun'
          type: array
        total:
          description: Total number of matching webhook invocations.
          type: integer
      type: object
    JsonError:
      description: 'JSON body Aiden returns for many failed requests. Same shape as
        `github.com/appcd-dev/go-lib/problems.Problem`

        serialized to JSON (`msg`, `errCode`, optional `extras`). Keep `msg` as stable
        constant strings; put variables in `extras`

        (often one object map).

        '
      example:
        msg: msg
        errCode: errCode
        extras:
        - key: ''
        - key: ''
      properties:
        msg:
          description: Human-readable message; use constant strings for validation
            errors so metrics stay low-cardinality.
          type: string
        errCode:
          description: Machine-readable code (e.g. BAD_REQUEST, PAYLOAD_TOO_LARGE,
            NOT_FOUND).
          type: string
        extras:
          description: Optional context list; often a single object map (e.g. filename,
            max_files, session_id).
          items:
            additionalProperties: true
            type: object
          type: array
      required:
      - errCode
      - msg
      type: object
    RegisterAgentRequest:
      type: object
      description: Register or update an Aiden agent (persona + optional HITL).
      required:
      - name
      - persona
      properties:
        name:
          type: string
          description: Unique agent name
        persona:
          type: string
          description: System prompt / role for the agent
        description:
          type: string
        hitl:
          type: object
          properties:
            always_allowed:
              type: array
              items:
                type: string
        auto_approve_tools:
          type: array
          items:
            type: object
            required:
            - tool
            properties:
              tool:
                type: string
    AgentStatus:
      type: object
      description: Agent registration or update response.
      properties:
        name:
          type: string
        status:
          type: string
    WorkflowStageWrite:
      type: object
      required:
      - stage_id
      properties:
        stage_id:
          type: string
        description:
          type: string
        note:
          type: string
        required:
          type: boolean
    StageBindingWrite:
      type: object
      required:
      - stage_id
      properties:
        stage_id:
          type: string
        agent_ref:
          type: string
        depends_on:
          type: array
          items:
            type: string
        skill_refs:
          type: array
          items:
            type: string
        note:
          type: string
    WorkflowWrite:
      type: object
      description: Create or update a workflow draft (stages + bindings).
      required:
      - name
      - domain
      properties:
        name:
          type: string
        domain:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - draft
          - approved
          - deprecated
          - disabled
        required_inputs:
          type: array
          items:
            type: string
        optional_inputs:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        stages:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStageWrite'
        stage_bindings:
          type: array
          items:
            $ref: '#/components/schemas/StageBindingWrite'
    Workflow:
      type: object
      description: Workflow as returned by Aiden after create/update/approve.
      properties:
        name:
          type: string
        domain:
          type: string
        version:
          type: integer
        status:
          type: string
        description:
          type: string
        required_inputs:
          type: array
          items:
            type: string
        stages:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStageWrite'
        stage_bindings:
          type: array
          items:
            $ref: '#/components/schemas/StageBindingWrite'
    SessionSummary:
      type: object
      description: Summary of a single conversation session for list views.
      properties:
        session_id:
          type: string
          description: Logical session identifier.
        started_at:
          type: string
          format: date-time
        last_activity:
          type: string
          format: date-time
        started_by:
          type: string
        started_by_id:
          type: string
        total_cost:
          type: number
          format: double
        prompt:
          type: string
          description: Short snippet of the original user request.
        agent_name:
          type: string
        workflow_name:
          type: string
        source_app:
          type: string
        responder_kind:
          $ref: '#/components/schemas/SessionResponderKind'
        responder_name:
          type: string
        title:
          type: string
        starred:
          type: boolean
        archived:
          type: boolean
        source_metadata:
          type: object
          additionalProperties:
            type: string
          description: Arbitrary key-value metadata from the initiating app.
    SessionListResponse:
      type: object
      description: Paginated session list.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SessionSummary'
        total:
          type: integer
          description: Total number of matching sessions.
    SessionExportPartKind:
      type: string
      description: Kind of session data in an export part.
      enum:
      - notes
      - report
      - evidence
    SessionExportPart:
      type: object
      description: One part of a session export bundle.
      required:
      - kind
      - name
      - mime_type
      - content
      properties:
        kind:
          $ref: '#/components/schemas/SessionExportPartKind'
        name:
          type: string
          description: Suggested file name when this part is saved.
        mime_type:
          type: string
          description: Media type of the content (e.g. text/markdown).
        content:
          type: string
          description: The part's rendered content as text.
    SessionExport:
      type: object
      description: Composable export of a session's write-up and evidence.
      required:
      - session_id
      - generated_at
      - parts
      properties:
        session_id:
          type: string
        generated_at:
          type: string
          format: date-time
        parts:
          type: array
          items:
            $ref: '#/components/schemas/SessionExportPart'
    TerminateSessionResponse:
      type: object
      description: Result of terminating a session's active runs.
      required:
      - session_id
      - cancelled_workflows
      properties:
        session_id:
          type: string
        cancelled_workflows:
          type: integer
          description: Number of running workflows that received cancellation requests.
        reason:
          type: string
          description: Caller-supplied reason for termination, when provided.
    ExecutionListItem:
      type: object
      description: Summary of a single execution for list views.
      properties:
        trace_id:
          type: string
        agent_name:
          type: string
        session_id:
          type: string
        created_at:
          type: string
          format: date-time
        duration_ms:
          type: integer
          format: int64
        status:
          type: string
          description: completed, running, error, or unknown.
        prompt:
          type: string
        llm_calls:
          type: integer
        tool_calls:
          type: integer
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        total_cost:
          type: number
          format: double
        workflow_name:
          type: string
  securitySchemes:
    ApiToken:
      type: http
      scheme: bearer
      bearerFormat: stackgen
      description: AIDEN API token (stackgen_…)
    WebhookToken:
      type: http
      scheme: bearer
      bearerFormat: sg_aios
      description: Webhook token (sg_aios_…) for triggerWebhook only
    bearerAuth:
      bearerFormat: JWT
      description: Vault-signed JWT used by policy sidecars to authenticate with Aiden.
      scheme: bearer
      type: http
security:
- ApiToken: []