openapi: 3.0.3
info:
  title: ProofGate API
  version: 0.1.0
  description: Deterministic consequence rails for probabilistic models.
servers:
  - url: https://api.proofgate.dev
paths:
  /v1/health:
    get:
      summary: Health
      responses:
        '200':
          description: OK
  /v1/decide:
    post:
      summary: Decide (policy gate)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntentEnvelope'
      responses:
        '200':
          description: Decision + signed receipt
        '400':
          description: Invalid envelope
  /v1/approve:
    post:
      summary: Approve (for REQUIRE_APPROVAL)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [approvalToken, approverId]
              properties:
                approvalToken: { type: string }
                approverId: { type: string }
      responses:
        '200':
          description: Execution result + signed execution receipt
        '400':
          description: Invalid token/body
        '404':
          description: Token not found
  /v1/execute:
    post:
      summary: Execute (one-call decide→execute or return approval token)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntentEnvelope'
      responses:
        '200':
          description: Decision + receipts (+ execution if allowed)
        '403':
          description: Denied by policy
components:
  schemas:
    IntentEnvelope:
      type: object
      required: [intentId, action, actor, payload]
      properties:
        intentId:
          type: string
          example: intent_00000001
        action:
          type: string
          enum: [email.send]
        actor:
          type: object
          required: [actorId, actorType]
          properties:
            actorId: { type: string, example: bjk }
            actorType: { type: string, enum: [human, model, service] }
        payload:
          type: object
          required: [to, subject, body]
          properties:
            to:
              type: array
              items: { type: string, format: email }
            cc:
              type: array
              items: { type: string, format: email }
            bcc:
              type: array
              items: { type: string, format: email }
            subject:
              type: string
            body:
              type: string
            links:
              type: array
              items: { type: string, format: uri }
        requestedScopes:
          type: array
          items: { type: string }
        meta:
          type: object
          additionalProperties: true
