openapi.yaml

openapi: 3.0.3
info:
  title: Waylog API
  version: 0.2.0
  description: |
    HTTP API for the Waylog ingest server.

    The primary product path is schema-2.0 ingest plus the v2 read APIs used by
    the operator CLI and embedded dashboard: recent traces, error families,
    trace story, blast radius, incidents, event search, and direct trace/event
    lookup. `/v1/insight` is a compatibility endpoint; new clients should use
    `/v1/incidents/*`.

    Write endpoints require write-scope auth when auth is configured. Read
    endpoints require read-scope auth when read keys are configured.
servers:
  - url: /

tags:
  - name: Ingest
    description: Schema-2.0 event ingest and validation.
  - name: OTLP
    description: OTLP trace ingest converted into schema-2.0 events. HTTP is documented here; gRPC uses OTLP TraceService on the configured OTLP_GRPC_ADDR.
  - name: Signals
    description: Production-context facts used by incident triage.
  - name: Deployments
    description: Deployment registration (with optional commit/PR provenance) and query.
  - name: Events
    description: Direct event lookup and search.
  - name: Traces
    description: Trace lookup, recent trace summaries, and trace stories.
  - name: Triage
    description: Error-family rollups and blast-radius analysis.
  - name: Capabilities
    description: Runtime capability discovery for CLI and UI clients.
  - name: Operational
    description: Secondary operational graph, tool, and agent endpoints.
  - name: Health
    description: Process health, readiness, and metrics endpoints.

