Accept Drift API

openapi: 3.2.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:
    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
    DriftObservationOperatorStatus:
      type: string
      enum:
      - open
      - triaged
      - resolved
      - accepted
      - superseded
    DriftAnnotationTargetRef:
      type: object
      required:
      - kind
      - id
      properties:
        kind:
          $ref: '#/components/schemas/DriftAnnotationTargetKind'
        id:
          type: string
    DriftTargetRef:
      type: object
      description: Discriminated reference to a governed entity.
      required:
      - kind
      - id
      properties:
        kind:
          $ref: '#/components/schemas/DriftTargetEntityKind'
        id:
          type: string
    DriftAnnotationType:
      type: string
      enum:
      - known_business_change
      - suppression
      - remediation_note
      - acknowledgement
    DriftAnnotationListResponse:
      type: object
      required:
      - drift_annotations
      properties:
        drift_annotations:
          type: array
          items:
            $ref: '#/components/schemas/DriftAnnotation'
    DriftThresholdDirection:
      type: string
      enum:
      - ascending
      - descending
    DriftStatusBand:
      type: string
      description: 'Five-band status used by DriftSeries, DriftSeriesPoint, and DriftObservation.detector_status. The split into unknown_insufficient_data and unknown_detector_error is deliberate; there is no single ''unknown'' value.

        '
      enum:
      - healthy
      - warning
      - breached
      - unknown_insufficient_data
      - unknown_detector_error
    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
    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
    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
    DriftTargetEntityKind:
      type: string
      description: 'The nine governed entity kinds a DriftDefinition may target.

        '
      enum:
      - business_service
      - capability
      - process
      - decision_surface
      - ai_system
      - ai_system_binding
      - agent
      - authority_profile
      - authority_grant
    DriftAnnotationTargetKind:
      type: string
      enum:
      - series
      - observation
    DriftSeriesPoint:
      type: object
      description: 'Append-only window summary. summary_stats and baseline_stats are opaque JSON objects whose internal shape is detector- specific. Backfill state is encoded on computation_mode + backfill_run_id, NOT on status.

        '
      required:
      - id
      - series_id
      - window_start
      - window_end
      - sample_count
      - summary_stats
      - baseline_stats
      - magnitude
      - status
      - computation_mode
      - computed_at
      - source_window_complete
      - provenance_envelope_ids
      - created_at
      properties:
        id:
          type: string
        series_id:
          type: string
        window_start:
          type: string
          format: date-time
        window_end:
          type: string
          format: date-time
        sample_count:
          type: integer
          minimum: 0
        summary_stats:
          type: object
          description: Detector-specific summary stats; opaque object whose internal shape is detector-specific.
          additionalProperties: true
        baseline_stats:
          type: object
          description: Detector-specific baseline stats; opaque object whose internal shape is detector-specific.
          additionalProperties: true
        baseline_window_id:
          type: string
        magnitude:
          type: number
        status:
          $ref: '#/components/schemas/DriftStatusBand'
        computation_mode:
          $ref: '#/components/schemas/DriftPointComputationMode'
        computed_at:
          type: string
          format: date-time
        backfill_run_id:
          type: string
        source_window_complete:
          type: boolean
        provenance_envelope_ids:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
    DriftBaselineStrategy:
      type: string
      description: 'V1 baseline strategies. champion_challenger and seasonality_aware are deferred to V2 and MUST NOT appear here.

        

# --- 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