openapi: 3.1.0
info:
  title: MIDAS Agents Processes 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: Processes
paths:
  /v1/processes:
    get:
      operationId: listProcesses
      summary: List all processes
      description: 'Returns all registered processes. No pagination — returns the full list. Requires platform.viewer or above.

        '
      responses:
        '200':
          description: Process list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Process'
        '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:
      - Processes
  /v1/processes/{id}:
    get:
      operationId: getProcessById
      summary: Get a process by ID
      description: 'Returns a single process by its unique identifier. Requires platform.viewer or above.

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Unique process identifier.
      responses:
        '200':
          description: Process found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '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: Process not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: process not found
      tags:
      - Processes
  /v1/processes/{id}/surfaces:
    get:
      operationId: listSurfacesByProcess
      summary: List surfaces belonging to a process
      description: 'Returns all decision surfaces belonging to the given process. Returns 404 when the parent process does not exist. Returns an empty array when the process exists but has no surfaces. Requires platform.viewer or above.

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Unique process identifier.
      responses:
        '200':
          description: Surface list (may be empty)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Surface'
        '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: Process not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: process not found
      tags:
      - Processes
components:
  schemas:
    Surface:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          $ref: '#/components/schemas/LifecycleStatus'
        version:
          type: integer
        domain:
          type: string
        business_owner:
          type: string
        technical_owner:
          type: string
        effective_from:
          type: string
          format: date-time
        approved_by:
          type: string
        approved_at:
          type: string
          format: date-time
        deprecation_reason:
          type: string
        successor_surface_id:
          type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    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
    Process:
      type: object
      properties:
        id:
          type: string
          description: Unique process identifier.
        name:
          type: string
          description: Human-readable process name.
        capability_id:
          type: string
          description: ID of the parent capability.
        description:
          type: string
          description: Optional description. Omitted when empty.
        status:
          type: string
          enum:
          - active
          - inactive
          - deprecated
        owner:
          type: string
          description: Owner identifier. Omitted when not set.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Static bearer token. Configured via MIDAS_AUTH_TOKENS or midas.yaml auth.tokens. Not required when auth.mode=open (development only).

        '