openapi: 3.1.0
info:
  title: Kevros Governance API
  description: "HTTP governance API for delegated requesters.\n\n## Getting Started\n\n```bash\ncurl -X POST https://governance.taskhawktech.com/signup \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"operator_name\": \"my-org\", \"agent_id\": \"my-agent\"}'\n```\n\nReturns an API key for the trial allowance. No credit card required.\n\n## Payment Options\n\n- **API Key** - trial allowance or operator-provisioned key-backed access.\n- **x402 USDC** - pay per call on Base after `X-API-Key` or verified Delegation proof.\n- **L402 Lightning** - invoice challenge and macaroon retry flow for endpoints that advertise L402.\n- **MPP / fiat** - processor-backed settlement for configured payment-session flows.\n\n## Paid-call discovery sequence\n\n1. `GET /payment/health` - candidate rail challenge configuration.\n2. `GET /payment/quote?endpoint=/governance/verify` - per-endpoint price across candidate rails.\n3. For generic paid agents, fetch a safe-method 402 challenge, then POST with a verified rail credential. Unpaid executable POST remains Delegation-gated.\n\nDiscovery reduces avoidable rail attempts, but it is not settlement, adoption, or revenue evidence.\n\n## Resources\n\n- [Integration contract](/for-agents.txt)\n- [OpenAPI JSON](/openapi.json)\n- [Agent Card](https://governance.taskhawktech.com/.well-known/agent.json)\n- [MCP Server](https://governance.taskhawktech.com/mcp/)\n"
  termsOfService: https://taskhawktech.com/legal/terms
  contact:
    name: TaskHawk Systems
    url: https://taskhawktech.com/contact
    email: support@taskhawktech.com
  license:
    name: TaskHawk Terms
    url: https://taskhawktech.com/legal/terms
  version: 0.4.1
servers:
- url: https://governance.taskhawktech.com
  description: Production Gateway
