Accept Controlplane API

openapi: 3.1.0
info:
  title: MIDAS Agents Controlplane 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: Controlplane
paths:
  /v1/controlplane/apply:
    post:
      operationId: applyBundle
      summary: Apply a control-plane configuration bundle
      description: 'Applies a YAML bundle of surface, profile, grant, and agent documents. All resources in the bundle are validated before any are persisted. Surfaces are created in review state and must be approved separately. Requires platform.admin role.

        '
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              type: string
              description: 'Multi-document YAML stream of control-plane resources. Profile spec.authority.consequence_threshold.type accepts monetary (canonical amount/currency threshold), financial (compatibility alias persisted as the Postgres storage value), or risk_rating.

                '
      responses:
        '200':
          description: Bundle applied (may contain per-resource validation errors)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  created:
                    type: integer
                  updated:
                    type: integer
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        kind:
                          type: string
                        id:
                          type: string
                        field:
                          type: string
                        message:
                          type: string
        '400':
          description: Invalid YAML or bundle-level validation failure
          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.admin)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/plan:
    post:
      operationId: planBundle
      summary: Preview a control-plane bundle without applying it
      description: 'Validates and plans a YAML bundle, returning the projected changes without persisting anything. Useful for CI/CD dry-run workflows. Requires platform.admin role.

        '
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              type: string
              description: 'Multi-document YAML stream of control-plane resources. Profile spec.authority.consequence_threshold.type accepts monetary (canonical amount/currency threshold), financial (compatibility alias persisted as the Postgres storage value), or risk_rating.

                '
      responses:
        '200':
          description: Plan computed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  planned:
                    type: integer
                  errors:
                    type: array
                    items:
                      type: object
        '400':
          description: Invalid YAML
          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.admin)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/audit:
    get:
      operationId: listControlAudit
      summary: List control-plane audit events
      description: Returns the audit trail of control-plane operations (apply, approve, deprecate).
      responses:
        '200':
          description: Audit event list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    event_type:
                      type: string
                    resource_kind:
                      type: string
                    resource_id:
                      type: string
                    actor:
                      type: string
                    occurred_at:
                      type: string
                      format: date-time
        '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'
      tags:
      - Controlplane
  /v1/controlplane/surfaces/{id}/approve:
    post:
      operationId: approveSurface
      summary: Approve a surface in review state
      description: 'Transitions a surface from review to active. Enforces maker-checker: the approver must not be the same principal who submitted the surface. Requires platform.admin or governance.approver role.

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveSurfaceRequest'
      responses:
        '200':
          description: Surface approved
          content:
            application/json:
              schema:
                type: object
                required:
                - surface_id
                - status
                - approved_by
                properties:
                  surface_id:
                    type: string
                  status:
                    type: string
                    example: active
                  approved_by:
                    type: string
        '400':
          description: Invalid request or approval policy violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role or approval policy denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Surface not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Surface is not in review state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/surfaces/{id}/deprecate:
    post:
      operationId: deprecateSurface
      summary: Deprecate an active surface
      description: 'Transitions a surface from active to deprecated. Deprecated surfaces remain usable for existing grants but signal pending migration. Requires platform.admin role.

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeprecateSurfaceRequest'
      responses:
        '200':
          description: Surface deprecated
          content:
            application/json:
              schema:
                type: object
                properties:
                  surface_id:
                    type: string
                  status:
                    type: string
                    example: deprecated
                  deprecation_reason:
                    type: string
                  successor_surface_id:
                    type: string
        '400':
          description: Invalid request
          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.admin)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Surface not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/profiles/{id}/approve:
    post:
      operationId: approveProfile
      summary: Approve a profile version in review state
      description: 'Transitions a specific profile version from review to active. Requires platform.admin or governance.approver role.

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveProfileRequest'
      responses:
        '200':
          description: Profile approved
          content:
            application/json:
              schema:
                type: object
                required:
                - profile_id
                - version
                - status
                - approved_by
                properties:
                  profile_id:
                    type: string
                  version:
                    type: integer
                  status:
                    type: string
                  approved_by:
                    type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Profile not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/expectations/{id}/approve:
    post:
      operationId: approveGovernanceExpectation
      summary: Approve a GovernanceExpectation version in review state
      description: 'Transitions a specific GovernanceExpectation version from review to active. After approval the matcher (#53) considers the expectation when emitting GOVERNANCE_CONDITION_DETECTED runtime audit events. Requires platform.admin or governance.approver role.

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveGovernanceExpectationRequest'
      responses:
        '200':
          description: GovernanceExpectation approved
          content:
            application/json:
              schema:
                type: object
                required:
                - expectation_id
                - version
                - status
                - approved_by
                properties:
                  expectation_id:
                    type: string
                  version:
                    type: integer
                  status:
                    type: string
                  approved_by:
                    type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: GovernanceExpectation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Expectation is not in review state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/profiles/{id}/deprecate:
    post:
      operationId: deprecateProfile
      summary: Deprecate a profile version
      description: Requires platform.admin role.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeprecateProfileRequest'
      responses:
        '200':
          description: Profile deprecated
          content:
            application/json:
              schema:
                type: object
                properties:
                  profile_id:
                    type: string
                  version:
                    type: integer
                  status:
                    type: string
        '400':
          description: Invalid request
          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.admin)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Profile not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/fail_mode_policies/{id}/approve:
    post:
      operationId: approveFailModePolicy
      summary: Approve a FailModePolicy version in review state
      description: 'Transitions a specific FailModePolicy version from review to active. Requires platform.admin or governance.approver role (permission `fail_mode_policy:approve`). Mirrors the AuthorityProfile approval lifecycle.

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveFailModePolicyRequest'
      responses:
        '200':
          description: FailModePolicy approved
          content:
            application/json:
              schema:
                type: object
                required:
                - policy_id
                - version
                - status
                - approved_by
                properties:
                  policy_id:
                    type: string
                  version:
                    type: integer
                  status:
                    type: string
                  approved_by:
                    type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permission (requires fail_mode_policy:approve)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: FailModePolicy not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: FailModePolicy is not in review state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/fail_mode_policies/{id}/deprecate:
    post:
      operationId: deprecateFailModePolicy
      summary: Deprecate an active FailModePolicy version
      description: 'Transitions a specific FailModePolicy version from active to deprecated. The operator-supplied reason is captured in the control-audit record only — failmode.FailModePolicy has no DeprecationReason field on the persisted row. Requires platform.admin role (permission `fail_mode_policy:deprecate`, admin-only by deliberate maker-checker boundary).

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeprecateFailModePolicyRequest'
      responses:
        '200':
          description: FailModePolicy deprecated
          content:
            application/json:
              schema:
                type: object
                required:
                - policy_id
                - version
                - status
                properties:
                  policy_id:
                    type: string
                  version:
                    type: integer
                  status:
                    type: string
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permission (requires fail_mode_policy:deprecate)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: FailModePolicy not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: FailModePolicy is not in active state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/drift_definitions/{id}/submit:
    post:
      operationId: submitDriftDefinition
      summary: Submit a DriftDefinition revision for review
      description: 'Transitions a specific DriftDefinition revision from draft to review. Requires platform.operator or platform.admin role (permission `drift_definition:submit`).

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitDriftDefinitionRequest'
      responses:
        '200':
          description: DriftDefinition transitioned to review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftDefinition'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permission (requires drift_definition:submit)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: DriftDefinition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: DriftDefinition is not in draft state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Approval service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/drift_definitions/{id}/approve:
    post:
      operationId: approveDriftDefinition
      summary: Approve a DriftDefinition revision in review state
      description: 'Transitions a specific DriftDefinition revision from review to active. Maker-checker is enforced at the service layer: the approver must not equal the revision''s `created_by` field (case-insensitive trim). Requires governance.approver or platform.admin role (permission `drift_definition:approve`).

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveDriftDefinitionRequest'
      responses:
        '200':
          description: DriftDefinition approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftDefinition'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permission or maker-checker violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: DriftDefinition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: DriftDefinition is not in review state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Approval service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/drift_definitions/{id}/reject:
    post:
      operationId: rejectDriftDefinition
      summary: Reject a DriftDefinition revision back to draft
      description: 'Transitions a specific DriftDefinition revision from review back to draft. Approved_by and approved_at are not modified (review-state revisions have neither set). The operator-supplied reason is captured in the control-audit record only. Requires governance.approver or platform.admin role (permission `drift_definition:reject`).

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectDriftDefinitionRequest'
      responses:
        '200':
          description: DriftDefinition transitioned to draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftDefinition'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permission (requires drift_definition:reject)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: DriftDefinition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: DriftDefinition is not in review state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Approval service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/drift_definitions/{id}/deprecate:
    post:
      operationId: deprecateDriftDefinition
      summary: Deprecate an active DriftDefinition revision
      description: 'Transitions a specific DriftDefinition revision from active to deprecated. Successor information is optional; when supplied it is persisted on the row''s `successor_definition_id` and `successor_version` fields. The operator-supplied reason is captured in the control-audit record only. Requires platform.admin role (permission `drift_definition:deprecate`). Cross-version atomic deprecation (auto-deprecate prior active when activating a new revision) is intentionally NOT performed — operators must call this endpoint explicitly.

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeprecateDriftDefinitionRequest'
      responses:
        '200':
          description: DriftDefinition deprecated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftDefinition'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permission (requires drift_definition:deprecate)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: DriftDefinition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: DriftDefinition is not in active state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Approval service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/drift_definitions/{id}/retire:
    post:
      operationId: retireDriftDefinition
      summary: Retire a DriftDefinition revision
      description: 'Transitions a DriftDefinition revision to retired. Allowed source states: draft, review, active, deprecated. Retired is terminal — already-retired revisions are rejected with 409. Requires platform.admin role (permission `drift_definition:retire`).

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetireDriftDefinitionRequest'
      responses:
        '200':
          description: DriftDefinition retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftDefinition'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permission (requires drift_definition:retire)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: DriftDefinition not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: DriftDefinition is already retired (terminal)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Approval service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Controlplane
  /v1/controlplane/grants/{id}/suspend:
    post:
      operationId: suspendGrant
      summary: Suspend an active grant
      description: 'Suspends an active authority grant, preventing the associated agent from being authorized on the linked profile. Reversible via reinstate. Requires platform.admin role.

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - suspended_by
              properties:
                suspended_by:
                  type: string
                reason:
                  type: string
      responses:
        '200':
          description: Grant suspended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantLifecycleResponse'
        '400':
          description: Invalid request
          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.admin)
          content:
            application/json:
              schema:


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