openapi: 3.0.3
info:
  title: MayExecute Governance Gateway API
  version: v2.0.0
  description: Open-source pre-execution governance gateway for AI-enabled actions.
servers:
  - url: https://dev.mayexecute.com
paths:
  /api/check:
    post:
      summary: Generate a full MayExecute governance record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GateRequest'
      responses:
        '200':
          description: Full governance record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceRecord'
  /api/gate:
    post:
      summary: Return an allow/review/block gate response before execution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GateRequest'
      responses:
        '200':
          description: Compact gate response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateResponse'
components:
  schemas:
    GateRequest:
      type: object
      required:
        - action_title
        - proposed_action
        - expected_governed_effect
        - answers
      properties:
        policy_profile:
          type: string
          enum:
            - general
            - agentic_ai
            - public_sector
            - iot
            - robotics
            - finance_procurement
            - customer_comm
            - high_risk
          default: general
        action_title:
          type: string
        system_or_context:
          type: string
        proposed_action:
          type: string
        expected_governed_effect:
          type: string
        evidence_reference:
          type: string
        privacy_mode:
          type: string
          enum:
            - standard
            - hash_only
          default: standard
        answers:
          type: object
          additionalProperties:
            type: string
            enum:
              - yes
              - unclear
              - no
        notes:
          type: object
          additionalProperties:
            type: string
        reviewer_name:
          type: string
        reviewer_role:
          type: string
        reviewer_note:
          type: string
    GateResponse:
      type: object
      properties:
        allowed:
          type: boolean
        classification:
          type: string
          enum:
            - PROCEED
            - REVIEW
            - BLOCK
        risk_level:
          type: string
          enum:
            - LOW
            - MEDIUM
            - HIGH
            - CRITICAL
        risk_score:
          type: number
        reason:
          type: string
        critical_failures:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string
        record_id:
          type: string
        record_hash_sha256:
          type: string
        verify_url:
          type: string
    GovernanceRecord:
      allOf:
        - $ref: '#/components/schemas/GateResponse'
        - type: object
          properties:
            schema:
              type: string
            version:
              type: string
            policy_profile:
              type: object
            conditions:
              type: array
              items:
                type: object
            evidence_pack:
              type: object
            human_review:
              type: object