paths:
  /governance/verify:
    post:
      tags:
      - governance
      summary: Verify Action
      description: 'Verify a proposed action against policy bounds.


        Returns a signed ALLOW, CONSTRAIN, or DENY decision with release token.

        Fail-closed: any verification failure results in DENY.'
      operationId: verify-action
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Delegation-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Delegation-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
      responses:
        '200':
          description: Verification decision with signed release token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
              example:
                decision: ALLOW
                verification_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                release_token: example-release-token-not-a-secret
                applied_action:
                  motor_command:
                    throttle: 0.75
                reason: Action within policy bounds
                epoch: 42
                provenance_hash: abc123...
                hash_prev: 000000...
                timestamp_utc: '2026-03-19T12:00:00+00:00'
                enforcement_mode: enforce
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment challenge metadata. Executable POST requires X-API-Key, verified Delegation proof, or a verified x402, L402, or MPP credential obtained from safe-method payment challenge discovery.
      x-payment-info:
        intent: charge
        method: stripe
        amount: '1'
        currency: usd
        amount_unit: usd_cents
        description: Action verification
        delegation_authorization_required: true
        settlement_signal: false
        revenue_signal: false
  /governance/attest:
    post:
      tags:
      - governance
      summary: Attest Action
      description: 'Create a hash-chained provenance attestation for an agent action.


        Each attestation extends the append-only evidence chain.

        Independently verifiable by any third party.'
      operationId: attest-action
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Delegation-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Delegation-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttestRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment challenge metadata. Executable POST requires X-API-Key, verified Delegation proof, or a verified x402, L402, or MPP credential obtained from safe-method payment challenge discovery.
      x-payment-info:
        intent: charge
        method: stripe
        amount: '2'
        currency: usd
        amount_unit: usd_cents
        description: Provenance attestation
        delegation_authorization_required: true
        settlement_signal: false
        revenue_signal: false
  /governance/bind:
    post:
      tags:
      - governance
      summary: Bind Intent
      description: 'Declare an intent and cryptographically bind it to a command.


        Proves that the command was issued in service of the declared intent.

        The binding HMAC can be independently verified.'
      operationId: bind-intent
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Delegation-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Delegation-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindIntentRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BindIntentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment challenge metadata. Executable POST requires X-API-Key, verified Delegation proof, or a verified x402, L402, or MPP credential obtained from safe-method payment challenge discovery.
      x-payment-info:
        intent: charge
        method: stripe
        amount: '2'
        currency: usd
        amount_unit: usd_cents
        description: Intent binding
        delegation_authorization_required: true
        settlement_signal: false
        revenue_signal: false
  /governance/verify-outcome:
    post:
      tags:
      - governance
      summary: Verify Outcome
      description: 'Verify that an executed action achieved its declared intent.


        Closes the loop: intent -> command -> action -> outcome -> verification.'
      operationId: verify-outcome
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Delegation-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Delegation-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyOutcomeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyOutcomeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
  /governance/bundle:
    post:
      tags:
      - governance
      summary: Generate Bundle
      description: 'Generate a certifier-grade compliance evidence bundle.


        Contains hash-chained provenance records, intent binding proofs,

        PQC attestation references, and verification instructions.


        The bundle is independently verifiable without Kevros access.'
      operationId: generate-bundle
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Delegation-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Delegation-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BundleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment challenge metadata. Executable POST requires X-API-Key, verified Delegation proof, or a verified x402, L402, or MPP credential obtained from safe-method payment challenge discovery.
      x-payment-info:
        intent: charge
        method: stripe
        amount: '5'
        currency: usd
        amount_unit: usd_cents
        description: Compliance bundle
        delegation_authorization_required: true
        settlement_signal: false
        revenue_signal: false
  /media/capabilities:
    get:
      tags:
      - media
      summary: Media Capabilities
      description: Machine-readable media authority capabilities for agent clients.
      operationId: media_capabilities_media_capabilities_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Media Capabilities Media Capabilities Get
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
  /media/verify:
    get:
      tags:
      - media
      summary: Media Verify Tool
      description: Human-facing verifier. Hashing happens client-side; the file is not uploaded.
      operationId: media_verify_tool_media_verify_get
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
    post:
      tags:
      - media
      summary: Verify Media
      description: 'Verify a media file''s hash against its attestation certificate.


        Free endpoint  -  no API key or payment required. Anyone can verify.'
      operationId: verify_media_media_verify_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaVerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaVerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
  /media/status/{certificate_id}:
    get:
      tags:
      - media
      summary: Media Certificate Status
      description: Public certificate lifecycle status for agents and humans.
      operationId: media_certificate_status_media_status__certificate_id__get
      parameters:
      - name: certificate_id
        in: path
        required: true
        schema:
          type: string
          title: Certificate Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Media Certificate Status Media Status  Certificate Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
  /media/approve/{certificate_id}:
    post:
      tags:
      - media
      summary: Approve Media Certificate
      description: Approve or deny a certificate for campaign/media use.
      operationId: approve_media_certificate_media_approve__certificate_id__post
      parameters:
      - name: certificate_id
        in: path
        required: true
        schema:
          type: string
          title: Certificate Id
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaApprovalRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Approve Media Certificate Media Approve  Certificate Id  Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
      x-authority-info:
        authority: media_lifecycle_operator
        requires:
        - X-API-Key bound to certificate agent_id
        - or internal admin key
        accepts_paid_rail: false
        settlement_signal: false
        revenue_signal: false
  /media/revoke/{certificate_id}:
    post:
      tags:
      - media
      summary: Revoke Media Certificate
      description: Revoke a media authority certificate.
      operationId: revoke_media_certificate_media_revoke__certificate_id__post
      parameters:
      - name: certificate_id
        in: path
        required: true
        schema:
          type: string
          title: Certificate Id
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaRevokeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Revoke Media Certificate Media Revoke  Certificate Id  Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
      x-authority-info:
        authority: media_lifecycle_operator
        requires:
        - X-API-Key bound to certificate agent_id
        - or internal admin key
        accepts_paid_rail: false
        settlement_signal: false
        revenue_signal: false
  /media/attest:
    post:
      tags:
      - media
      summary: Attest Media
      description: 'Attest a media file''s integrity via its SHA-256 hash.


        The media file never leaves the user''s device. Only the hash

        and metadata are recorded in the provenance chain. Returns a

        PQC-signed certificate with a public verification URL.'
      operationId: attest_media_media_attest_post
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaAttestRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaAttestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment challenge metadata. Executable POST requires X-API-Key, verified Delegation proof, or a verified x402, L402, or MPP credential obtained from safe-method payment challenge discovery.
      x-payment-info:
        intent: charge
        method: mpp-fiat
        amount: '5'
        currency: usd
        amount_unit: usd_cents
        description: Media authority certificate issuance
        delegation_authorization_required: true
        settlement_signal: false
        revenue_signal: false
  /media/verify/{certificate_id}:
    get:
      tags:
      - media
      summary: Lookup Certificate
      description: 'Look up a media attestation certificate by its ID.


        Free endpoint  -  no API key or payment required. Returns the

        full certificate for independent verification.'
      operationId: lookup_certificate_media_verify__certificate_id__get
      parameters:
      - name: certificate_id
        in: path
        required: true
        schema:
          type: string
          title: Certificate Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaVerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
  /signup:
    post:
      tags:
      - signup
      summary: Signup
      description: 'Get a trial API key for agent evaluation.


        - 1,000 calls per month

        - 10 requests per minute rate limit

        - No credit card, no email required

        - Upgrade anytime for higher limits


        Anti-abuse: rate-limited keys per IP per 24 hours.'
      operationId: signup
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupRequest'
        required: true
      responses:
        '200':
          description: Trial API key provisioned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupResponse'
              example:
                api_key: ''
                tier: free
                monthly_limit: 1000
                rate_limit_per_minute: 10
                upgrade_url: https://governance.taskhawktech.com/pricing
                payment_discovery_url: https://governance.taskhawktech.com/payment/discovery
                usage:
                  header: X-API-Key
                  example: 'curl -H ''X-API-Key: kv1_...'' -X POST https://governance.taskhawktech.com/governance/verify ...'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
  /shield/scan:
    post:
      tags:
      - shield
      summary: Shield Scan
      description: Scan a prompt for injection attacks. $0.01 per scan.
      operationId: shield-scan
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Delegation-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Delegation-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment challenge metadata. Executable POST requires X-API-Key, verified Delegation proof, or a verified x402, L402, or MPP credential obtained from safe-method payment challenge discovery.
      x-payment-info:
        intent: charge
        method: stripe
        amount: '1'
        currency: usd
        amount_unit: usd_cents
        description: Prompt injection detection
        delegation_authorization_required: true
        settlement_signal: false
        revenue_signal: false
  /shield/scan-free:
    post:
      tags:
      - shield
      summary: Shield Scan Free
      description: Free prompt injection scan. 10 scans/day per IP, no auth needed.
      operationId: shield-scan-free
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
  /governance/mpp/session:
    post:
      tags:
      - governance
      summary: Create a governed MPP payment session
      description: 'Authorize a new streaming payment session. The agent receives a signed session token and can stream payments within the declared budget and rate limits. Every session is recorded in the provenance ledger. Cost: $0.02 per session.'
      operationId: mpp-create-session
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Delegation-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Delegation-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MPPSessionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MPPSessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: Payment challenge metadata. Executable POST requires X-API-Key, verified Delegation proof, or a verified x402, L402, or MPP credential obtained from safe-method payment challenge discovery.
      x-payment-info:
        intent: charge
        method: stripe
        amount: '2'
        currency: usd
        amount_unit: usd_cents
        description: Governed streaming session
        delegation_authorization_required: true
        settlement_signal: false
        revenue_signal: false
  /governance/mpp/heartbeat:
    post:
      tags:
      - governance
      summary: Mid-session drift check
      description: Called periodically during a streaming payment session. Kevros checks for budget overruns, rate limit violations, and unauthorized service usage. Free (no charge per heartbeat).
      operationId: mpp-heartbeat
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Delegation-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Delegation-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MPPHeartbeatRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MPPHeartbeatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
  /governance/mpp/close:
    post:
      tags:
      - governance
      summary: Close an MPP session
      description: Close a streaming payment session and seal the provenance record. Free (no charge).
      operationId: mpp-close-session
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: X-Delegation-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Delegation-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MPPCloseRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MPPCloseResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-payment-info:
        intent: none
        method: none
        amount: null
        currency: usd
        amount_unit: usd_cents
        settlement_signal: false
        revenue_signal: false
  /payment/discovery:
    get:
      tags:
      - billing
      summary: 'Single-call aggregator: rail challenge configuration + all per-endpoint quotes'
      description: 'One-call discovery: rail health AND per-endpoint quotes for every

        paid endpoint, bundled into a single response.


        Replaces the N+1 startup pattern (1x /payment/health + N x /payment/quote)

        with a single HTTP round-trip. Cheaper for agents, cheaper for the

        gateway origin, more frictionless.


        Cache: 30s (matches /payment/health since it''s the bottleneck).


        Conditional GET: when the client sends `If-None-Match: W/"<fingerprint>"`

        AND the value matches the current pricing_fingerprint, the gateway

        returns 304 Not Modified with NO body. Cached agents can poll the

        endpoint cheaply (single line with the `requests` library: pass

        `headers={''If-None-Match'': last_etag}` and check for 304). The 304

        response includes the same ETag and Cache-Control headers as the

        full 200 response so caches continue to dedupe.'
      operationId: getPaymentDiscovery
      responses:
        '200':
          description: 'Full payment surface in one response: rail challenge configuration + per-endpoint pricing'
          content:
            application/json:
              schema: {}
              example:
                health:
                  status: healthy
                  rails_enabled: 5
                  rails_total: 5
                  rails:
                  - rail: x402
                    enabled: true
                    network: base-mainnet
                endpoints:
                  /governance/verify:
                    free: false
                    rails:
                    - rail: x402
                      amount_usdc: '10000'
                      amount_display: $0.01
                      currency: USDC
                      network: base-mainnet
                doc: https://governance.taskhawktech.com/api
    head:
      tags:
      - billing
      summary: 'Single-call aggregator: rail challenge configuration + all per-endpoint quotes'
      description: 'One-call discovery: rail health AND per-endpoint quotes for every

        paid endpoint, bundled into a single response.


        Replaces the N+1 startup pattern (1x /payment/health + N x /payment/quote)

        with a single HTTP round-trip. Cheaper for agents, cheaper for the

        gateway origin, more frictionless.


        Cache: 30s (matches /payment/health since it''s the bottleneck).


        Conditional GET: when the client sends `If-None-Match: W/"<fingerprint>"`

        AND the value matches the current pricing_fingerprint, the gateway

        returns 304 Not Modified with NO body. Cached agents can poll the

        endpoint cheaply (single line with the `requests` library: pass

        `headers={''If-None-Match'': last_etag}` and check for 304). The 304

        response includes the same ETag and Cache-Control headers as the

        full 200 response so caches continue to dedupe.'
      operationId: getPaymentDiscovery
      responses:
        '200':
          description: 'Full payment surface in one response: rail challenge configuration + per-endpoint pricing'
          content:
            application/json:
              schema: {}
              example:
                health:
                  status: healthy
                  rails_enabled: 5
                  rails_total: 5
                  rails:
                  - rail: x402
                    enabled: true
                    network: base-mainnet
                endpoints:
                  /governance/verify:
                    free: false
                    rails:
                    - rail: x402
                      amount_usdc: '10000'
                      amount_display: $0.01
                      currency: USDC
                      network: base-mainnet
                doc: https://governance.taskhawktech.com/api
  /payment/badge:
    get:
      tags:
      - billing
      summary: Compact rail challenge-configuration status for embedding
      description: "Compact rail challenge-configuration badge for status pages, README badges, and\ndashboards. Pairs with `/payment/health` (full detail) but returns\na single line that's cheap to embed anywhere.\n\nTwo formats based on Accept header:\n  - `text/plain`     -> \"3/5 rails configured\"  (suitable for `curl`)\n  - `application/json` (default) → Shields.io schema\n\nFor Shields.io embedding:\n  https://img.shields.io/endpoint?url=https://governance.taskhawktech.com/payment/badge\n\nCache: 30s (matches /payment/health to keep counts in sync)."
      operationId: getPaymentBadge
      responses:
        '200':
          description: Shields.io-compatible JSON badge schema
          content:
            application/json:
              schema: {}
              example:
                schemaVersion: 1
                label: rails
                message: 4/5 configured
                color: brightgreen
            text/plain:
              example: 4/5 rails configured
    head:
      tags:
      - billing
      summary: Compact rail challenge-configuration status for embedding
      description: "Compact rail challenge-configuration badge for status pages, README badges, and\ndashboards. Pairs with `/payment/health` (full detail) but returns\na single line that's cheap to embed anywhere.\n\nTwo formats based on Accept header:\n  - `text/plain`     -> \"3/5 rails configured\"  (suitable for `curl`)\n  - `application/json` (default) → Shields.io schema\n\nFor Shields.io embedding:\n  https://img.shields.io/endpoint?url=https://governance.taskhawktech.com/payment/badge\n\nCache: 30s (matches /payment/health to keep counts in sync)."
      operationId: getPaymentBadge
      responses:
        '200':
          description: Shields.io-compatible JSON badge schema
          content:
            application/json:
              schema: {}
              example:
                schemaVersion: 1
                label: rails
                message: 4/5 configured
                color: brightgreen
            text/plain:
              example: 4/5 rails configured
  /payment/quote:
    get:
      tags:
      - billing
      summary: Get the per-rail price for a specific endpoint
      description: "Per-endpoint price quote across all candidate rails.\n\nLets clients pre-budget for a paid call sequence without burning a 402\nround-trip per endpoint. Returns the same price info that may be\nembedded in a settlement-rail challenge response, but on demand and\nwithout requiring the client to make a real request first.\n\nQuery param: `endpoint` (required) — the endpoint path the client\nintends to call (e.g. `/governance/verify`).\n\nPairs with `/payment/health` for the full discovery loop:\n  1. GET /payment/health -> which rails can emit challenge/config metadata?\n  2. GET /payment/quote?endpoint=/governance/verify → how much?\n  3. POST /governance/verify only after X-API-Key or verified Delegation proof."
      operationId: getPaymentQuote
      parameters:
      - name: endpoint
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Endpoint
      responses:
        '200':
          description: Per-rail price for the requested endpoint, with challenge metadata and Protocol 427 prerequisites inline
          content:
            application/json:
              schema: {}
              example:
                endpoint: /governance/verify
                free: false
                rails:
                - rail: x402
                  amount_usdc: '10000'
                  amount_display: $0.01
                  currency: USDC
                  network: base-mainnet
                - rail: mpp
                  amount_cents: 1
                  amount_display: $0.01
                  currency: USD
                doc: https://governance.taskhawktech.com/api
                health_url: https://governance.taskhawktech.com/payment/health
        '400':
          description: Invalid endpoint parameter
        '404':
          description: Endpoint is not priced (free or unknown)
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payment/health:
    head:
      tags:
      - billing
      summary: Payment rail challenge-configuration status
      description: "Per-rail payment challenge-configuration status. Public, cacheable for 30s.\n\nFor each payment rail, returns:\n  - enabled: True iff the configuration needed to issue a payment\n    challenge or discovery metadata is present (env vars, secrets,\n    identity material). This is not settlement or revenue evidence.\n  - rail: short identifier matching what /.well-known docs use\n  - reason: when enabled=False, a one-line operator-readable reason\n    (NEVER includes secret values)\n\nDesigned for two audiences:\n  1. AI agents — poll this BEFORE attempting a rail so they do not\n     chase a rail that cannot emit the expected challenge metadata.\n  2. Operators / oncall — single curl shows configured rail candidates\n     without needing to read the gateway's bootlog.\n\nBy default this endpoint does NO outbound network calls — it only\nreflects local public configuration state. `?deep=true` performs\noperator-only backend probes and requires X-Admin-Key."
      operationId: getPaymentHealth
      parameters:
      - name: deep
        in: query
        required: false
        schema:
          type: boolean
          description: Probe backend connectivity; requires X-Admin-Key
          default: false
          title: Deep
        description: Probe backend connectivity; requires X-Admin-Key
      - name: X-Admin-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Admin-Key
      responses:
        '200':
          description: Per-rail challenge-configuration state with operator-readable failure reasons. Not settlement or revenue evidence.
          content:
            application/json:
              schema: {}
              example:
                status: healthy
                rails_enabled: 3
                rails_total: 5
                rails:
                - rail: x402
                  enabled: true
                  network: base-mainnet
                - rail: l402
                  enabled: true
                  network: lightning
                - rail: mpp
                  enabled: true
                  network: fiat
                version: 0.x.x
                doc: https://governance.taskhawktech.com/.well-known/x402
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - billing
      summary: Payment rail challenge-configuration status
      description: "Per-rail payment challenge-configuration status. Public, cacheable for 30s.\n\nFor each payment rail, returns:\n  - enabled: True iff the configuration needed to issue a payment\n    challenge or discovery metadata is present (env vars, secrets,\n    identity material). This is not settlement or revenue evidence.\n  - rail: short identifier matching what /.well-known docs use\n  - reason: when enabled=False, a one-line operator-readable reason\n    (NEVER includes secret values)\n\nDesigned for two audiences:\n  1. AI agents — poll this BEFORE attempting a rail so they do not\n     chase a rail that cannot emit the expected challenge metadata.\n  2. Operators / oncall — single curl shows configured rail candidates\n     without needing to read the gateway's bootlog.\n\nBy default this endpoint does NO outbound network calls — it only\nreflects local public configuration state. `?deep=true` performs\noperator-only backend probes and requires X-Admin-Key."
      operationId: getPaymentHealth
      parameters:
      - name: deep
        in: query
        required: false
        schema:
          type: boolean
          description: Probe backend connectivity; requires X-Admin-Key
          default: false
          title: Deep
        description: Probe backend connectivity; requires X-Admin-Key
      - name: X-Admin-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Admin-Key
      responses:
        '200':
          description: Per-rail challenge-configuration state with operator-readable failure reasons. Not settlement or revenue evidence.
          content:
            application/json:
              schema: {}
              example:
                status: healthy
                rails_enabled: 3
                rails_total: 5
                rails:
                - rail: x402
                  enabled: true
                  network: base-mainnet
                - rail: l402
                  enabled: true
                  network: lightning
                - rail: mpp
                  enabled: true
                  network: fiat
                version: 0.x.x
                doc: https://governance.taskhawktech.com/.well-known/x402
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AttestRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
        action_description:
          type: string
          maxLength: 2048
          minLength: 1
          title: Action Description
          description: What the agent did
        action_payload:
          additionalProperties: true
          type: object
          title: Action Payload
          description: Full action details for the record
        context:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Context
          description: Additional context (environment, state, etc.)
        prior_attestation_hash:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Prior Attestation Hash
          description: Hash of the agent's prior attestation (for agent-side chain continuity)
        cmd_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Cmd Id
          description: Command ID for replay protection. Auto-generated by SDK if not provided.
        risk_category:
          anyOf:
          - $ref: '#/components/schemas/RiskCategory'
          - type: 'null'
          description: EU AI Act risk classification for this attestation record.
      type: object
      required:
      - agent_id
      - action_description
      - action_payload
      title: AttestRequest
      description: Request to create a hash-chained provenance attestation.
    AttestResponse:
      properties:
        attestation_id:
          type: string
          title: Attestation Id
        epoch:
          type: integer
          title: Epoch
        hash_prev:
          type: string
          title: Hash Prev
          description: Previous hash in the chain
        hash_curr:
          type: string
          title: Hash Curr
          description: Current hash (includes this record)
        pqc_block_ref:
          type: string
          minLength: 1
          title: Pqc Block Ref
          description: 'Post-quantum signature anchor reference. Always populated. Form: ''block:<N>:sig:<hex16>...:policy:<policy>'' for chain positions past the first block boundary; ''pending:<chain_length>/<BLOCK_SIZE>'' before. See ``pqc_anchor`` for full metadata.'
        pqc_anchor:
          $ref: '#/components/schemas/PQCAnchor'
          description: Rich PQC anchor metadata (block_index, anchor_lag, signature_policy, etc.). See spec.md §16.7 for the verifier contract.
        timestamp_utc:
          type: string
          title: Timestamp Utc
        chain_length:
          type: integer
          title: Chain Length
          description: Number of records in the chain so far
        contract_versions:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Contract Versions
          description: 'Surface version metadata for the contract this response participates in (issue #595). Optional + nullable so server can `exclude_none=True` from wire when omitted | preserves backwards-compat with strict (`extra=''forbid''`) SDK clients pinned to the pre-field schema.'
      type: object
      required:
      - attestation_id
      - epoch
      - hash_prev
      - hash_curr
      - pqc_block_ref
      - pqc_anchor
      - timestamp_utc
      - chain_length
      title: AttestResponse
      description: 'Hash-chained provenance attestation.


        Iteration-3 finding (2026-05-11 Prove Claims #19 regression): the

        legacy shape had ``pqc_block_ref: Optional[str]`` which FastAPI

        dropped from JSON when null (the 99% case between block boundaries).

        External claim verifiers saw no PQC evidence on most responses,

        contradicting the Six-Layer thesis posture.


        Post-fix: ``pqc_block_ref`` is ALWAYS a non-empty string referencing

        the most recent signed block (or a ``pending:N/100`` sentinel before

        the first block). The new ``pqc_anchor`` field gives rich metadata

        for verifier consumption. Field shape is documented in spec.md §16.7.'
    BindIntentRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
        intent_type:
          $ref: '#/components/schemas/IntentType'
        intent_description:
          type: string
          maxLength: 2048
          minLength: 1
          title: Intent Description
          description: What the agent intends to accomplish
        intent_source:
          $ref: '#/components/schemas/IntentSource'
          default: AI_PLANNER
        goal_state:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Goal State
          description: Target state the agent wants to reach
        command_payload:
          additionalProperties: true
          type: object
          title: Command Payload
          description: The command being bound to this intent
        max_duration_ms:
          anyOf:
          - type: number
            maximum: 86400000.0
            minimum: 0.0
          - type: 'null'
          title: Max Duration Ms
          description: Max duration in milliseconds (up to 24h)
        parent_intent_id:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Parent Intent Id
          description: Parent intent for hierarchical intent chains
        cmd_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Cmd Id
          description: Command ID for replay protection. Auto-generated by SDK if not provided.
      type: object
      required:
      - agent_id
      - intent_type
      - intent_description
      - command_payload
      title: BindIntentRequest
      description: Declare an intent and bind it to a command.
    BindIntentResponse:
      properties:
        intent_id:
          type: string
          title: Intent Id
        intent_hash:
          type: string
          title: Intent Hash
          description: SHA-256 hash of canonical intent
        binding_id:
          type: string
          title: Binding Id
        binding_hmac:
          type: string
          title: Binding Hmac
          description: HMAC proving intent-command linkage
        command_hash:
          type: string
          title: Command Hash
        epoch:
          type: integer
          title: Epoch
        timestamp_utc:
          type: string
          title: Timestamp Utc
        contract_versions:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Contract Versions
          description: 'Surface version metadata for the contract this response participates in (issue #595). Optional + nullable so server can `exclude_none=True` from wire when omitted | preserves backwards-compat with strict (`extra=''forbid''`) SDK clients pinned to the pre-field schema.'
      type: object
      required:
      - intent_id
      - intent_hash
      - binding_id
      - binding_hmac
      - command_hash
      - epoch
      - timestamp_utc
      title: BindIntentResponse
      description: Cryptographic intent binding.
    BundleRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
        time_range_start:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Time Range Start
          description: 'ISO 8601 start of range (default: last 24h)'
        time_range_end:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Time Range End
          description: 'ISO 8601 end of range (default: now)'
        max_records:
          type: integer
          maximum: 100000.0
          minimum: 1.0
          title: Max Records
          description: Maximum records to include (pagination limit)
          default: 10000
        include_intent_chains:
          type: boolean
          title: Include Intent Chains
          default: true
        include_pqc_signatures:
          type: boolean
          title: Include Pqc Signatures
          default: true
        include_verification_instructions:
          type: boolean
          title: Include Verification Instructions
          default: true
      type: object
      required:
      - agent_id
      title: BundleRequest
      description: Request a certifier-grade compliance evidence bundle.
    BundleResponse:
      properties:
        bundle_id:
          type: string
          title: Bundle Id
        agent_id:
          type: string
          title: Agent Id
        record_count:
          type: integer
          title: Record Count
        truncated:
          type: boolean
          title: Truncated
          description: Whether records were truncated by max_records limit
          default: false
        chain_integrity:
          type: boolean
          title: Chain Integrity
          description: Whether the hash chain is intact end-to-end
        time_range:
          additionalProperties:
            type: string
          type: object
          title: Time Range
        records:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Records
        intent_chains:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Intent Chains
        pqc_signatures:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Pqc Signatures
        verification_instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Verification Instructions
          description: How a third party can independently verify this bundle
        bundle_hash:
          type: string
          title: Bundle Hash
          description: SHA-256 of the entire bundle (for integrity checking)
        timestamp_utc:
          type: string
          title: Timestamp Utc
        contract_versions:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Contract Versions
          description: 'Surface version metadata for the contract this response participates in (issue #595). Optional + nullable so server can `exclude_none=True` from wire when omitted | preserves backwards-compat with strict (`extra=''forbid''`) SDK clients pinned to the pre-field schema.'
      type: object
      required:
      - bundle_id
      - agent_id
      - record_count
      - chain_integrity
      - time_range
      - records
      - bundle_hash
      - timestamp_utc
      title: BundleResponse
      description: Certifier-grade compliance evidence bundle.
    CaptureLocation:
      properties:
        latitude:
          type: number
          maximum: 90.0
          minimum: -90.0
          title: Latitude
        longitude:
          type: number
          maximum: 180.0
          minimum: -180.0
          title: Longitude
        altitude:
          anyOf:
          - type: number
          - type: 'null'
          title: Altitude
          description: Meters above sea level
        accuracy:
          anyOf:
          - type: number
            minimum: 0.0
          - type: 'null'
          title: Accuracy
          description: GPS accuracy in meters
      type: object
      required:
      - latitude
      - longitude
      title: CaptureLocation
      description: GPS coordinates at time of capture.
    Decision:
      type: string
      enum:
      - ALLOW
      - CONSTRAIN
      - DENY
      title: Decision
    DeviceInfo:
      properties:
        model:
          type: string
          maxLength: 256
          minLength: 1
          title: Model
          description: Device model (e.g., 'iPhone 16 Pro')
        os_version:
          type: string
          maxLength: 64
          minLength: 1
          title: Os Version
          description: OS version (e.g., 'iOS 18.3')
        app_version:
          type: string
          maxLength: 32
          minLength: 1
          title: App Version
          description: Kevros app version
        device_id_hash:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Device Id Hash
          description: SHA-256 of stable device identifier (privacy-preserving)
      type: object
      required:
      - model
      - os_version
      - app_version
      title: DeviceInfo
      description: Device metadata for provenance context.
    EnforcementMode:
      type: string
      enum:
      - enforce
      - advisory
      - deny
      - gated
      title: EnforcementMode
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    IntentSource:
      type: string
      enum:
      - HUMAN_OPERATOR
      - AI_PLANNER
      - MISSION_SCRIPT
      - REMOTE_API
      - SENSOR_TRIGGER
      - INTERNAL
      title: IntentSource
    IntentType:
      type: string
      enum:
      - NAVIGATION
      - MANIPULATION
      - SENSING
      - COMMUNICATION
      - MAINTENANCE
      - EMERGENCY
      - OPERATOR_COMMAND
      - AI_GENERATED
      - AUTOMATED
      title: IntentType
    MPPCloseRequest:
      properties:
        session_id:
          type: string
          title: Session Id
          description: Session to close
        agent_id:
          type: string
          title: Agent Id
          description: Agent closing the session
        final_spent_cents:
          type: integer
          minimum: 0.0
          title: Final Spent Cents
        final_transactions_count:
          type: integer
          minimum: 0.0
          title: Final Transactions Count
        close_reason:
          type: string
          title: Close Reason
          description: completed, budget_exhausted, timeout, drift_detected, agent_requested
          default: completed
      type: object
      required:
      - session_id
      - agent_id
      - final_spent_cents
      - final_transactions_count
      title: MPPCloseRequest
      description: Close a streaming payment session.
    MPPCloseResponse:
      properties:
        session_id:
          type: string
          title: Session Id
        status:
          type: string
          title: Status
        total_spent_cents:
          type: integer
          title: Total Spent Cents
        total_transactions:
          type: integer
          title: Total Transactions
        duration_actual_seconds:
          type: number
          title: Duration Actual Seconds
        provenance_hash:
          type: string
          title: Provenance Hash
        bundle_available:
          type: boolean
          title: Bundle Available
      type: object
      required:
      - session_id
      - status
      - total_spent_cents
      - total_transactions
      - duration_actual_seconds
      - provenance_hash
      - bundle_available
      title: MPPCloseResponse
      description: Session close confirmation.
    MPPHeartbeatRequest:
      properties:
        session_id:
          type: string
          title: Session Id
          description: Active session ID
        agent_id:
          type: string
          title: Agent Id
          description: Agent sending heartbeat
        spent_cents:
          type: integer
          minimum: 0.0
          title: Spent Cents
          description: Total spent so far in this session
        transactions_count:
          type: integer
          minimum: 0.0
          title: Transactions Count
        current_service:
          type: string
          title: Current Service
          description: Service currently being used
        spending_rate_cents_per_minute:
          type: number
          minimum: 0.0
          title: Spending Rate Cents Per Minute
          description: Current spending rate
      type: object
      required:
      - session_id
      - agent_id
      - spent_cents
      - transactions_count
      - current_service
      - spending_rate_cents_per_minute
      title: MPPHeartbeatRequest
      description: Mid-session drift check during streaming payments.
    MPPHeartbeatResponse:
      properties:
        session_id:
          type: string
          title: Session Id
        status:
          type: string
          title: Status
        budget_remaining_cents:
          type: integer
          title: Budget Remaining Cents
        time_remaining_seconds:
          type: integer
          title: Time Remaining Seconds
        drift_detected:
          type: boolean
          title: Drift Detected
        drift_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Drift Reason
        provenance_hash:
          type: string
          title: Provenance Hash
      type: object
      required:
      - session_id
      - status
      - budget_remaining_cents
      - time_remaining_seconds
      - drift_detected
      - provenance_hash
      title: MPPHeartbeatResponse
      description: Heartbeat drift check result.
    MPPSessionRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: Agent requesting the session
        session_budget_cents:
          type: integer
          maximum: 10000000.0
          minimum: 1.0
          title: Session Budget Cents
          description: Maximum session spend in cents
        duration_seconds:
          type: integer
          maximum: 86400.0
          minimum: 60.0
          title: Duration Seconds
          description: Session duration (60s to 24h)
        spending_rate_limit_cents_per_minute:
          type: integer
          maximum: 100000.0
          minimum: 1.0
          title: Spending Rate Limit Cents Per Minute
          description: Max spend rate per minute in cents
          default: 500
        allowed_services:
          items:
            type: string
          type: array
          title: Allowed Services
          description: Allowed service categories
        payment_rail:
          type: string
          title: Payment Rail
          description: 'Payment rail: stripe, x402, tempo'
          default: stripe
      type: object
      required:
      - agent_id
      - session_budget_cents
      - duration_seconds
      title: MPPSessionRequest
      description: Authorize a new MPP streaming payment session.
      example:
        agent_id: agent-001
        allowed_services:
        - inference
        - storage
        - compute
        duration_seconds: 3600
        payment_rail: stripe
        session_budget_cents: 50000
        spending_rate_limit_cents_per_minute: 500
    MPPSessionResponse:
      properties:
        session_id:
          type: string
          title: Session Id
        decision:
          type: string
          title: Decision
        session_token:
          type: string
          title: Session Token
        budget_cents:
          type: integer
          title: Budget Cents
        duration_seconds:
          type: integer
          title: Duration Seconds
        rate_limit_cents_per_minute:
          type: integer
          title: Rate Limit Cents Per Minute
        allowed_services:
          items:
            type: string
          type: array
          title: Allowed Services
        expires_at:
          type: string
          title: Expires At
        provenance_hash:
          type: string
          title: Provenance Hash
      type: object
      required:
      - session_id
      - decision
      - session_token
      - budget_cents
      - duration_seconds
      - rate_limit_cents_per_minute
      - allowed_services
      - expires_at
      - provenance_hash
      title: MPPSessionResponse
      description: Authorized MPP session details.
    MediaApprovalRequest:
      properties:
        decision:
          type: string
          title: Decision
          description: approved or denied
          default: approved
        approver:
          anyOf:
          - type: string
            maxLength: 256
            minLength: 1
          - type: 'null'
          title: Approver
        reason:
          anyOf:
          - type: string
            maxLength: 1024
          - type: 'null'
          title: Reason
        campaign_id:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Campaign Id
        brand_client:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Brand Client
        permitted_use:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Permitted Use
        territory:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Territory
        expiry:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Expiry
        policy_id:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Policy Id
      type: object
      title: MediaApprovalRequest
      description: Operator approval or denial for a media certificate.
    MediaAttestRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: Identifier of the requesting agent or user
        media_hash:
          type: string
          title: Media Hash
          description: SHA-256 hex digest of the media file bytes
        media_type:
          $ref: '#/components/schemas/MediaType'
        media_size_bytes:
          type: integer
          maximum: 10737418240.0
          exclusiveMinimum: 0.0
          title: Media Size Bytes
          description: File size in bytes (max 10 GB)
        capture_timestamp_utc:
          type: string
          maxLength: 64
          minLength: 1
          title: Capture Timestamp Utc
          description: ISO 8601 timestamp of when the media was captured
        capture_location:
          anyOf:
          - $ref: '#/components/schemas/CaptureLocation'
          - type: 'null'
        device_info:
          anyOf:
          - $ref: '#/components/schemas/DeviceInfo'
          - type: 'null'
        app_attest_assertion:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
          title: App Attest Assertion
          description: Base64 Apple App Attest assertion (device integrity proof)
        description:
          anyOf:
          - type: string
            maxLength: 1024
          - type: 'null'
          title: Description
        tags:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 20
          - type: 'null'
          title: Tags
        frame_hashes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Frame Hashes
          description: Per-frame SHA-256 hashes for video/live capture (streaming integrity)
        c2pa_manifest_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: C2Pa Manifest Hash
          description: SHA-256 hex digest of the associated C2PA manifest, if present
        campaign_id:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Campaign Id
        brand_client:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Brand Client
        approver:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Approver
        permitted_use:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Permitted Use
        territory:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Territory
        expiry:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Expiry
        license_uri:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: License Uri
        consent_assertion:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Consent Assertion
        model_provider:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Model Provider
        model_id:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Model Id
        prompt_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt Hash
          description: SHA-256 hex digest of the prompt or generation instruction, if applicable
        policy_id:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Policy Id
      type: object
      required:
      - agent_id
      - media_hash
      - media_type
      - media_size_bytes
      - capture_timestamp_utc
      title: MediaAttestRequest
      description: Request to attest a media file's integrity via its hash.
    MediaAttestResponse:
      properties:
        attestation_id:
          type: string
          title: Attestation Id
        media_hash:
          type: string
          title: Media Hash
        media_type:
          type: string
          title: Media Type
        epoch:
          type: integer
          title: Epoch
        hash_prev:
          type: string
          title: Hash Prev
        hash_curr:
          type: string
          title: Hash Curr
        pqc_block_ref:
          type: string
          minLength: 1
          title: Pqc Block Ref
          description: Post-quantum signature anchor reference. Always populated. See AttestResponse.pqc_block_ref / spec.md §16.7.
        pqc_anchor:
          $ref: '#/components/schemas/PQCAnchor'
          description: Rich PQC anchor metadata. See spec.md §16.7.
        certificate_id:
          type: string
          title: Certificate Id
          description: Short ID for verification URLs
        verification_url:
          type: string
          title: Verification Url
        device_verified:
          type: boolean
          title: Device Verified
          description: True if App Attest assertion was validated
          default: false
        chain_length:
          type: integer
          title: Chain Length
        timestamp_utc:
          type: string
          title: Timestamp Utc
        frame_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Frame Count
          description: Number of per-frame hashes recorded
        frame_root_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Frame Root Hash
          description: Merkle root of per-frame hashes
        contract_versions:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Contract Versions
          description: 'Surface version metadata for the contract this response participates in (issue #595). Optional + nullable so server can `exclude_none=True` from wire when omitted | preserves backwards-compat with strict (`extra=''forbid''`) SDK clients pinned to the pre-field schema.'
      type: object
      required:
      - attestation_id
      - media_hash
      - media_type
      - epoch
      - hash_prev
      - hash_curr
      - pqc_block_ref
      - pqc_anchor
      - certificate_id
      - verification_url
      - chain_length
      - timestamp_utc
      title: MediaAttestResponse
      description: 'PQC-signed media attestation certificate.


        Carries the same PQC anchor contract as AttestResponse (spec.md §16.7):

        ``pqc_block_ref`` is always non-empty; ``pqc_anchor`` is the rich

        metadata for verifier consumption. Pre-2026-05-11 the field was

        Optional and the router used response_model_exclude_none=True, so

        the field disappeared from JSON on inter-block calls.'
    MediaRevokeRequest:
      properties:
        reason:
          type: string
          maxLength: 1024
          minLength: 1
          title: Reason
        revoked_by:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Revoked By
      type: object
      required:
      - reason
      title: MediaRevokeRequest
      description: Revoke a media certificate.
    MediaType:
      type: string
      enum:
      - PHOTO
      - VIDEO
      - AUDIO
      - DOCUMENT
      title: MediaType
      description: Supported media types for attestation.
    MediaVerifyRequest:
      properties:
        media_hash:
          type: string
          title: Media Hash
          description: SHA-256 hex digest to verify against certificate
        certificate_id:
          type: string
          maxLength: 32
          minLength: 1
          title: Certificate Id
          description: Certificate ID from attestation
      type: object
      required:
      - media_hash
      - certificate_id
      title: MediaVerifyRequest
      description: Verify a media file against a certificate.
    MediaVerifyResponse:
      properties:
        verified:
          type: boolean
          title: Verified
        certificate_id:
          type: string
          title: Certificate Id
        certificate_found:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Certificate Found
          description: True when a certificate record exists, independent of media byte/hash verification
        media_hash_checked:
          type: boolean
          title: Media Hash Checked
          description: True only when the caller supplied a media hash for byte-level verification
          default: false
        media_hash_match:
          type: boolean
          title: Media Hash Match
        chain_integrity:
          type: boolean
          title: Chain Integrity
        pqc_signature_valid:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Pqc Signature Valid
        certificate:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Certificate
          description: Full certificate details when a certificate exists; byte verification is represented by verified/media_hash_checked
        reason:
          type: string
          title: Reason
          description: Human-readable verification result
          default: ''
        layers:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Layers
          description: Layered machine-readable media authority verdicts
        machine_action:
          anyOf:
          - type: string
          - type: 'null'
          title: Machine Action
          description: Suggested machine action for agent workflows
        human_verdict:
          anyOf:
          - type: string
          - type: 'null'
          title: Human Verdict
          description: Short human-facing verdict for certificate pages
        human_summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Human Summary
          description: Plain-language summary for non-technical verifiers
        agent_view:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Agent View
          description: Compact machine-facing view derived from the same certificate
        public_view:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Public View
          description: Human-facing view metadata derived from the same certificate
        contract_versions:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Contract Versions
          description: 'Surface version metadata for the contract this response participates in (issue #595). Optional + nullable so server can `exclude_none=True` from wire when omitted | preserves backwards-compat with strict (`extra=''forbid''`) SDK clients pinned to the pre-field schema.'
      type: object
      required:
      - verified
      - certificate_id
      - media_hash_match
      - chain_integrity
      title: MediaVerifyResponse
      description: Result of media verification.
    OutcomeStatus:
      type: string
      enum:
      - ACHIEVED
      - PARTIALLY_ACHIEVED
      - FAILED
      - BLOCKED
      - TIMEOUT
      title: OutcomeStatus
    PQCAnchor:
      properties:
        block_index:
          type: integer
          minimum: -1.0
          title: Block Index
          description: 0-indexed block number of the most recent signed block; -1 if no block has been signed yet
        block_ref:
          type: string
          minLength: 1
          title: Block Ref
          description: 'Human-readable reference to the anchoring block signature. Form: ''block:<N>:sig:<hex16>...:policy:<policy>'' or ''pending:<chain_length>/<BLOCK_SIZE>'' before the first block.'
        anchor_lag:
          type: integer
          exclusiveMaximum: 100.0
          minimum: 0.0
          title: Anchor Lag
          description: Number of records since the last signed block boundary. Always 0 <= anchor_lag < BLOCK_SIZE (=100).
        next_block_at:
          type: integer
          title: Next Block At
          description: chain_length at which the next block signature will fire
        signature_policy:
          type: string
          title: Signature Policy
          description: 'Most-recent anchor block''s signature policy: ''ml_dsa_only'' (api_key/free/l402 rails), ''dual_pq'' (x402/MPP on-chain rails), or ''pending'' (no block signed yet)'
        algorithm:
          type: string
          title: Algorithm
          description: Primary signature algorithm (ML-DSA-87 = FIPS 204)
        standard:
          type: string
          title: Standard
          description: Primary signature standard (FIPS 204)
        slh_dsa_present:
          type: boolean
          title: Slh Dsa Present
          description: True if the anchor block also carries an SLH-DSA-SHA2-256f signature (FIPS 205). Required for dual_pq rails.
      type: object
      required:
      - block_index
      - block_ref
      - anchor_lag
      - next_block_at
      - signature_policy
      - algorithm
      - standard
      - slh_dsa_present
      title: PQCAnchor
      description: "Cryptographic anchor binding an attestation to a PQC-signed block.\n\nPer spec.md §16.7, every attestation response carries an anchor that\nreferences the most recent COMPLETED PQC block. Consumers verify:\n\n  * Records 0..(block_index+1)*BLOCK_SIZE-1 are covered by the\n    ML-DSA-87 (and optionally SLH-DSA-SHA2-256f) signature at\n    block_index.\n  * The current attestation extends the chain anchor_lag records\n    beyond the last signed boundary; the next block signature will\n    fire when chain_length reaches next_block_at.\n  * Before the first block boundary (chain_length < BLOCK_SIZE),\n    block_index = -1 and signature_policy = \"pending\"; the anchor\n    object is still emitted so the response shape is stable.\n\nThis contract is load-bearing for external claim verification\n(DOE Genesis, CVP, LM SBIR, marketplace cert reviewers)."
    RiskCategory:
      type: string
      enum:
      - MINIMAL
      - LIMITED
      - HIGH
      - UNACCEPTABLE
      title: RiskCategory
      description: EU AI Act Annex III risk classification for AI systems.
    ScanRequest:
      properties:
        prompt:
          type: string
          maxLength: 10000
          minLength: 1
          title: Prompt
          description: Text to scan for prompt injection
        agent_id:
          anyOf:
          - type: string
            maxLength: 256
            pattern: ^[a-zA-Z0-9._@\-]+$
          - type: 'null'
          title: Agent Id
          description: Optional agent identifier
        context:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Context
          description: Optional context about the prompt source
      type: object
      required:
      - prompt
      title: ScanRequest
    ScanResponse:
      properties:
        scan_id:
          type: string
          title: Scan Id
        injection_detected:
          type: boolean
          title: Injection Detected
        confidence:
          type: number
          title: Confidence
        risk_level:
          type: string
          title: Risk Level
        latency_ms:
          type: number
          title: Latency Ms
        model_version:
          type: string
          title: Model Version
        truncated:
          type: boolean
          title: Truncated
        timestamp_utc:
          type: string
          title: Timestamp Utc
        hmac:
          type: string
          title: Hmac
      type: object
      required:
      - scan_id
      - injection_detected
      - confidence
      - risk_level
      - latency_ms
      - model_version
      - truncated
      - timestamp_utc
      - hmac
      title: ScanResponse
    SignupRequest:
      properties:
        agent_id:
          type: string
          maxLength: 256
          minLength: 1
          title: Agent Id
          description: The agent's identifier (required - this is how you're tracked)
        operator_email:
          type: string
          maxLength: 320
          title: Operator Email
          description: Optional operator email for account recovery
          default: ''
        operator_name:
          type: string
          maxLength: 256
          title: Operator Name
          description: Optional legal entity name
          default: ''
        referred_by:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Referred By
          description: Broker agent_id that referred this operator
      type: object
      required:
      - agent_id
      title: SignupRequest
      description: Agent self-serve signup request. agent_id is required; email/name optional.
    SignupResponse:
      properties:
        api_key:
          type: string
          title: Api Key
        tier:
          type: string
          title: Tier
          default: free
        monthly_limit:
          type: integer
          title: Monthly Limit
          default: 1000
        rate_limit_per_minute:
          type: integer
          title: Rate Limit Per Minute
          default: 10
        upgrade_url:
          type: string
          title: Upgrade Url
        payment_discovery_url:
          type: string
          title: Payment Discovery Url
        profile_url:
          type: string
          title: Profile Url
        usage:
          additionalProperties:
            type: string
          type: object
          title: Usage
          description: How to use the key (header name + curl example)
        contract_versions:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Contract Versions
          description: 'Surface version metadata for the contract this response participates in (issue #595). Optional + nullable so server can `exclude_none=True` from wire when omitted | preserves backwards-compat with strict (`extra=''forbid''`) SDK clients pinned to the pre-field schema.'
      type: object
      required:
      - api_key
      title: SignupResponse
      description: Returned once on successful signup. The api_key is shown once - store it.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    VerifyOutcomeRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
        intent_id:
          type: string
          maxLength: 256
          title: Intent Id
        binding_id:
          type: string
          maxLength: 256
          title: Binding Id
        actual_state:
          additionalProperties: true
          type: object
          title: Actual State
          description: The state after action execution
        tolerance:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Tolerance
          description: Acceptable deviation from goal state (0=exact, 1=any)
          default: 0.1
      type: object
      required:
      - agent_id
      - intent_id
      - binding_id
      - actual_state
      title: VerifyOutcomeRequest
      description: Verify that an action achieved its declared intent.
    VerifyOutcomeResponse:
      properties:
        verification_id:
          type: string
          title: Verification Id
        intent_id:
          type: string
          title: Intent Id
        status:
          $ref: '#/components/schemas/OutcomeStatus'
        achieved_percentage:
          type: number
          title: Achieved Percentage
        discrepancy:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Discrepancy
        evidence_hash:
          type: string
          title: Evidence Hash
        timestamp_utc:
          type: string
          title: Timestamp Utc
        contract_versions:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Contract Versions
          description: 'Surface version metadata for the contract this response participates in (issue #595). Optional + nullable so server can `exclude_none=True` from wire when omitted | preserves backwards-compat with strict (`extra=''forbid''`) SDK clients pinned to the pre-field schema.'
      type: object
      required:
      - verification_id
      - intent_id
      - status
      - achieved_percentage
      - evidence_hash
      - timestamp_utc
      title: VerifyOutcomeResponse
      description: Outcome verification result.
    VerifyRequest:
      properties:
        action_type:
          type: string
          maxLength: 128
          minLength: 1
          title: Action Type
          description: Type of action being verified (e.g., 'motor_command', 'api_call', 'transaction')
        action_payload:
          additionalProperties: true
          type: object
          title: Action Payload
          description: The action to verify - contents depend on action_type
        policy_context:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Policy Context
          description: Optional policy constraints (max values, allowed ranges, etc.)
        template_id:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Template Id
          description: Named policy template (e.g., 'robotics-arm', 'financial-transaction'). Merged with policy_context - agent-supplied values override template defaults.
        agent_id:
          type: string
          title: Agent Id
          description: Identifier of the requesting agent
        idempotency_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency Key
          description: Idempotency key for retry safety
        cmd_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Cmd Id
          description: Command ID for replay protection. Auto-generated by SDK if not provided. Server rejects duplicate cmd_ids within the replay window.
        risk_category:
          anyOf:
          - $ref: '#/components/schemas/RiskCategory'
          - type: 'null'
          description: EU AI Act risk classification (MINIMAL, LIMITED, HIGH, UNACCEPTABLE). Recorded in provenance for regulatory compliance tagging.
      type: object
      required:
      - action_type
      - action_payload
      - agent_id
      title: VerifyRequest
      description: Request to verify an action against policy bounds.
    VerifyResponse:
      properties:
        decision:
          $ref: '#/components/schemas/Decision'
        verification_id:
          type: string
          title: Verification Id
          description: Unique ID for this verification
        release_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Release Token
          description: Cryptographically signed release token (present for ALLOW and CONSTRAIN decisions). Submit the token alone to /governance/verify-token to confirm authenticity; the gateway performs the comparison server-side.
        applied_action:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Applied Action
          description: The action as it will be applied (may be constrained to bounds)
        policy_applied:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Policy Applied
          description: Policy constraints that were applied
        reason:
          type: string
          title: Reason
          description: Human/agent-readable reason for decision
          default: ''
        epoch:
          type: integer
          title: Epoch
          description: Provenance epoch of this decision
        provenance_hash:
          type: string
          title: Provenance Hash
          description: Hash-chain reference for this decision
        hash_prev:
          anyOf:
          - type: string
          - type: 'null'
          title: Hash Prev
          description: Previous hash in provenance chain
        timestamp_utc:
          type: string
          title: Timestamp Utc
        enforcement_mode:
          $ref: '#/components/schemas/EnforcementMode'
          description: Enforcement mode for this decision.
          default: enforce
        advisory_decision:
          anyOf:
          - $ref: '#/components/schemas/Decision'
          - type: 'null'
          description: Present only when enforcement_mode is 'advisory'.
        enrichment:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Enrichment
          description: AI-enriched decision context (powered by enterprise LLM). Present only for tiers with enrichment allowance. Contains explanation and compliance_note fields for auditor/operator consumption.
        contract_versions:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Contract Versions
          description: 'Surface version metadata for the contract this response participates in (issue #595). Optional + nullable so server can `exclude_none=True` from wire when omitted | preserves backwards-compat with strict (`extra=''forbid''`) SDK clients pinned to the pre-field schema.'
      type: object
      required:
      - decision
      - verification_id
      - epoch
      - provenance_hash
      title: VerifyResponse
      description: Signed verification decision.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Get a trial key via POST /signup. 1,000-call trial allowance.