paths:
  /v1/events:
    post:
      tags: [Ingest]
      operationId: ingestEvents
      summary: Ingest schema-2.0 WideEvents
      description: |
        Accepts one schema-2.0 WideEvent as JSON or a batch as NDJSON. Accepted
        events are written to the schema-2.0 WAL before projection into the v2
        read models. Per-event schema failures are returned inside the ingest
        envelope; infrastructure failures return 503.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WideEvent'
          application/x-ndjson:
            schema:
              type: string
              description: Newline-delimited schema-2.0 WideEvent JSON objects.
      responses:
        '200':
          description: Ingest envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestEnvelope'
        '400':
          description: Malformed body, missing content type, unsupported encoding, or invalid cursor/body framing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestEnvelope'
        '401':
          description: Unauthorized
        '405':
          description: Method Not Allowed
        '413':
          description: Body or batch too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestEnvelope'
        '415':
          description: Unsupported content type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestEnvelope'
        '503':
          description: Durability or projection unavailable

  /v1/events/validate:
    post:
      tags: [Ingest]
      operationId: validateEvents
      summary: Dry-run schema-2.0 event validation
      description: |
        Parses and validates JSON or NDJSON with the same contract as
        /v1/events, but does not dedupe, write to WAL, or project events.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WideEvent'
          application/x-ndjson:
            schema:
              type: string
      responses:
        '200':
          description: Dry-run ingest envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestEnvelope'
        '400':
          description: Malformed body or unsupported encoding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestEnvelope'
        '405':
          description: Method Not Allowed
        '413':
          description: Body or batch too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestEnvelope'
        '415':
          description: Unsupported content type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestEnvelope'

  /v1/signals:
    post:
      tags: [Signals]
      operationId: ingestSignal
      summary: Ingest one production-context signal
      description: |
        Accepts one low-volume production-context signal, such as a deploy,
        dependency, runtime, healthcheck, config, or alert fact. Signals require
        SQLite persistence and are used by the v2.1 incident engine.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Signal'
      responses:
        '201':
          description: Signal accepted and persisted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignalAccepted'
        '400':
          description: Invalid signal JSON or fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadError'
        '401':
          description: Unauthorized
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadError'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadError'
        '503':
          description: Signal storage unavailable; set SQLITE_PATH
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadError'
        '500':
          description: Internal signal storage error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadError'

  /v1/alerts:
    post:
      tags: [Signals]
      operationId: ingestAlert
      summary: Ingest an external alert and correlate it with an active incident
      description: |
        Accepts Waylog-normalized alerts plus Alertmanager, Grafana, and
        PagerDuty webhook payloads. Accepted alerts are stored as `type=alert`
        signals and correlated with active incidents when possible. Alerts do
        not create incidents — the spike detector owns incident lifecycle.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '201':
          description: Alert accepted and stored as a signal
          content:
            application/json:
              schema:
                type: object
                required: [signal, match]
                properties:
                  signal:
                    $ref: '#/components/schemas/Signal'
                  match:
                    type: object
                    required: [matched, strategy]
                    properties:
                      matched: {type: boolean}
                      incident_id: {type: string}
                      strategy:
                        type: string
                        enum: [incident_id, trace_id, family, none]
        '400':
          description: Invalid JSON, unsupported alert shape, or missing required fields
        '401':
          description: Unauthorized
        '405':
          description: Method Not Allowed
        '503':
          description: Signal store unavailable

  /v1/deployments:
    post:
      tags: [Deployments]
      operationId: registerDeployment
      summary: Register a deployment
      description: |
        Registers a deployment so the incident engine can correlate it to error
        spikes. CI should include the optional commit/PR provenance
        (`commit_sha`, `pr_url`, `commit_author`) at deploy time; these are
        opaque, vendor-neutral strings surfaced later in the triage report's
        Suspect Change section and the `suspect_change` tool. Requires SQLite.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentRequest'
      responses:
        '201':
          description: Deployment registered
          content:
            application/json:
              schema:
                type: object
                required: [id]
                properties:
                  id: {type: string}
        '400':
          description: Invalid JSON or missing required fields (id, service, env)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadError'
        '401':
          description: Unauthorized
        '409':
          description: Deployment env conflict (id already registered to a different env)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadError'
        '503':
          description: Cold store unavailable; set SQLITE_PATH
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadError'
    get:
      tags: [Deployments]
      operationId: listDeployments
      summary: List recent deployments with error-rate enrichment
      description: |
        Returns deployments whose first_seen falls within the window, each
        enriched with the before/after error-rate comparison around the deploy.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - name: window
          in: query
          description: Lookback duration (Go duration, e.g. 1h). Capped at 24h.
          schema: {type: string, default: 1h}
        - name: service
          in: query
          description: Optional service filter.
          schema: {type: string}
      responses:
        '200':
          description: Deployments in the window
          content:
            application/json:
              schema:
                type: object
                required: [deployments]
                properties:
                  deployments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Deployment'
        '401':
          description: Unauthorized
        '503':
          description: Cold store unavailable; set SQLITE_PATH

  /v1/otlp/v1/traces:
    post:
      tags: [OTLP]
      operationId: ingestOTLPTraces
      summary: Ingest OTLP/HTTP traces
      description: |
        Accepts OTLP ExportTraceServiceRequest protobuf bodies. HTTP spans are
        converted into schema-2.0 WideEvents and ingested through the same WAL
        and projector as SDK events. Unsupported spans and validation rejects
        are reported via OTLP partial_success. The same trace conversion path
        is available over OTLP/gRPC TraceService when the gRPC receiver is
        enabled.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/x-protobuf:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: OTLP ExportTraceServiceResponse protobuf
          content:
            application/x-protobuf:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid gzip body, unreadable body, or invalid protobuf
        '401':
          description: Unauthorized
        '405':
          description: Method Not Allowed
        '413':
          description: Request body too large
        '415':
          description: Unsupported content type or content encoding
        '503':
          description: v2 ingest infrastructure unavailable

  /v1/events/{event_id}:
    get:
      tags: [Events]
      operationId: getEvent
      summary: Get one schema-2.0 event
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/EventID'
      responses:
        '200':
          description: Event wrapper
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventGetResponse'
        '400':
          $ref: '#/components/responses/ReadBadRequest'
        '404':
          $ref: '#/components/responses/ReadNotFound'

  /v1/events/search:
    get:
      tags: [Events]
      operationId: searchEvents
      summary: Search schema-2.0 events
      description: Searches the v2 recent index with cursor pagination.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/Service'
        - $ref: '#/components/parameters/StatusCSV'
        - $ref: '#/components/parameters/ErrorCode'
        - $ref: '#/components/parameters/TraceIDQuery'
        - $ref: '#/components/parameters/Since'
        - $ref: '#/components/parameters/Until'
        - $ref: '#/components/parameters/Window'
        - $ref: '#/components/parameters/IncludeSuppressed'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Event search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSearchResponse'
        '400':
          $ref: '#/components/responses/ReadBadRequest'

  /v1/traces/{trace_id}:
    get:
      tags: [Traces]
      operationId: getTraceEvents
      summary: Get all events for a trace
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TraceIDPath'
      responses:
        '200':
          description: Trace events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceGetResponse'
        '400':
          $ref: '#/components/responses/ReadBadRequest'
        '404':
          $ref: '#/components/responses/ReadNotFound'

  /v1/traces/recent:
    get:
      tags: [Traces]
      operationId: listRecentTraces
      summary: Recent traces
      description: Returns recent trace summaries ordered by time descending with cursor pagination.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/Service'
        - $ref: '#/components/parameters/StatusCSV'
        - $ref: '#/components/parameters/Since'
        - $ref: '#/components/parameters/Until'
        - $ref: '#/components/parameters/Window'
        - $ref: '#/components/parameters/IncludeSuppressed'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Recent trace summaries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecentTracesResponse'
        '400':
          $ref: '#/components/responses/ReadBadRequest'

  /v1/traces/story:
    get:
      tags: [Traces]
      operationId: getTraceStory
      summary: Explain a trace as an execution story
      description: Returns the service, route, first failing step, contributing path, logs, downstream calls, and linkage mode for one trace or event.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - in: query
          name: event_id
          schema:
            type: string
          description: Event ID to explain. Exactly one of event_id or trace_id is required.
        - in: query
          name: trace_id
          schema:
            type: string
          description: Trace ID to explain. Exactly one of event_id or trace_id is required.
      responses:
        '200':
          description: Trace story
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoryResponse'
        '400':
          $ref: '#/components/responses/ReadBadRequest'
        '404':
          $ref: '#/components/responses/ReadNotFound'

  /v1/errors:
    get:
      tags: [Triage]
      operationId: listErrorFamilies
      summary: Error family rollups
      description: Groups failures by service, step, and error code. Suppressed events are excluded from error rollups.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/Service'
        - $ref: '#/components/parameters/ErrorStatusCSV'
        - $ref: '#/components/parameters/Since'
        - $ref: '#/components/parameters/Until'
        - $ref: '#/components/parameters/Window'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Error family rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsResponse'
        '400':
          $ref: '#/components/responses/ReadBadRequest'

  /v1/blast_radius:
    get:
      tags: [Triage]
      operationId: getBlastRadius
      summary: Blast radius for an error family or error code
      description: |
        Computes affected requests, users, and services for one error family or
        for all families with the same error code.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/Service'
        - in: query
          name: step
          schema:
            type: string
          description: Step name. Use with service and error_code for single-family mode.
        - $ref: '#/components/parameters/ErrorCode'
        - in: query
          name: error_family
          schema:
            type: string
          description: Display form service:step:error_code.
        - $ref: '#/components/parameters/Since'
        - $ref: '#/components/parameters/Until'
        - $ref: '#/components/parameters/Window'
      responses:
        '200':
          description: Blast radius
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlastRadiusResponse'
        '400':
          $ref: '#/components/responses/ReadBadRequest'

  /v1/incidents/active:
    get:
      tags: [Triage]
      operationId: listActiveIncidents
      summary: Active v2.1 incidents
      description: Returns active and recovering incidents derived from v2 error-family spikes, signals, and deployment context.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      responses:
        '200':
          description: Active incidents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentListResponse'
        '401':
          description: Unauthorized
        '405':
          description: Method Not Allowed

  /v1/incidents/{id}:
    get:
      tags: [Triage]
      operationId: getIncident
      summary: Get one incident
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IncidentID'
      responses:
        '200':
          description: Incident detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentDetailResponse'
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/ReadNotFound'
        '405':
          description: Method Not Allowed

  /v1/incidents/{id}/snapshot:
    get:
      tags: [Triage]
      operationId: getIncidentSnapshot
      summary: Render an incident snapshot
      description: |
        Defaults to text/plain. Send Accept: application/json to receive the
        snapshot text plus the incident object.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IncidentID'
      responses:
        '200':
          description: Incident snapshot
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentSnapshotResponse'
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/ReadNotFound'
        '405':
          description: Method Not Allowed

  /v1/triage/{incident_id}:
    get:
      tags: [Triage]
      operationId: getTriageReport
      summary: Build a deterministic TriageReport for an open incident
      description: |
        Returns a structured TriageReport v1 (incident_ref, blast_snapshot,
        first_failure, sample_traces, signals, next_checks, confidence,
        report_hash). Same builder backs `POST /v1/tools/triage_incident`;
        both surfaces produce identical `report_hash` for the same input.
        Read-scope auth.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - name: incident_id
          in: path
          required: true
          schema: {type: string}
        - name: window
          in: query
          required: false
          schema: {type: string, default: "15m"}
          description: Go duration string (e.g. 15m, 1h). Default 15m.
        - name: snapshot
          in: query
          required: false
          schema: {type: boolean, default: false}
          description: |
            When true, freeze evaluation bounds to the incident's started_at
            and updated_at instead of using wall-clock now.
      responses:
        '200':
          description: TriageReport v1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriageReport'
        '400':
          description: Missing or invalid parameters
        '401':
          description: Unauthorized
        '500':
          description: Triage build failed

  /v1/triage/{incident_id}/report:
    get:
      tags: [Triage]
      operationId: renderTriageReport
      summary: Render a cited operator report from a TriageReport
      description: |
        Builds the same deterministic TriageReport as `/v1/triage/{incident_id}`
        and renders it as Markdown, Slack Block Kit JSON, or PagerDuty note text.
        This endpoint does not deliver messages to Slack or PagerDuty.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - name: incident_id
          in: path
          required: true
          schema: {type: string}
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [markdown, slack, pagerduty]
            default: markdown
        - name: window
          in: query
          required: false
          schema: {type: string, default: "15m"}
        - name: snapshot
          in: query
          required: false
          schema: {type: boolean, default: false}
      responses:
        '200':
          description: Rendered operator report
          content:
            text/markdown:
              schema: {type: string}
            text/plain:
              schema: {type: string}
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Missing or invalid parameters
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/ReadNotFound'
        '500':
          description: Triage build or render failed

  /v1/insight:
    get:
      tags: [Operational]
      operationId: getCompatibilityInsight
      summary: Compatibility anomaly insight
      deprecated: true
      description: |
        Compatibility endpoint for older dashboard/tool consumers. When the
        v2.1 incident engine is running, this projects the top active incident
        into the legacy insight shape. Otherwise it falls back to the legacy
        detector. New clients should use `/v1/incidents/active` and
        `/v1/incidents/{id}`.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      responses:
        '200':
          description: Compatibility insight object
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '204':
          description: No active insight
        '401':
          description: Unauthorized
        '405':
          description: Method Not Allowed

  /v1/capabilities:
    get:
      tags: [Capabilities]
      operationId: getCapabilities
      summary: Runtime capabilities
      description: Returns runtime feature/configuration flags used by CLI and UI clients.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      responses:
        '200':
          description: Capabilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapabilitiesResponse'
        '405':
          description: Method Not Allowed


  /v1/ask:
    post:
      tags: [Operational]
      operationId: askWaylog
      summary: Ask Waylog
      description: Executes a natural-language query through the configured LLM provider and tool registry.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt:
                  type: string
                max_steps:
                  type: integer
                  minimum: 1
                  maximum: 8
      responses:
        '200':
          description: Query answered
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid request
        '413':
          description: Request Entity Too Large
        '502':
          description: Provider or tool execution failure
        '503':
          description: LLM provider unavailable

  /v1/plans/execute:
    post:
      tags: [Operational]
      operationId: executePlan
      summary: Execute a deterministic tool plan
      description: |
        Executes explicit plan steps or a built-in template shorthand. The
        `triage` template expands to one `triage_incident` tool step; the
        resulting TriageReport is returned at `steps[0].result`.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [steps]
                  properties:
                    steps:
                      type: array
                      minItems: 1
                      maxItems: 10
                      items:
                        type: object
                        required: [id, tool]
                        properties:
                          id: {type: string}
                          tool: {type: string}
                          params:
                            type: object
                            additionalProperties: true
                - type: object
                  required: [template, params]
                  properties:
                    template:
                      type: string
                      enum: [triage]
                    params:
                      type: object
                      required: [incident_id]
                      properties:
                        incident_id: {type: string}
                        window: {type: string, default: 15m}
                        snapshot: {type: boolean, default: false}
      responses:
        '200':
          description: Plan execution result
          headers:
            X-Plan-ID:
              schema: {type: string}
              description: Plan ID for `/v1/stream/plans/{id}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanResult'
        '400':
          description: Invalid plan or template parameters
        '503':
          description: Tool registry unavailable

  /v1/tools/{name}:
    post:
      tags: [Operational]
      operationId: executeTool
      summary: Direct tool call
      description: |
        Executes a registered structured tool by name. `triage_incident`
        returns a TriageReport; `render_triage_report` renders that report as
        Markdown, Slack Block Kit JSON, or PagerDuty note text without delivery.
      security:
        - ApiKeyHeader: []
        - BearerAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Tool output
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid params
        '404':
          description: Tool not found
        '422':
          description: Tool execution failed
        '503':
          description: Store unavailable

  /healthz:
    get:
      tags: [Health]
      operationId: getHealth
      summary: Health check
      responses:
        '200':
          description: Health status
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /livez:
    get:
      tags: [Health]
      operationId: getLiveness
      summary: Liveness probe
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: ok

  /readyz:
    get:
      tags: [Health]
      operationId: getReadiness
      summary: Readiness probe
      responses:
        '200':
          description: Ready
          content:
            text/plain:
              schema:
                type: string
                example: ok
        '503':
          description: Not ready

  /metrics:
    get:
      tags: [Health]
      operationId: getMetrics
      summary: Prometheus metrics
      responses:
        '200':
          description: Prometheus exposition
          content:
            text/plain:
              schema:
                type: string

components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key supplied via X-API-Key. Required for write or read operations when the corresponding server key is configured.
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token alternative to X-API-Key. Required for write or read operations when the corresponding server key is configured.

  parameters:
    EventID:
      name: event_id
      in: path
      required: true
      schema:
        type: string
    TraceIDPath:
      name: trace_id
      in: path
      required: true
      schema:
        type: string
    IncidentID:
      name: id
      in: path
      required: true
      schema:
        type: string
    TraceIDQuery:
      name: trace_id
      in: query
      schema:
        type: string
    Service:
      name: service
      in: query
      schema:
        type: string
    StatusCSV:
      name: status
      in: query
      schema:
        type: string
      description: "Comma-separated status list: ok,error,timeout,partial,aborted,suppressed."
    ErrorStatusCSV:
      name: status
      in: query
      schema:
        type: string
      description: "Comma-separated failure status list: error,timeout,partial,aborted."
    ErrorCode:
      name: error_code
      in: query
      schema:
        type: string
    Since:
      name: since
      in: query
      schema:
        type: string
        format: date-time
    Until:
      name: until
      in: query
      schema:
        type: string
        format: date-time
    Window:
      name: window
      in: query
      schema:
        type: string
      description: Go duration string such as 15m or 1h.
    IncludeSuppressed:
      name: include_suppressed
      in: query
      schema:
        type: boolean
        default: false
    Cursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Opaque cursor from next_cursor.
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 200

  responses:
    ReadBadRequest:
      description: Invalid query or request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReadError'
    ReadNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReadError'

  schemas:
    IngestEnvelope:
      type: object
      required: [accepted, duplicate, rejected, deprecations]
      example:
        accepted: 1
        duplicate: 0
        rejected: []
        deprecations: {}
      properties:
        accepted:
          type: integer
        duplicate:
          type: integer
        rejected:
          type: array
          items:
            $ref: '#/components/schemas/RejectedEvent'
        deprecations:
          type: object
          additionalProperties:
            type: integer

    RejectedEvent:
      type: object
      required: [index, reason]
      properties:
        index:
          type: integer
        event_id:
          type: string
        reason:
          type: string
          enum:
            - invalid_json
            - schema_validation_failed
            - bridge_not_implemented
            - batch_oversize
            - body_oversize
            - unsupported_content_type
            - unsupported_content_encoding
            - invalid_body
            - durability_unavailable
        detail:
          type: string

    ReadError:
      type: object
      required: [error]
      example:
        error:
          code: invalid_query
          message: window must be a valid duration
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string
            detail:
              type: string

    WideEvent:
      type: object
      required: [schema_version, event_id, ts_start, ts_end, kind, service, env, trace_id, status]
      example:
        schema_version: "2.0"
        event_id: 11111111-1111-4111-8111-111111111111
        ts_start: "2026-05-04T10:00:00Z"
        ts_end: "2026-05-04T10:00:00.042Z"
        duration_ms: 42
        kind: http
        service: checkout
        env: demo
        version: local
        trace_id: 7f3a2b9c000000000000000000000001
        span_id: 0000000000000001
        status: error
        anchor:
          step: payment.charge
          error_code: PMT_502
          kind: downstream
        steps:
          - name: cart.validate
            start_ms: 0
            duration_ms: 1
            status: ok
          - name: db.load_cart
            start_ms: 1
            duration_ms: 4
            status: ok
            downstream:
              service: db
              endpoint: /cart/X1
              kind: http
          - name: inventory.reserve
            start_ms: 5
            duration_ms: 2
            status: ok
          - name: payment.charge
            start_ms: 7
            duration_ms: 35
            status: error
            downstream:
              service: payment
              endpoint: /charge
              kind: http
            error:
              code: PMT_502
              reason: upstream gateway 5xx
        logs:
          - ts_offset_ms: 5
            level: info
            msg: inventory reserved
          - ts_offset_ms: 41
            level: error
            msg: upstream gateway 5xx
        fields:
          demo:
            scenario: payment_502
            sku: X1
        errors:
          - code: PMT_502
            reason: upstream gateway 5xx
      properties:
        schema_version:
          type: string
          enum: ["2.0"]
        event_id:
          type: string
          format: uuid
        ts_start:
          type: string
          format: date-time
        ts_end:
          type: string
          format: date-time
        duration_ms:
          type: integer
          minimum: 0
        kind:
          type: string
          enum: [http]
        service:
          type: string
        env:
          type: string
        version:
          type: string
        trace_id:
          type: string
          pattern: '^[0-9a-f]{32}$'
        span_id:
          type: string
          pattern: '^([0-9a-f]{16})?$'
        parent_span_id:
          type: string
          pattern: '^([0-9a-f]{16})?$'
        status:
          type: string
          enum: [ok, error, timeout, partial, aborted, suppressed]
        anchor:
          $ref: '#/components/schemas/Anchor'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/EventStep'
        logs:
          type: array
          items:
            $ref: '#/components/schemas/EventLog'
        fields:
          type: object
          additionalProperties: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorRef'

    Signal:
      type: object
      additionalProperties: true
      required: [type, source, service, env, severity, reason, timestamp]
      example:
        type: deploy
        source: github-actions
        service: checkout
        env: prod
        severity: info
        reason: RolloutComplete
        message: checkout 1.18.2 rolled out
        metadata:
          deployment_id: deploy_123
          version: 1.18.2
        timestamp: "2026-05-02T18:09:40Z"
      properties:
        signal_id:
          type: string
          readOnly: true
          description: Server-generated signal id with sig_ prefix.
        type:
          type: string
          enum: [deploy, runtime, healthcheck, dependency, config, alert]
        source:
          type: string
        service:
          type: string
        env:
          type: string
        severity:
          type: string
          enum: [info, warning, critical]
        reason:
          type: string
        message:
          type: string
        resource:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        timestamp:
          type: string
          format: date-time
        received_at:
          type: string
          format: date-time
          readOnly: true

    SignalAccepted:
      type: object
      required: [signal]
      properties:
        signal:
          $ref: '#/components/schemas/Signal'

    DeploymentRequest:
      type: object
      required: [id, service, env]
      example:
        id: deploy_482
        service: payment-service
        env: prod
        version: v1.4.2
        commit_sha: a1b2c3d
        pr_url: https://github.com/org/repo/pull/482
        commit_author: alice
      properties:
        id:
          type: string
          description: Caller-supplied deployment id (idempotency key).
        service:
          type: string
        env:
          type: string
        version:
          type: string
        metadata:
          type: object
          additionalProperties: {type: string}
        commit_sha:
          type: string
          description: Optional, opaque commit hash pushed by CI at deploy time.
        pr_url:
          type: string
          description: Optional full PR/MR URL (vendor-neutral; GitHub/GitLab/Bitbucket).
        commit_author:
          type: string
          description: Optional commit/PR author.

    Deployment:
      type: object
      required: [id, service, env, first_seen, last_seen]
      properties:
        id: {type: string}
        service: {type: string}
        version: {type: string}
        env: {type: string}
        first_seen: {type: string, format: date-time}
        last_seen: {type: string, format: date-time}
        metadata:
          type: object
          additionalProperties: {type: string}
        commit_sha: {type: string}
        pr_url: {type: string}
        commit_author: {type: string}
        before_requests: {type: integer}
        after_requests: {type: integer}
        before_error_rate: {type: number, nullable: true}
        after_error_rate: {type: number, nullable: true}
        error_rate_change:
          type: number
          nullable: true
          description: after/before failure-ratio multiplier; null below the sample threshold.

    Anchor:
      type: object
      required: [step, error_code]
      properties:
        step:
          type: string
        error_code:
          type: string
        kind:
          type: string

    EventStep:
      type: object
      required: [name, start_ms, duration_ms, status]
      properties:
        name:
          type: string
        span_id:
          type: string
        start_ms:
          type: integer
          minimum: 0
        duration_ms:
          type: integer
          minimum: 0
        status:
          type: string
          enum: [ok, error]
        downstream:
          $ref: '#/components/schemas/Downstream'
        error:
          type: object
          properties:
            code:
              type: string
            reason:
              type: string
            cause:
              type: string

    Downstream:
      type: object
      properties:
        service:
          type: string
        endpoint:
          type: string
        kind:
          type: string

    EventLog:
      type: object
      required: [ts_offset_ms, level, msg]
      properties:
        ts_offset_ms:
          type: integer
          minimum: 0
        level:
          type: string
          enum: [info, warn, error]
        msg:
          type: string
        fields:
          type: object
          additionalProperties: true

    ErrorRef:
      type: object
      required: [code]
      properties:
        code:
          type: string
        reason:
          type: string

    EventGetResponse:
      type: object
      required: [event]
      properties:
        event:
          $ref: '#/components/schemas/WideEvent'

    EventSearchResponse:
      type: object
      required: [events]
      example:
        events:
          - schema_version: "2.0"
            event_id: 11111111-1111-4111-8111-111111111111
            ts_start: "2026-05-04T10:00:00Z"
            ts_end: "2026-05-04T10:00:00.042Z"
            kind: http
            service: checkout
            env: demo
            trace_id: 7f3a2b9c000000000000000000000001
            status: error
        next_cursor: cur_01
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/WideEvent'
        next_cursor:
          type: string
          nullable: true

    TraceGetResponse:
      type: object
      required: [trace_id, events, linkage]
      example:
        trace_id: 7f3a2b9c000000000000000000000001
        events: []
        linkage: causal
      properties:
        trace_id:
          type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/WideEvent'
        linkage:
          type: string
          enum: [causal, timestamp_fallback, direct]

    TraceSummary:
      type: object
      required: [trace_id, ts_start, duration_ms, services, status]
      properties:
        trace_id:
          type: string
        ts_start:
          type: string
          format: date-time
        duration_ms:
          type: integer
        services:
          type: array
          items:
            type: string
        status:
          type: string
          enum: [ok, error, timeout, partial, aborted, suppressed]
        anchor_summary:
          type: string
          nullable: true

    RecentTracesResponse:
      type: object
      required: [traces]
      example:
        traces:
          - trace_id: 7f3a2b9c000000000000000000000001
            ts_start: "2026-05-04T10:00:00Z"
            duration_ms: 42
            services: [api-gateway, checkout, payment]
            status: error
            anchor_summary: checkout:payment.charge:PMT_502
        next_cursor: cur_01
      properties:
        traces:
          type: array
          items:
            $ref: '#/components/schemas/TraceSummary'
        next_cursor:
          type: string
          nullable: true

    StoryResponse:
      type: object
      required: [trace_id, service, route, status, path, logs, downstream, linkage]
      example:
        trace_id: 7f3a2b9c000000000000000000000001
        service: checkout
        route: /purchase
        status: error
        anchor:
          step: payment.charge
          error_code: PMT_502
        path:
          - name: cart.validate
            start_ms: 0
            duration_ms: 1
            status: ok
          - name: db.load_cart
            start_ms: 1
            duration_ms: 4
            status: ok
          - name: inventory.reserve
            start_ms: 5
            duration_ms: 2
            status: ok
          - name: payment.charge
            start_ms: 7
            duration_ms: 35
            status: error
            error_code: PMT_502
            error_msg: upstream gateway 5xx
        logs:
          - ts_offset_ms: 5
            level: info
            msg: inventory reserved
            step: inventory.reserve
          - ts_offset_ms: 41
            level: error
            msg: upstream gateway 5xx
            step: payment.charge
        downstream:
          - step: db.load_cart
            service: db
            endpoint: /cart/X1
          - step: payment.charge
            service: payment
            endpoint: /charge
        linkage: causal
      properties:
        trace_id:
          type: string
        service:
          type: string
        route:
          type: string
        status:
          type: string
          enum: [ok, error, timeout, partial, aborted, suppressed]
        anchor:
          $ref: '#/components/schemas/StoryAnchor'
        path:
          type: array
          items:
            $ref: '#/components/schemas/StoryStep'
        logs:
          type: array
          items:
            $ref: '#/components/schemas/StoryLog'
        downstream:
          type: array
          items:
            $ref: '#/components/schemas/StoryDownstream'
        linkage:
          type: string
          enum: [causal, timestamp_fallback, direct]

    StoryAnchor:
      type: object
      required: [step, error_code]
      properties:
        step:
          type: string
        error_code:
          type: string

    StoryStep:
      type: object
      required: [name, start_ms, duration_ms, status]
      properties:
        name:
          type: string
        start_ms:
          type: integer
        duration_ms:
          type: integer
        status:
          type: string
          enum: [ok, error]
        error_code:
          type: string
        error_msg:
          type: string

    StoryLog:
      type: object
      required: [ts_offset_ms, level, msg]
      properties:
        ts_offset_ms:
          type: integer
        level:
          type: string
          enum: [info, warn, error]
        msg:
          type: string
        step:
          type: string

    StoryDownstream:
      type: object
      required: [step, service]
      properties:
        step:
          type: string
        service:
          type: string
        endpoint:
          type: string

    ErrorFamily:
      type: object
      required: [service, step, error_code]
      properties:
        service:
          type: string
        step:
          type: string
        error_code:
          type: string

    ErrorRow:
      type: object
      required: [error_family, count, affected_traces, sample_traces]
      properties:
        error_family:
          $ref: '#/components/schemas/ErrorFamily'
        count:
          type: integer
        affected_users:
          type: integer
          nullable: true
        affected_traces:
          type: integer
        sample_traces:
          type: array
          items:
            type: string

    ErrorsResponse:
      type: object
      required: [window, rows]
      example:
        window: 15m
        rows:
          - error_family:
              service: checkout
              step: payment.charge
              error_code: PMT_502
            count: 12
            affected_users: 8
            affected_traces: 12
            sample_traces:
              - 7f3a2b9c000000000000000000000001
        next_cursor: null
      properties:
        window:
          type: string
        rows:
          type: array
          items:
            $ref: '#/components/schemas/ErrorRow'
        next_cursor:
          type: string
          nullable: true

    BlastKey:
      type: object
      required: [error_code]
      properties:
        service:
          type: string
        step:
          type: string
        error_code:
          type: string

    BlastRadiusResponse:
      type: object
      required: [key, view_mode, window, affected_requests, affected_services, top_services, sample_traces]
      example:
        key:
          service: checkout
          step: payment.charge
          error_code: PMT_502
        view_mode: single_family
        window: 15m
        affected_requests: 12
        affected_users: 8
        affected_services: 3
        top_services: [api-gateway, checkout, payment]
        sample_traces:
          - 7f3a2b9c000000000000000000000001
      properties:
        key:
          $ref: '#/components/schemas/BlastKey'
        view_mode:
          type: string
          enum: [single_family, cross_family]
        window:
          type: string
        affected_requests:
          type: integer
        affected_users:
          type: integer
          nullable: true
        affected_services:
          type: integer
        top_services:
          type: array
          items:
            type: string
        sample_traces:
          type: array
          items:
            type: string

    IncidentEvidence:
      type: object
      required: [kind, title, occurred_at]
      properties:
        kind:
          type: string
          enum: [signal, deployment, trace, metric]
        title:
          type: string
        detail:
          type: string
        service:
          type: string
        signal_id:
          type: string
        deployment_id:
          type: string
        trace_id:
          type: string
        occurred_at:
          type: string
          format: date-time
        fields:
          type: object
          additionalProperties: true

    Incident:
      type: object
      required:
        - incident_id
        - env
        - service
        - error_family
        - status
        - cause
        - confidence
        - severity
        - started_at
        - updated_at
        - last_seen_at
        - affected_requests
        - affected_services
        - top_services
        - sample_traces
        - evidence
        - next_checks
        - lift
        - baseline_count
        - current_count
      example:
        incident_id: inc_7d0b0b3d5a52d891
        env: prod
        service: checkout
        error_family:
          service: checkout
          step: payment.charge
          error_code: PMT_502
        status: active
        cause: dependency
        confidence: medium
        severity: 8
        started_at: '2026-05-04T16:00:00Z'
        updated_at: '2026-05-04T16:02:00Z'
        last_seen_at: '2026-05-04T16:02:00Z'
        affected_requests: 12
        affected_users: 8
        affected_services: 3
        top_services: [api-gateway, checkout, payment]
        sample_traces: [7f3a2b9c000000000000000000000001]
        evidence:
          - kind: trace
            title: First failing trace sample
            detail: payment.charge/PMT_502
            service: checkout
            trace_id: 7f3a2b9c000000000000000000000001
            occurred_at: '2026-05-04T16:00:00Z'
        next_checks:
          - Check the downstream service health and recent deploys.
        lift: 6
        baseline_count: 2
        current_count: 12
      properties:
        incident_id:
          type: string
        env:
          type: string
        service:
          type: string
        error_family:
          $ref: '#/components/schemas/ErrorFamily'
        status:
          type: string
          enum: [active, recovering, resolved]
        cause:
          type: string
          enum: [deploy, app, dependency, unknown]
        confidence:
          type: string
          enum: [high, medium, low]
        severity:
          type: integer
          minimum: 1
          maximum: 10
        started_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        last_seen_at:
          type: string
          format: date-time
        recovering_at:
          type: string
          format: date-time
          nullable: true
        resolved_at:
          type: string
          format: date-time
          nullable: true
        affected_requests:
          type: integer
        affected_users:
          type: integer
          nullable: true
        affected_services:
          type: integer
        top_services:
          type: array
          items:
            type: string
        sample_traces:
          type: array
          items:
            type: string
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/IncidentEvidence'
        next_checks:
          type: array
          items:
            type: string
        instrumentation_warnings:
          type: array
          items:
            type: string
        lift:
          type: number
          format: double
        baseline_count:
          type: integer
        current_count:
          type: integer

    IncidentListResponse:
      type: object
      required: [incidents]
      properties:
        incidents:
          type: array
          items:
            $ref: '#/components/schemas/Incident'

    IncidentDetailResponse:
      type: object
      required: [incident]
      properties:
        incident:
          $ref: '#/components/schemas/Incident'

    IncidentSnapshotResponse:
      type: object
      required: [snapshot, incident]
      properties:
        snapshot:
          type: string
        incident:
          $ref: '#/components/schemas/Incident'

    TriageReport:
      type: object
      required: [schema_version, incident_ref, blast_snapshot, confidence, generated_at, report_hash]
      description: |
        Deterministic triage artifact for an open incident. Versioned via
        schema_version. report_hash is sha256 over the canonical JSON
        excluding generated_at, plan_run_id, and report_hash itself.
      properties:
        schema_version:
          type: string
          enum: ["triage.v1"]
        incident_ref:
          type: object
          required: [id]
          properties:
            id: {type: string}
            window: {type: string, description: "Go duration string e.g. 15m0s"}
        blast_snapshot:
          type: object
          properties:
            requests: {type: integer}
            users: {type: integer}
            services: {type: integer}
            top_error_families:
              type: array
              items:
                type: object
                properties:
                  service: {type: string}
                  step: {type: string}
                  error_code: {type: string}
                  count: {type: integer}
        first_failure:
          type: object
          additionalProperties: true
          description: Full /v1/traces/story payload for the first observed failing step.
        sample_traces:
          type: array
          items:
            type: object
            properties:
              trace_id: {type: string}
              summary: {type: string}
        signals:
          type: array
          items:
            type: object
            properties:
              id: {type: string}
              type: {type: string}
              evidence_ids: {type: array, items: {type: string}}
        alerts:
          type: array
          description: Alert signals linked to this incident and cited by operator reports.
          items:
            type: object
            properties:
              signal_id: {type: string}
              alert_id: {type: string}
              source: {type: string, enum: [waylog, alertmanager, grafana, pagerduty]}
              severity: {type: string}
              reason: {type: string}
              provider_url: {type: string}
              evidence_ids:
                type: array
                items: {type: string}
        next_checks:
          type: array
          items:
            type: object
            properties:
              id: {type: string}
              prompt: {type: string}
        confidence:
          type: string
          enum: [low, medium, high]
        generated_at: {type: string}
        plan_run_id:
          type: string
          description: Reserved for future plan-produced reports; omitted by the M1.5 triage template.
        report_hash:
          type: string
          description: "sha256:<hex>"

    PlanResult:
      type: object
      required: [plan_id, steps, completed, total, status]
      properties:
        plan_id: {type: string}
        steps:
          type: array
          items:
            type: object
            required: [id, index, tool, duration_ms]
            properties:
              id: {type: string}
              index: {type: integer}
              tool: {type: string}
              result:
                description: Tool output. For the triage template this is a TriageReport.
                oneOf:
                  - $ref: '#/components/schemas/TriageReport'
                  - type: object
                    additionalProperties: true
              error:
                type: object
                nullable: true
                properties:
                  code: {type: string}
                  message: {type: string}
                  retryable: {type: boolean}
              duration_ms: {type: integer}
        completed: {type: integer}
        total: {type: integer}
        status:
          type: string
          enum: [complete, partial, failed]
        halted_at:
          type: integer
          nullable: true
        error:
          type: object
          nullable: true
          properties:
            code: {type: string}
            message: {type: string}
            retryable: {type: boolean}

    CapabilitiesResponse:
      type: object
      example:
        otlp:
          http_traces: true
          grpc_traces: true
          grpc_addr: ":4317"
        v2_reads:
          enabled: true
        graph: false
      properties:
        ask:
          type: object
          additionalProperties: true
        llm:
          type: object
          description: Provider-neutral Ask configuration and runtime state.
          properties:
            provider:
              type: string
              description: Resolved Ask provider. `custom` is used for injected providers.
              enum: [none, gemini, anthropic, openai, custom]
            model:
              type: string
              description: Resolved model for the selected provider, or empty when Ask is disabled.
            tool_mode:
              type: string
              description: Resolved tool-calling mode for the selected provider, or empty when Ask is disabled.
            configured:
              type: boolean
              description: True when a provider was explicitly selected or inferred from credentials.
            ask_enabled:
              type: boolean
              description: True when Ask has a provider implementation available.
        dashboard:
          type: object
          additionalProperties: true
        links:
          type: object
          additionalProperties: true
        graph:
          type: boolean
        otlp:
          type: object
          properties:
            http_traces:
              type: boolean
            grpc_traces:
              type: boolean
            grpc_addr:
              type: string
        v2_reads:
          type: object
          properties:
            enabled:
              type: boolean
        incidents:
          type: object
          properties:
            enabled:
              type: boolean
            persistent:
              type: boolean
            rebuild:
              type: object
              properties:
                supported:
                  type: boolean
                scope:
                  type: string
                  enum: ["", hot-window]
        architecture:
          type: object
          additionalProperties: true