{
  "openapi": "3.1.0",
  "info": {
    "title": "The MCP Census API",
    "description": "Public-evidence Preflight for Model Context Protocol servers. Select one exact canonical Census server name and receive PASS, REVIEW, or BLOCK under an immutable built-in policy. A PASS is not a security finding or install authorization.",
    "version": "2.0.0",
    "contact": { "email": "info@mcpcensus.com" }
  },
  "servers": [
    { "url": "https://api.mcpcensus.com", "description": "MCP Census API" }
  ],
  "paths": {
    "/v1/policies": {
      "get": {
        "operationId": "listPreflightPolicies",
        "summary": "Get the three immutable Preflight v1 policies and canonical ruleset",
        "responses": {
          "200": {
            "description": "Exact policy catalog",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyCatalog" } } }
          }
        }
      }
    },
    "/v1/preflight": {
      "post": {
        "operationId": "evaluateMcpServerPreflight",
        "summary": "Evaluate one exact MCP server under one built-in policy",
        "description": "Returns PASS, REVIEW, or BLOCK with ordered reasons, source facts and times, validity, reproducibility digests, and limitations. Anonymous calls must use refresh=never. Authenticated completed calls receive an account-scoped audit ID. A PASS does not authorize install or execution.",
        "security": [{}, { "ApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightInput" } } }
        },
        "responses": {
          "200": {
            "description": "Completed policy decision",
            "headers": {
              "x-tier": { "schema": { "type": "string", "enum": ["free", "registered", "pro"] }, "description": "Resolved quota tier" },
              "x-ratelimit-limit": { "schema": { "type": "integer" } },
              "x-ratelimit-remaining": { "schema": { "type": "integer" } }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightResult" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "description": "A current-liveness refresh is already in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "description": "Authenticated audit could not be recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/evaluations": {
      "get": {
        "operationId": "listPreflightEvaluations",
        "summary": "List up to 50 recent evaluations for the authenticated account",
        "description": "Newest first. Completed authenticated evaluations are retained for 90 days.",
        "security": [{ "ApiKey": [] }],
        "responses": {
          "200": { "description": "Account-scoped evaluation list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationList" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/evaluations/{id}": {
      "get": {
        "operationId": "getPreflightEvaluation",
        "summary": "Get one evaluation for the authenticated account",
        "security": [{ "ApiKey": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Random audit ID returned by an authenticated completed Preflight" }
        ],
        "responses": {
          "200": { "description": "Account-scoped evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationDetailResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/search": {
      "get": {
        "operationId": "searchMcpServers",
        "summary": "Search MCP servers and select an exact canonical name",
        "description": "Returns ranked candidates. Search output is not a Preflight decision.",
        "security": [{}, { "ApiKey": [] }],
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "description": "Keyword or partial server name" },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }
        ],
        "responses": {
          "200": { "description": "Ranked matches with evidence cards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/server": {
      "get": {
        "operationId": "getMcpServerEvidence",
        "summary": "Get one server evidence card by exact canonical name",
        "security": [{}, { "ApiKey": [] }],
        "parameters": [
          { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact canonical Census server name" }
        ],
        "responses": {
          "200": { "description": "Evidence card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCard" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "operationId": "getEcosystemStats",
        "summary": "Get ecosystem headline counts",
        "responses": { "200": { "description": "Current totals" } }
      }
    },
    "/v1/recent": {
      "get": {
        "operationId": "getRecentlyDiscoveredServers",
        "summary": "Get recently discovered MCP servers",
        "responses": { "200": { "description": "Newest servers by first_seen_at" } }
      }
    },
    "/v1/coverage": {
      "get": {
        "operationId": "getCoverageReport",
        "summary": "Get the public coverage and provenance report",
        "description": "Current census totals, source coverage, identity evidence, harvest state, and discovery pipeline context. A missing official row is not a claim that a vendor has no server anywhere.",
        "responses": { "200": { "description": "Coverage report" } }
      }
    },
    "/v1/watch": {
      "post": {
        "operationId": "createServerWatch",
        "summary": "Subscribe to observed changes for one MCP server",
        "security": [{ "ApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["server_name"],
                "properties": {
                  "server_name": { "type": "string" },
                  "webhook_url": { "type": "string", "format": "uri" },
                  "email": { "type": "string", "format": "email" },
                  "events": { "type": "array", "items": { "type": "string" } },
                  "label": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Watch created or updated" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "description": "Watch limit reached" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "get": {
        "operationId": "listServerWatches",
        "summary": "List active watches for the authenticated key",
        "security": [{ "ApiKey": [] }],
        "responses": { "200": { "description": "Watch list" }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      },
      "delete": {
        "operationId": "deleteServerWatch",
        "summary": "Unsubscribe one watch",
        "security": [{ "ApiKey": [] }],
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Unsubscribed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Account API key. Required for current-liveness refresh, evaluation history, and watches." }
    },
    "responses": {
      "BadRequest": { "description": "Closed input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "Missing, invalid, or revoked account API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Exact resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Burst, daily, refresh, or per-server cooldown limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["ok", "error"],
        "properties": {
          "ok": { "const": false },
          "error": { "type": "string" },
          "message": { "type": "string" },
          "retry_after": { "type": "integer" },
          "reset_at": { "type": "string", "format": "date-time" }
        }
      },
      "PreflightInput": {
        "type": "object",
        "additionalProperties": false,
        "required": ["server_name"],
        "properties": {
          "server_name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Exact canonical Census server name" },
          "policy_id": { "type": "string", "enum": ["builtin:baseline", "builtin:first-party", "builtin:strict"], "default": "builtin:baseline" },
          "refresh": { "type": "string", "enum": ["never", "if_stale"], "default": "never" }
        }
      },
      "PreflightEvidence": {
        "type": "object",
        "properties": {
          "source": { "type": "string" },
          "url": { "type": ["string", "null"], "format": "uri" },
          "value": {},
          "observed_at": { "type": ["string", "null"], "format": "date-time" },
          "attempted_at": { "type": ["string", "null"], "format": "date-time" },
          "freshness_enforced": { "type": "boolean" },
          "canonical_evidence_id": { "type": "string" }
        }
      },
      "PreflightReason": {
        "type": "object",
        "required": ["code", "result", "summary", "evidence"],
        "properties": {
          "code": { "type": "string" },
          "result": { "type": "string", "enum": ["pass", "review", "block", "context", "not_applicable", "unknown"] },
          "summary": { "type": "string" },
          "ecosystem": { "type": "string" },
          "artifact_id": { "type": "string" },
          "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/PreflightEvidence" } }
        }
      },
      "PreflightResult": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "decision", "decision_scope", "meaning", "server_name", "policy", "reasons", "facts", "facts_digest", "decision_input_digest", "engine_version", "evaluated_at", "valid_until", "audit_id", "audit_signed", "limitations"],
        "properties": {
          "ok": { "const": true },
          "decision": { "type": "string", "enum": ["PASS", "REVIEW", "BLOCK"] },
          "decision_scope": { "const": "public_evidence_policy" },
          "meaning": { "type": "string" },
          "server_name": { "type": "string" },
          "policy": {
            "type": "object",
            "additionalProperties": false,
            "required": ["id", "revision", "digest"],
            "properties": {
              "id": { "type": "string", "enum": ["builtin:baseline", "builtin:first-party", "builtin:strict"] },
              "revision": { "const": 1 },
              "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
            }
          },
          "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/PreflightReason" } },
          "facts": { "type": "object" },
          "facts_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
          "decision_input_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
          "engine_version": { "type": "string" },
          "evaluated_at": { "type": "string", "format": "date-time" },
          "valid_until": { "type": "string", "format": "date-time" },
          "audit_id": { "type": ["string", "null"], "format": "uuid" },
          "audit_signed": { "const": false },
          "limitations": { "type": "array", "items": { "type": "string" } }
        }
      },
      "PreflightPolicy": {
        "type": "object",
        "additionalProperties": false,
        "required": ["schema_version", "id", "revision", "ruleset_id", "ruleset_revision", "name", "identity_requirement", "hosted_liveness", "unknown_required", "findings"],
        "properties": {
          "schema_version": { "const": 1 },
          "id": { "type": "string", "enum": ["builtin:baseline", "builtin:first-party", "builtin:strict"] },
          "revision": { "const": 1 },
          "ruleset_id": { "const": "preflight-ruleset" },
          "ruleset_revision": { "const": 1 },
          "name": { "type": "string", "enum": ["baseline@1", "first-party@1", "strict@1"] },
          "identity_requirement": { "type": "string", "enum": ["any", "first_party"] },
          "hosted_liveness": { "type": "string", "enum": ["observe_only", "require_fresh_live"] },
          "max_liveness_age_hours": { "const": 48 },
          "unknown_required": { "type": "string", "enum": ["review", "block"] },
          "findings": {
            "type": "object",
            "additionalProperties": false,
            "required": ["brand_impersonation", "brand_claim_without_identity", "repo_gone", "repo_archived", "npm_package_missing", "pypi_package_missing", "npm_deprecated", "repo_no_push_6mo", "osv_package_advisory"],
            "properties": {
              "brand_impersonation": { "const": "block" },
              "brand_claim_without_identity": { "const": "review" },
              "repo_gone": { "const": "block" },
              "repo_archived": { "const": "review" },
              "npm_package_missing": { "const": "block" },
              "pypi_package_missing": { "const": "block" },
              "npm_deprecated": { "const": "block" },
              "repo_no_push_6mo": { "const": "review" },
              "osv_package_advisory": { "const": "review" }
            }
          }
        }
      },
      "PolicyCatalog": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "policies", "ruleset", "policy_digests", "audit_signed"],
        "properties": {
          "ok": { "const": true },
          "policies": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "$ref": "#/components/schemas/PreflightPolicy" } },
          "ruleset": { "type": "object" },
          "policy_digests": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" } },
          "audit_signed": { "const": false }
        }
      },
      "EvaluationSummary": {
        "type": "object",
        "required": ["audit_id", "server_name", "policy_id", "policy_revision", "decision", "decision_scope", "facts_digest", "policy_digest", "decision_input_digest", "engine_version", "evaluated_at", "valid_until", "audit_signed"],
        "properties": {
          "audit_id": { "type": "string", "format": "uuid" },
          "server_name": { "type": "string" },
          "policy_id": { "type": "string" },
          "policy_revision": { "type": "integer" },
          "decision": { "type": "string", "enum": ["PASS", "REVIEW", "BLOCK"] },
          "decision_scope": { "const": "public_evidence_policy" },
          "facts_digest": { "type": "string" },
          "policy_digest": { "type": "string" },
          "decision_input_digest": { "type": "string" },
          "engine_version": { "type": "string" },
          "evaluated_at": { "type": "string", "format": "date-time" },
          "valid_until": { "type": "string", "format": "date-time" },
          "audit_signed": { "const": false }
        }
      },
      "EvaluationList": {
        "type": "object",
        "required": ["ok", "count", "evaluations"],
        "properties": {
          "ok": { "const": true },
          "count": { "type": "integer", "minimum": 0, "maximum": 50 },
          "evaluations": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/EvaluationSummary" } }
        }
      },
      "EvaluationDetailResponse": {
        "type": "object",
        "required": ["ok", "evaluation"],
        "properties": {
          "ok": { "const": true },
          "evaluation": { "allOf": [
            { "$ref": "#/components/schemas/EvaluationSummary" },
            { "type": "object", "required": ["ruleset_id", "ruleset_revision", "facts", "reasons"], "properties": {
              "ruleset_id": { "const": "preflight-ruleset" },
              "ruleset_revision": { "const": 1 },
              "facts": { "type": "object" },
              "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/PreflightReason" } }
            } }
          ] }
        }
      },
      "HealthCard": {
        "type": "object",
        "properties": {
          "server_name": { "type": "string" },
          "health": { "type": "string", "enum": ["healthy", "issues", "unknown"] },
          "health_problems": { "type": "array", "items": { "type": "string" } },
          "verified": { "type": "boolean", "description": "Enough applicable registry and distribution surface is confirmed under the current published method. This is not first-party identity or a security finding." },
          "gh_stars": { "type": ["integer", "null"] },
          "months_since_push": { "type": ["number", "null"] },
          "gh_archived": { "type": ["boolean", "null"] },
          "npm_deprecated": { "type": ["boolean", "null"] },
          "name_collision_count": { "type": "integer" },
          "registry_status": { "type": "string" }
        }
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "count": { "type": "integer" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/HealthCard" } }
        }
      }
    }
  }
}