tags:
- name: governance
  description: 'Public governance operations: verify, attest, bind, verify-outcome, and bundle. Successful operations return endpoint-specific evidence; provenance-capable operations append audit records.'
- name: signup
  description: Self-serve API key provisioning. No email or credit card required. 1,000-call trial allowance.
- name: shield
  description: 'Prompt injection detection. DeBERTa-v3 classifier with sub-second inference. Trial allowance: 10 scans/day per IP.'
- name: billing
  description: 'Payment surface discovery for clients before attempting a paid call.


    1. `GET /payment/health` - rail challenge and configuration status.

    2. `GET /payment/quote?endpoint=/path` - per-endpoint price across candidate rails.

    3. For generic paid agents, fetch a safe-method 402 challenge, then POST with a verified rail credential. Unpaid executable POST remains Delegation-gated.


    `GET /payment/discovery` aggregates rail status and quotes. `GET /payment/badge` returns a compact status badge payload. Discovery is cached and does not represent settlement, adoption, or revenue evidence.'
security:
- ApiKeyAuth: []
x-service-info:
  categories:
  - ai
  - security
  - compliance
  docs:
    homepage: https://governance.taskhawktech.com
    apiReference: https://governance.taskhawktech.com/openapi.json
    llms: https://governance.taskhawktech.com/for-agents.txt