{
  "openapi": "3.0.0",
  "info": {
    "title": "QnEvt Agent Proof API",
    "version": "2.0.0",
    "description": "Make zero-knowledge cryptographically verifiable decisions (shuffling, sampling, selections) using a recorded entropy source. Defaults to server_csprng via auto; physical entropy is available when explicitly requested."
  },
  "servers": [
    {
      "url": "https://qnevt.com",
      "description": "Production"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local development"
    }
  ],
  "paths": {
    "/api/public/proofs": {
      "get": {
        "summary": "List recent public proofs",
        "description": "Returns the 50 most recent public verifiable random decision proofs.",
        "responses": {
          "200": {
            "description": "A list of recent public proofs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicProofListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "operationId": "listPublicProofs"
      }
    },
    "/api/agent/fair-select": {
      "post": {
        "security": [
          {},
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Fairly select items from a list (fair_select)",
        "description": "Generates a verifiable_random_decision proof. Performs a deterministic selection (Fisher-Yates or independent sampling) using the requested entropy source. Returns the selection along with a full cryptographic proof. Public proof material includes entropy_hex by design so verifiers can recompute the decision; do not treat public proofs as secret material.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "options": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 2,
                    "maxItems": 256,
                    "description": "List of options to choose from"
                  },
                  "count": {
                    "type": "integer",
                    "default": 1,
                    "description": "Number of items to select"
                  },
                  "allow_duplicates": {
                    "type": "boolean",
                    "default": false,
                    "description": "If true, samples with replacement. If false, samples without replacement."
                  },
                  "context": {
                    "type": "string",
                    "description": "Optional business context or prompt string bound to the decision.",
                    "maxLength": 500
                  },
                  "entropy_source": {
                    "type": "string",
                    "enum": ["auto", "server_csprng", "physical"],
                    "default": "auto",
                    "description": "Source of entropy. 'physical' strictly requires hardware physical entropy. 'server_csprng' uses local crypto.randomBytes. 'auto' defaults to 'server_csprng'."
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "public",
                      "private"
                    ],
                    "default": "public",
                    "description": "Whether the proof is hidden from the public timeline."
                  }
                },
                "required": [
                  "options"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful selection",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentDecisionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "operationId": "createFairSelection"
      }
    },
    "/api/agent/tie-break": {
      "post": {
        "security": [
          {},
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Break a tie between options (tie_break)",
        "description": "Alias for fair_select with count=1. Generates a verifiable_random_decision proof. Selects exactly one item deterministically using the requested entropy source. Public proof material includes entropy_hex by design so verifiers can recompute the decision; do not treat public proofs as secret material.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "options": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 2,
                    "maxItems": 256,
                    "description": "List of tied options to choose between"
                  },
                  "context": {
                    "type": "string",
                    "description": "Optional business context or prompt string bound to the decision.",
                    "maxLength": 500
                  },
                  "entropy_source": {
                    "type": "string",
                    "enum": ["auto", "server_csprng", "physical"],
                    "default": "auto",
                    "description": "Source of entropy. 'physical' strictly requires hardware physical entropy. 'server_csprng' uses local crypto.randomBytes. 'auto' defaults to 'server_csprng'."
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "public",
                      "private"
                    ],
                    "default": "public",
                    "description": "Whether the proof is hidden from the public timeline."
                  }
                },
                "required": [
                  "options"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful tie-break",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentDecisionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "operationId": "createTieBreak"
      }
    },
    "/api/agent/audit-sample": {
      "post": {
        "security": [
          {},
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Sample data for auditing (audit_sampling)",
        "description": "Generates a verifiable_random_decision proof. Selects a sample from a provided dataset (without replacement) using the requested entropy source. Public proof material includes entropy_hex by design so verifiers can recompute the decision; do not treat public proofs as secret material. Use visibility=\"private\" for sensitive datasets.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "description": "Array of items or records to sample from. Max 1000 items. Note: items can be any valid JSON type, but when verifying the proof, the exact same types and structure must be provided."
                  },
                  "records": {
                    "type": "array",
                    "description": "Alias for items."
                  },
                  "sample_size": {
                    "type": "integer",
                    "default": 1,
                    "description": "Number of items to sample without replacement."
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "public",
                      "private"
                    ],
                    "default": "public",
                    "description": "Unified proof visibility field. Use private to hide raw dataset fields from public proof material."
                  },
                  "context": {
                    "type": "string",
                    "description": "Optional business context or prompt string bound to the decision.",
                    "maxLength": 500
                  },
                  "entropy_source": {
                    "type": "string",
                    "enum": ["auto", "server_csprng", "physical"],
                    "default": "auto",
                    "description": "Source of entropy. 'physical' strictly requires hardware physical entropy. 'server_csprng' uses local crypto.randomBytes. 'auto' defaults to 'server_csprng'."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful sampling",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentDecisionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "operationId": "createAuditSample"
      }
    },
    "/api/agent/verify-proof": {
      "post": {
        "security": [
          {},
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Verify a random decision proof",
        "description": "Re-executes the deterministic selection process to verify that the specified output was genuinely selected from the inputs without bias or tampering.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/VerifyProofRequest"
                  }
                ],
                "required": [
                  "proof_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyProofResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "operationId": "verifyAgentProof"
      }
    },
    "/api/agent/proofs": {
      "get": {
        "security": [
          {},
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List agent decision proofs",
        "description": "Lists verifiable random decision proofs visible to the caller. Anonymous callers see public proofs; authenticated callers also see their own private proofs. Supports pagination and decision_type filtering.",
        "operationId": "listAgentProofs",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "decision_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "fair_select",
                "tie_break",
                "audit_sampling"
              ]
            }
          },
          {
            "name": "created_before",
            "in": "query",
            "required": false,
            "description": "Cursor for pagination. Only return proofs created before this ISO8601 timestamp.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Visible proof history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentProofListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/api/agent/proofs/{id}": {
      "get": {
        "security": [
          {},
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Fetch a proof by ID",
        "description": "Retrieves a proof record by public_id. Private proofs are sanitized: original input_commitment/public_items are omitted and input_private is true.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The public_id of the proof to fetch"
          }
        ],
        "responses": {
          "200": {
            "description": "Proof record found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FetchProofResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "operationId": "getAgentProof"
      }
    },
    "/api/agent/proofs/{id}/verify": {
      "post": {
        "security": [
          {},
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Cryptographically verify a proof",
        "description": "Performs zero-knowledge resimulation of the random decision using the originally recorded entropy to ensure the result is unbiased and untampered.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The public_id of the proof to verify"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyProofRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyProofResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "operationId": "verifyAgentProofById"
      }
    },
    "/mcp": {
      "post": {
        "summary": "QnEvt MCP Streamable HTTP transport",
        "description": "Model Context Protocol Streamable HTTP endpoint. Supports initialize, tools/list, and tools/call without local MCP installation. Clients must send Accept: application/json, text/event-stream.",
        "operationId": "callMcpStreamableHttp",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "application/json, text/event-stream"
            },
            "description": "MCP Streamable HTTP requires clients to accept both application/json and text/event-stream."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpJsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "MCP JSON-RPC response or streamable response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpJsonRpcResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-sent event stream carrying MCP JSON-RPC response events."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Optional. Bearer API key from developer console. Without a key, rate limits are 5 req/min per IP."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Machine-readable or human-readable error message."
          },
          "valid": {
            "type": "boolean",
            "description": "Present on verification endpoints when a failed verification is returned as JSON."
          }
        },
        "required": [
          "error"
        ]
      },
      "EntropyMaterial": {
        "type": "object",
        "properties": {
          "requested_source": {
            "type": "string",
            "enum": ["auto", "server_csprng", "physical"],
            "example": "auto"
          },
          "resolved_source": {
            "type": "string",
            "enum": ["server_csprng", "physical"],
            "example": "physical"
          },
          "physical_entropy_used": {
            "type": "boolean",
            "example": true
          },
          "algorithm": {
            "type": "string",
            "example": "QnEvt Physical Entropy Stream"
          },
          "reveal_mode": {
            "type": "string",
            "example": "full_replay_material"
          },
          "entropy_hex": {
            "type": "string",
            "pattern": "^[a-f0-9]+$",
            "description": "Entropy bytes consumed by the deterministic sampler, encoded as hex."
          },
          "final_entropy_hash": {
            "type": "string",
            "description": "SHA-256 hash of the consumed entropy."
          },
          "batch_id": {
            "type": "string",
            "nullable": true,
            "description": "The identifier of the physical entropy batch used, or null for pseudo-random."
          },
          "node_signature": {
            "type": "string",
            "nullable": true,
            "description": "The node signature of the physical entropy batch used, or null for pseudo-random."
          }
        },
        "required": [
          "requested_source",
          "resolved_source",
          "physical_entropy_used",
          "algorithm",
          "reveal_mode",
          "entropy_hex",
          "final_entropy_hash",
          "batch_id",
          "node_signature"
        ]
      },
      "ProofSignatures": {
        "type": "object",
        "properties": {
          "node": {
            "type": "string",
            "description": "Entropy batch/node signature."
          },
          "server": {
            "type": "string",
            "description": "Server HMAC signature over proof_id, input hash, output hash, and decision type."
          },
          "client": {
            "type": "string",
            "description": "Legacy client signature, present only on older proof types."
          }
        }
      },
      "AgentProofSummary": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "example": "2.0"
          },
          "proof_type": {
            "type": "string",
            "enum": [
              "verifiable_random_decision"
            ]
          },
          "decision_type": {
            "type": "string",
            "enum": [
              "fair_select",
              "tie_break",
              "audit_sampling"
            ]
          },
          "input_commitment": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "SHA-256 hash of the canonical input object."
          },
          "algorithm": {
            "type": "string"
          },
          "canonicalization": {
            "type": "string",
            "example": "QnEvt Canonical JSON v1"
          },
          "entropy_material": {
            "$ref": "#/components/schemas/EntropyMaterial"
          },
          "result_hash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "signatures": {
            "$ref": "#/components/schemas/ProofSignatures"
          }
        },
        "required": [
          "version",
          "proof_type",
          "decision_type",
          "input_commitment",
          "algorithm",
          "canonicalization",
          "entropy_material",
          "result_hash",
          "signatures"
        ]
      },
      "AgentDecisionProof": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AgentProofSummary"
          }
        ],
        "description": "Proof object returned directly by decision creation endpoints."
      },
      "VerifyInstructions": {
        "type": "object",
        "properties": {
          "endpoint": {
            "type": "string",
            "example": "/api/agent/verify-proof"
          },
          "required_payload": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "endpoint",
          "required_payload"
        ]
      },
      "AgentDecisionResponse": {
        "type": "object",
        "properties": {
          "selected": {
            "type": "array",
            "items": {},
            "description": "Selected option(s) or record(s)."
          },
          "proof_id": {
            "type": "string"
          },
          "proof_url": {
            "type": "string",
            "format": "uri"
          },
          "proof": {
            "$ref": "#/components/schemas/AgentDecisionProof"
          },
          "verify": {
            "$ref": "#/components/schemas/VerifyInstructions"
          },
          "proof_json_url": {
            "type": "string",
            "format": "uri",
            "description": "Machine-readable JSON proof URL."
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          }
        },
        "required": [
          "selected",
          "proof_id",
          "proof_url",
          "proof_json_url",
          "proof",
          "verify"
        ]
      },
      "StoredProofMaterials": {
        "type": "object",
        "properties": {
          "entropy_hex": {
            "type": "string",
            "pattern": "^[a-f0-9]+$"
          },
          "decision_type": {
            "type": "string",
            "enum": [
              "fair_select",
              "tie_break",
              "audit_sampling"
            ]
          },
          "requested_source": {
            "type": "string",
            "enum": ["auto", "server_csprng", "physical"]
          },
          "resolved_source": {
            "type": "string",
            "enum": ["server_csprng", "physical"]
          },
          "physical_entropy_used": {
            "type": "boolean"
          },
          "decision_params": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer"
              },
              "allow_duplicates": {
                "type": "boolean"
              },
              "context": {
                "type": "string"
              }
            },
            "additionalProperties": true
          },
          "canonicalization": {
            "type": "string"
          },
          "input_private": {
            "type": "boolean"
          },
          "input_commitment": {
            "type": "object",
            "additionalProperties": true,
            "description": "Public canonical input object. Omitted for private proofs."
          },
          "public_items": {
            "type": "array",
            "items": {},
            "description": "Public audit dataset. Omitted for private proofs."
          },
          "selected_result": {
            "type": "array",
            "items": {},
            "description": "Public selected result. Omitted for private proofs."
          },
          "audit_params": {
            "type": "object",
            "properties": {
              "sample_size": {
                "type": "integer"
              },
              "context": {
                "type": "string"
              },
              "visibility": {
                "type": "string",
                "enum": [
                  "public",
                  "private"
                ]
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": true
      },
      "StoredProof": {
        "type": "object",
        "properties": {
          "public_id": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "proof_type": {
            "type": "string"
          },
          "algorithm_version": {
            "type": "string"
          },
          "input_hash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "entropy_batch": {
            "type": "string"
          },
          "mixing_algorithm": {
            "type": "string"
          },
          "output_hash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "proof_materials": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/StoredProofMaterials"
              },
              {
                "type": "string",
                "description": "JSON-encoded StoredProofMaterials, returned by some deployments for backwards compatibility."
              }
            ]
          },
          "node_health_summary": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": true
              },
              {
                "type": "string"
              }
            ],
            "nullable": true
          },
          "signature": {
            "type": "string"
          },
          "node_signature": {
            "type": "string"
          },
          "server_signature": {
            "type": "string"
          },
          "signatures": {
            "$ref": "#/components/schemas/ProofSignatures"
          },
          "is_hidden": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "proof_url": {
            "type": "string",
            "format": "uri"
          },
          "proof_json_url": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "public_id",
          "proof_type",
          "input_hash",
          "output_hash"
        ]
      },
      "FetchProofResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "proof": {
            "$ref": "#/components/schemas/StoredProof"
          }
        },
        "required": [
          "ok",
          "proof"
        ]
      },
      "VerifyProofRequest": {
        "type": "object",
        "properties": {
          "proof_id": {
            "type": "string",
            "description": "Required for /api/agent/verify-proof. Path id is used for /api/agent/proofs/{id}/verify."
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Original options for fair_select or tie_break. Values are normalized to strings by the API."
          },
          "items": {
            "type": "array",
            "items": {},
            "description": "Original audit dataset."
          },
          "records": {
            "type": "array",
            "items": {},
            "description": "Alias for items."
          },
          "count": {
            "type": "integer",
            "default": 1
          },
          "sample_size": {
            "type": "integer",
            "default": 1
          },
          "allow_duplicates": {
            "type": "boolean",
            "default": false
          },
          "context": {
            "type": "string"
          },
          "selected": {
            "type": "array",
            "items": {},
            "description": "Optional selected result to compare against the reconstructed result."
          }
        }
      },
      "VerifyProofResponse": {
        "type": "object",
        "properties": {
          "valid": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "simulatedResult": {
            "type": "array",
            "items": {},
            "description": "Reconstructed selected array. Omitted for private proofs to avoid leaking the result."
          }
        },
        "required": [
          "valid"
        ]
      },
      "PublicProofListResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "proofs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "public_id": {
                  "type": "string"
                },
                "proof_type": {
                  "type": "string"
                },
                "decision_type": {
                  "type": "string"
                },
                "mixing_algorithm": {
                  "type": "string"
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          }
        },
        "required": [
          "ok",
          "proofs"
        ]
      },
      "AgentProofListResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "has_more": {
            "type": "boolean",
            "description": "Whether more proofs exist beyond the current page."
          },
          "decision_type": {
            "type": "string",
            "enum": [
              "fair_select",
              "tie_break",
              "audit_sampling"
            ],
            "nullable": true
          },
          "proofs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StoredProof"
            }
          }
        },
        "required": [
          "ok",
          "limit",
          "offset",
          "proofs"
        ]
      },
      "McpJsonRpcRequest": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ],
            "nullable": true
          },
          "method": {
            "type": "string",
            "example": "tools/list"
          },
          "params": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "jsonrpc",
          "method"
        ]
      },
      "McpJsonRpcResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ],
            "nullable": true
          },
          "result": {
            "type": "object",
            "additionalProperties": true
          },
          "error": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid authentication credentials",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "QuotaExceeded": {
        "description": "Monthly API quota exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "Service unavailable, usually because database/auth service is unavailable or the entropy reservoir is temporarily empty. Entropy-empty responses may include Retry-After.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "string"
            },
            "description": "Seconds to wait before retrying when physical entropy is temporarily unavailable."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Proof not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}