Accept Drift API

openapi: 3.1.0
info:
  title: MIDAS Agents Drift API
  version: 1.1.0-rc.1
  description: 'Authority governance engine for autonomous decisions. Every evaluation produces exactly one outcome and one tamper-evident audit envelope.

    '
servers:
- url: http://localhost:8080
  description: Local development
security:
- BearerAuth: []
tags:
- name: Drift
paths:
  /v1/drift/analytics:
    get:
      operationId: getDriftAnalytics
      summary: Get node-scoped Drift Analytics read model data
      parameters:
      - name: node_kind
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/DriftTargetEntityKind'
      - name: node_id
        in: query
        required: true
        schema:
          type: string
      - name: range
        in: query
        required: false
        schema:
          type: string
          default: 30d
      responses:
        '200':
          description: Node-scoped drift analytics read model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftAnalyticsResponse'
        '400':
          description: Invalid node selector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift analytics reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/definitions/{id}:
    get:
      operationId: getDriftDefinition
      summary: Get the latest version of a DriftDefinition by ID
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Drift definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftDefinition'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Drift definition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift definition reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/definitions/{id}/versions:
    get:
      operationId: listDriftDefinitionVersions
      summary: List all versions of a DriftDefinition
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Versions list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftDefinitionListResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Drift definition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift definition reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/definitions/{id}/versions/{version}:
    get:
      operationId: getDriftDefinitionVersion
      summary: Get a specific DriftDefinition revision
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: Drift definition version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftDefinition'
        '400':
          description: Version path segment is not a positive integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Drift definition or version not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift definition reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/definitions/{id}/series:
    get:
      operationId: listDriftSeriesByDefinition
      summary: List DriftSeries for a DriftDefinition
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Series list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftSeriesListResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift series reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/definitions/{id}/observations:
    get:
      operationId: listDriftObservationsByDefinition
      summary: List DriftObservations for a DriftDefinition
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Observations list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftObservationListResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift observation reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/series/{id}:
    get:
      operationId: getDriftSeries
      summary: Get a DriftSeries by ID
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Drift series
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftSeries'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Drift series not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift series reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/series/{id}/points:
    get:
      operationId: listDriftSeriesPoints
      summary: List DriftSeriesPoints for a series
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: from_window
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Inclusive lower bound on window_start; RFC3339.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
      responses:
        '200':
          description: Points list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftSeriesPointListResponse'
        '400':
          description: Invalid query parameter (limit out of range or from_window not RFC3339)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift series point reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/series/{id}/observations:
    get:
      operationId: listDriftObservationsBySeries
      summary: List DriftObservations for a series
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Observations list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftObservationListResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift observation reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/series/{id}/annotations:
    get:
      operationId: listDriftAnnotationsBySeries
      summary: List DriftAnnotations attached to a series
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Annotations list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftAnnotationListResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift annotation reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/series-points/{id}:
    get:
      operationId: getDriftSeriesPoint
      summary: Get a DriftSeriesPoint by ID
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Drift series point
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftSeriesPoint'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Drift series point not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift series point reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/observations/{id}:
    get:
      operationId: getDriftObservation
      summary: Get a DriftObservation by ID
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Drift observation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftObservation'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Drift observation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift observation reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/observations/{id}/annotations:
    get:
      operationId: listDriftAnnotationsByObservation
      summary: List DriftAnnotations attached to an observation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Annotations list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftAnnotationListResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift annotation reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/annotations/{id}:
    get:
      operationId: getDriftAnnotation
      summary: Get a DriftAnnotation by ID
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Drift annotation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftAnnotation'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Drift annotation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift annotation reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
  /v1/drift/entities/{kind}/{entity_id}/observations:
    get:
      operationId: listDriftObservationsByEntity
      summary: List DriftObservations for a governed entity target
      parameters:
      - name: kind
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/DriftTargetEntityKind'
      - name: entity_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Observations list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftObservationListResponse'
        '400':
          description: Invalid target entity kind
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role (requires platform.viewer or above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Repository error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Drift observation reader not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Drift
components:
  schemas:
    DriftThresholdDirection:
      type: string
      enum:
      - ascending
      - descending
    DriftAnalyticsObservedPoint:
      type: object
      required:
      - t
      - value
      properties:
        t:
          type: string
          format: date-time
        value:
          type: number
          format: double
        status:
          type: string
        magnitude:
          type: number
          format: double
    DriftPointComputationMode:
      type: string
      description: 'Computation provenance for a series point. Backfill state lives on this enum; it is not encoded on detector_status.

        '
      enum:
      - realtime
      - backfilled
      - corrected
      - imported
    DriftAnalyticsResponse:
      type: object
      required:
      - node
      - range
      - chart
      - provenance
      - sourceClassification
      - dataAvailable
      properties:
        node:
          type: object
          required:
          - kind
          - id
          properties:
            kind:
              $ref: '#/components/schemas/DriftTargetEntityKind'
            id:
              type: string
        range:
          type: object
          required:
          - key
          - label
          properties:
            key:
              type: string
            label:
              type: string
            from:
              type: string
              format: date-time
            to:
              type: string
              format: date-time
        chart:
          type: object
          required:
          - observed
          - expected
          - watch
          - breach
          - yDomain
          properties:
            metricId:
              type: string
            driftType:
              $ref: '#/components/schemas/DriftType'
            seriesId:
              type: string
            observed:
              type: array
              items:
                $ref: '#/components/schemas/DriftAnalyticsObservedPoint'
            expected:
              type: array
              items:
                $ref: '#/components/schemas/DriftAnalyticsPoint'
            watch:
              type: array
              items:
                $ref: '#/components/schemas/DriftAnalyticsPoint'
            breach:
              type: array
              items:
                $ref: '#/components/schemas/DriftAnalyticsPoint'
            currentValue:
              type: number
              format: double
            currentStatus:
              type: string
            yDomain:
              type: object
              required:
              - min
              - max
              properties:
                min:
                  type: number
                  format: double
                max:
                  type: number
                  format: double
        provenance:
          type: object
          required:
          - envelopeIds
          - pointIds
          - observationIds
          - annotationIds
          - profileRefs
          - policyRefs
          - verificationStatus
          properties:
            envelopeIds:
              type: array
              items:
                type: string
            pointIds:
              type: array
              items:
                type: string
            observationIds:
              type: array
              items:
                type: string
            annotationIds:
              type: array
              items:
                type: string
            profileRefs:
              type: array
              items:
                type: string
            policyRefs:
              type: array
              items:
                type: string
            verificationStatus:
              type: string
              enum:
              - not_requested
              - not_verified
        sourceClassification:
          type: object
          required:
          - selectedNode
          - observedSeries
          - expectedBaseline
          - thresholds
          - status
          - provenance
          - compositeScore
          - contributionValues
          - contributionWeights
          - graphOverlay
          properties:
            selectedNode:
              type: string
              enum:
              - backend
            observedSeries:
              type: string
              enum:
              - backend
              - unavailable
            expectedBaseline:
              type: string
              enum:
              - backend
              - unavailable
            thresholds:
              type: string
              enum:
              - backend
              - unavailable
            status:
              type: string
              enum:
              - backend
              - unavailable
            provenance:
              type: string
              enum:
              - backend_refs
              - not_available
            compositeScore:
              type: string
              enum:
              - not_available
            contributionValues:
              type: string
              enum:
              - not_available
            contributionWeights:
              type: string
              enum:
              - not_available
            graphOverlay:
              type: string
              enum:
              - not_implemented
        projectionAsOf:
          type: string
          format: date-time
        dataAvailable:
          type: boolean
    DriftDefinitionListResponse:
      type: object
      required:
      - drift_definitions
      properties:
        drift_definitions:
          type: array
          items:
            $ref: '#/components/schemas/DriftDefinition'
    DriftBaselineStrategy:
      type: string
      description: 'V1 baseline strategies. champion_challenger and seasonality_aware are deferred to V2 and MUST NOT appear here.

        '
      enum:
      - rolling
      - fixed_governed
      - previous_equivalent
      - since_last_governed_change
      - manually_pinned
    DriftOrigin:
      type: string
      enum:
      - manual
      - inferred
      - auto_instrumented
    DriftObservationListResponse:
      type: object
      required:
      - drift_observations
      properties:
        drift_observations:
          type: array
          items:
            $ref: '#/components/schemas/DriftObservation'
    DriftAnnotationStatus:
      type: string
      enum:
      - active
      - superseded
    DriftAnalyticsPoint:
      type: object
      required:
      - t
      - value
      properties:
        t:
          type: string
          format: date-time
        value:
          type: number
          format: double
    DriftSeries:
      type: object
      description: One time-ordered stream for a (definition revision, metric, cadence) tuple.
      required:
      - id
      - definition_id
      - definition_version
      - metric_id
      - cadence
      - status
      - continuity_group_id
      - created_at
      - updated_at
      properties:
        id:
          type: string
        definition_id:
          type: string
        definition_version:
          type: integer
          minimum: 1
        metric_id:
          type: string
        cadence:
          $ref: '#/components/schemas/DriftCadence'
        status:
          $ref: '#/components/schemas/DriftStatusBand'
        continuity_group_id:
          type: string
        previous_series_id:
          type: string
        superseded_by_series_id:
          type: string
        cutover_at:
          type: string
          format: date-time
          nullable: true
        sealed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DriftCadence:
      type: string
      enum:
      - minute
      - hour
      - day
      - week
    DriftAnnotationTargetRef:
      type: object
      required:
      - kind
      - id
      properties:
        kind:
          $ref: '#/components/schemas/DriftAnnotationTargetKind'
        id:
          type: string
    DriftAnnotation:
      type: object
      description: Operator commentary against a series or observation.
      required:
      - id
      - target
      - annotation_type
      - body
      - reference_envelope_ids
      - status
      - author_id
      - created_at
      - updated_at
      properties:
        id:
          type: string
        target:
          $ref: '#/components/schemas/DriftAnnotationTargetRef'
        annotation_type:
          $ref: '#/components/schemas/DriftAnnotationType'
        body:
          type: string
        suppression_until:
          type: string
          format: date-time
          nullable: true
        reference_envelope_ids:
          type: array
          items:
            type: string
        status:
          $ref: '#/components/schemas/DriftAnnotationStatus'
        superseded_by_id:
          type: string
        author_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DriftAnnotationListResponse:
      type: object
      required:
      - drift_annotations
      properties:
        drift_annotations:
          type: array
          items:
            $ref: '#/components/schemas/DriftAnnotation'
    LifecycleStatus:
      type: string
      description: 'Canonical lifecycle posture for versioned governance resources (Surface, Profile, FailModePolicy, EscalationTarget). Every governed configuration entity in MIDAS follows the same draft -> review -> active -> deprecated -> retired progression. Only `active` versions participate in runtime resolution.

        '
      enum:
      - draft
      - review
      - active
      - deprecated
      - retired
    DriftAnnotationType:
      type: string
      enum:
      - known_business_change
      - suppression
      - remediation_note
      - acknowledgement
    DriftMetricDefinition:
      type: object
      description: Embedded metric inside a DriftDefinition revision.
      required:
      - metric_id
      - drift_type
      - baseline_strategy
      - window_seconds
      - cadence
      - threshold_direction
      - warning_threshold
      - breached_threshold
      properties:
        metric_id:
          type: string
        drift_type:
          $ref: '#/components/schemas/DriftType'
        baseline_strategy:
          $ref: '#/components/sch

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/accept/refs/heads/main/openapi/accept-drift-api-openapi.yml