{
  "openapi": "3.1.0",
  "info": {
    "title": "AffixIO Verification API",
    "version": "1.4.2",
    "description": "Stateless verification infrastructure returning signed allow or deny outcomes. Zero-knowledge circuit proofs, Merkle audit anchoring, and post-quantum attestation paths. Base URL: https://api.affix-io.com. Public specification for integration planning. Authenticated endpoints require a scoped API key.",
    "contact": {
      "name": "AffixIO",
      "url": "https://www.affix-io.com/contact"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.affix-io.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.affix-io.com",
      "description": "Production API"
    }
  ],
  "tags": [
    { "name": "Health", "description": "Service health and circuit readiness" },
    { "name": "Auth", "description": "API key validation" },
    { "name": "Verify", "description": "Eligibility and identity verification" },
    { "name": "Circuits", "description": "Zero-knowledge Noir circuit prove and verify" },
    { "name": "Merkle", "description": "Append-only audit Merkle tree" }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "tags": ["Health"],
        "summary": "Health check",
        "description": "Returns service status, circuit readiness, and current Merkle root context.",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service healthy",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/auth/check": {
      "get": {
        "tags": ["Auth"],
        "summary": "Validate API key",
        "security": [{ "BearerAuth": [] }, { "ApiKeyAuth": [] }],
        "responses": {
          "200": {
            "description": "Key accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "service": { "type": "string" }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid or missing credentials" }
        }
      }
    },
    "/v1/verify": {
      "post": {
        "tags": ["Verify"],
        "summary": "Eligibility verification",
        "description": "Evaluate identifier against policy and return allow or deny with optional signed attestation.",
        "security": [{ "BearerAuth": [] }, { "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EligibilityRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed verdict",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VerdictResponse" }
              }
            }
          }
        }
      }
    },
    "/api/demo/identity-verify": {
      "post": {
        "tags": ["Verify"],
        "summary": "Identity rules verification (demo)",
        "description": "Evaluate records against identity rules and return a Noir-backed proof with allow or deny.",
        "security": [{ "BearerAuth": [] }, { "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/IdentityVerifyRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Verification result with proof metadata" }
        }
      }
    },
    "/api/demo/circuit-prove": {
      "post": {
        "tags": ["Circuits"],
        "summary": "Generate zero-knowledge proof",
        "security": [{ "BearerAuth": [] }, { "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CircuitProveRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Proof generated" }
        }
      }
    },
    "/api/demo/circuit-verify": {
      "post": {
        "tags": ["Circuits"],
        "summary": "Verify zero-knowledge proof",
        "security": [{ "BearerAuth": [] }, { "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CircuitVerifyRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Verification result" }
        }
      }
    },
    "/v1/circuits/{circuitId}/verify": {
      "post": {
        "tags": ["Circuits"],
        "summary": "Verify circuit by ID",
        "security": [{ "BearerAuth": [] }, { "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "circuitId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "example": "yesno" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CircuitVerifyRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Circuit verification result" }
        }
      }
    },
    "/v1/circuits": {
      "get": {
        "tags": ["Circuits"],
        "summary": "List available circuits",
        "responses": {
          "200": { "description": "Circuit catalogue" }
        }
      }
    },
    "/v1/merkle/root": {
      "get": {
        "tags": ["Merkle"],
        "summary": "Current Merkle root",
        "responses": {
          "200": { "description": "Root hash and leaf count" }
        }
      }
    },
    "/v1/merkle/leaves": {
      "get": {
        "tags": ["Merkle"],
        "summary": "List audit leaves",
        "parameters": [
          { "name": "offset", "in": "query", "schema": { "type": "integer" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Paginated leaf list" }
        }
      }
    },
    "/v1/merkle/proof/{digest}": {
      "get": {
        "tags": ["Merkle"],
        "summary": "Merkle inclusion proof",
        "parameters": [
          {
            "name": "digest",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "description": "64-char hex proof digest" }
          }
        ],
        "responses": {
          "200": { "description": "Inclusion proof steps" }
        }
      }
    },
    "/v1/merkle/verify-proof": {
      "post": {
        "tags": ["Merkle"],
        "summary": "Verify Merkle inclusion proof",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/MerkleVerifyRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Proof valid or invalid" }
        }
      }
    },
    "/api/governance-stats": {
      "get": {
        "tags": ["Merkle"],
        "summary": "Governance and audit statistics",
        "responses": {
          "200": { "description": "Leaf counts, circuit breakdown, recent activity" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer <api_key>"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "ok" },
          "service": { "type": "string", "example": "affix-api" },
          "circuits": { "type": "boolean" },
          "engine": { "type": "string", "example": "noir+barretenberg" },
          "merkle_root": { "type": "string" },
          "merkle_leaf_count": { "type": "integer" }
        }
      },
      "EligibilityRequest": {
        "type": "object",
        "required": ["identifier"],
        "properties": {
          "identifier": { "type": "string", "minLength": 8 },
          "sector": { "type": "string" },
          "requestAttestation": { "type": "boolean", "description": "Request post-quantum signed attestation on response" }
        }
      },
      "IdentityVerifyRequest": {
        "type": "object",
        "required": ["records"],
        "properties": {
          "records": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "source_records": { "type": "array", "items": { "type": "object" } },
          "rules": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityRule" } },
          "requestAttestation": { "type": "boolean" },
          "sector": { "type": "string" }
        }
      },
      "IdentityRule": {
        "type": "object",
        "properties": {
          "field": { "type": "string" },
          "operator": { "type": "string", "enum": ["equals", "not_equals", "nonempty"] },
          "value": { "type": "string" },
          "mapsTo": { "type": "string" }
        }
      },
      "CircuitProveRequest": {
        "type": "object",
        "properties": {
          "circuit_id": { "type": "string", "default": "yesno" },
          "fields": { "type": "object", "additionalProperties": true },
          "records": { "type": "array", "items": { "type": "object" } },
          "rules": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityRule" } },
          "requestAttestation": { "type": "boolean" },
          "sector": { "type": "string" }
        }
      },
      "CircuitVerifyRequest": {
        "type": "object",
        "required": ["proof"],
        "properties": {
          "proof": { "type": "string", "description": "Hex-encoded proof" },
          "requestAttestation": { "type": "boolean" },
          "sector": { "type": "string" }
        }
      },
      "MerkleVerifyRequest": {
        "type": "object",
        "properties": {
          "leaf": { "type": "string" },
          "root": { "type": "string" },
          "proof": { "type": "array", "items": { "type": "string" } }
        }
      },
      "VerdictResponse": {
        "type": "object",
        "properties": {
          "proof_id": { "type": "string" },
          "valid": { "type": "boolean" },
          "verified": { "type": "boolean" },
          "decision": { "type": "string", "enum": ["yes", "no"] },
          "proof_digest": { "type": "string" },
          "proof_ref": { "type": "string" },
          "circuit_id": { "type": "string" },
          "attestation": { "type": "object", "description": "Present when requestAttestation is true" }
        }
      }
    }
  },
  "externalDocs": {
    "description": "AffixIO developer documentation",
    "url": "https://www.affix-io.com/docs"
  }
}