{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentCaliper API",
    "version": "0.2.0",
    "description": "Registry information, an x402-paid change brief, and Release Guard fulfillment. The Pages review deployment uses a fixed snapshot and simulated payments. Evidence you paste into the workbench is measured in your browser."
  },
  "servers": [{ "url": "/" }],
  "paths": {
    "/v1/catalog": {
      "get": {
        "operationId": "readCatalog",
        "responses": {
          "200": { "description": "Free resources, products, and active checkout modes.", "content": {
            "application/json": { "schema": { "type": "object", "required": ["format", "free", "products", "openapi", "guide"],
              "properties": { "format": { "const": "agentcaliper.catalog.v1" }, "free": { "type": "array", "items": { "type": "object" } },
                "products": { "type": "array", "items": { "type": "object" } }, "openapi": { "type": "string" }, "guide": { "type": "string" },
                "environment": { "const": "pages-demo" } } } }
          } }
        }
      }
    },
    "/v1/registry/brief": {
      "get": {
        "operationId": "previewRegistryBrief",
        "description": "Free coverage and sample. Use the returned path to request the immutable full brief. A quote is free to inspect.",
        "responses": {
          "200": { "description": "Fresh brief preview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BriefPreview" } } } },
          "503": { "description": "No fresh brief available." }
        }
      }
    },
    "/v1/briefs/{id}": {
      "get": {
        "operationId": "readPaidRegistryBrief",
        "description": "x402 v2 exact payment. GET without a signature to receive the quote. A successful settlement returns the fixed brief and a receipt. Reuse the identical authorization for recovery.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } },
          { "name": "Payment-Signature", "in": "header", "required": false, "schema": { "type": "string", "contentEncoding": "base64" } }
        ],
        "responses": {
          "200": { "description": "Paid registry brief.", "headers": {
            "Payment-Response": { "schema": { "type": "string", "contentEncoding": "base64" } }
          }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryBrief" } } } },
          "400": { "description": "Invalid authorization header or terms." },
          "402": { "description": "Payment required or authorization declined.", "headers": {
            "Payment-Required": { "schema": { "type": "string", "contentEncoding": "base64" } }
          } },
          "404": { "description": "Unknown or expired brief." },
          "409": { "description": "Authorization is already bound to another request." },
          "429": { "description": "Verification or settlement limit reached." },
          "503": { "description": "Checkout unavailable or settlement pending." }
        }
      }
    },
    "/v1/kit/checkout": {
      "post": {
        "operationId": "startReleaseGuardCheckout",
        "description": "Create or resume checkout for the Release Guard Kit. Store the random ID as a private recovery credential.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object",
          "required": ["id"], "properties": { "id": { "type": "string", "format": "uuid" } } } } } },
        "responses": {
          "200": { "description": "Hosted checkout URL or the return page for an order already paid.", "content": {
            "application/json": { "schema": { "type": "object", "required": ["ordered", "url", "mode"],
              "properties": { "ordered": { "type": "boolean" }, "url": { "type": "string" }, "mode": { "type": "string" } } } }
          } },
          "410": { "description": "The order expired." },
          "429": { "description": "Checkout start limit reached." },
          "503": { "description": "Checkout temporarily unavailable." }
        }
      }
    },
    "/v1/kit/orders/{id}": {
      "get": {
        "operationId": "readReleaseGuardOrder",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "Payment and fulfillment status.", "content": {
            "application/json": { "schema": { "type": "object", "required": ["paid", "expired", "mode", "download"],
              "properties": { "paid": { "type": "boolean" }, "expired": { "type": "boolean" }, "mode": { "type": "string" },
                "download": { "type": ["string", "null"] } } } }
          } },
          "404": { "description": "Order unknown." }
        }
      }
    },
    "/v1/kit/orders/{id}/download": {
      "get": {
        "operationId": "downloadReleaseGuardKit",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "The purchased kit, or a sample ZIP when using the public demo.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } },
          "402": { "description": "Order awaiting payment." },
          "404": { "description": "Order unknown." }
        }
      }
    },
    "/v1/demo/brief-payment": {
      "post": {
        "operationId": "simulateBriefAuthorization",
        "description": "Demo environments only. Returns a synthetic authorization for a current demo brief. Encode the payment object as Base64 UTF-8 JSON for Payment-Signature.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object",
          "required": ["id"], "properties": { "id": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } },
        "responses": {
          "200": { "description": "Synthetic payment data.", "content": {
            "application/json": { "schema": { "type": "object", "required": ["demo", "payment"],
              "properties": { "demo": { "const": true }, "payment": { "type": "object" } } } }
          } },
          "404": { "description": "Demo disabled or brief unknown." }
        }
      }
    },
    "/v1/demo/kit-pay": {
      "post": {
        "operationId": "simulateKitPayment",
        "description": "Demo environments only. Start an order via /v1/kit/checkout before calling this route. On Pages, return the order cookie set by checkout and save its replacement from this response.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object",
          "required": ["id"], "properties": { "id": { "type": "string", "format": "uuid" } } } } } },
        "responses": {
          "200": { "description": "Simulated payment completed.", "content": {
            "application/json": { "schema": { "type": "object", "required": ["demo", "paid"],
              "properties": { "demo": { "const": true }, "paid": { "const": true } } } }
          } },
          "404": { "description": "Demo disabled or order unknown." }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "readHealth",
        "responses": {
          "200": { "description": "The server is ready.", "content": { "application/json": {
            "schema": { "type": "object", "required": ["status", "local"], "properties": {
              "status": { "const": "ok" }, "local": { "type": "boolean" }, "environment": { "const": "pages-demo" }
            } }
          } } }
        }
      }
    },
    "/api/registry": {
      "get": {
        "operationId": "readMcpRegistrySnapshot",
        "responses": {
          "200": { "description": "A bounded recent listing sample from the official MCP Registry.", "content": { "application/json": {
            "schema": { "$ref": "#/components/schemas/RegistrySnapshot" }
          } } },
          "503": { "description": "A registry snapshot is unavailable.", "content": { "application/json": {
            "schema": { "type": "object", "required": ["ready", "enabled", "error"], "properties": {
              "ready": { "const": false }, "enabled": { "type": "boolean" }, "error": { "type": "string" }
            } }
          } } }
        }
      }
    },
    "/api/fixtures/x402": {
      "get": {
        "operationId": "readSyntheticPaymentChallenge",
        "responses": {
          "402": {
            "description": "Synthetic x402 v2 challenge. This fixture accepts no payment.",
            "headers": { "Payment-Required": { "schema": { "type": "string", "contentEncoding": "base64" } } },
            "content": { "application/json": { "schema": { "type": "object", "required": ["fixture", "message"],
              "properties": { "fixture": { "const": true }, "message": { "type": "string" } }
            } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BriefPreview": {
        "type": "object",
        "required": ["ready", "id", "updatedAt", "source", "scope", "profileCount", "sample", "price", "path", "paymentMode"],
        "properties": {
          "ready": { "const": true }, "id": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" },
          "source": { "type": "string", "format": "uri" }, "scope": { "type": "string" },
          "profileCount": { "type": "integer" }, "transportDifferences": { "type": "integer" },
          "sample": { "type": "array", "items": { "type": "object" } },
          "price": { "type": "object", "properties": { "amount": { "const": "0.01" }, "currency": { "const": "USDC" } } },
          "path": { "type": "string" }, "paymentMode": { "enum": ["demo", "off", "base", "base-sepolia"] },
          "dataMode": { "const": "frozen-preview" }
        }
      },
      "RegistryBrief": {
        "type": "object",
        "required": ["id", "format", "scope", "publishedAt", "coverage", "source", "profiles", "interpretation"],
        "properties": {
          "id": { "type": "string" }, "format": { "const": "agentcaliper.registry-brief.v1" }, "scope": { "type": "string" },
          "publishedAt": { "type": "string", "format": "date-time" }, "coverage": { "type": "object" },
          "source": { "type": "string", "format": "uri" }, "interpretation": { "type": "string" },
          "dataMode": { "const": "frozen-preview" },
          "profiles": { "type": "array", "items": { "type": "object", "required": ["name", "observedAt", "source", "versions", "summary", "truncated"],
            "properties": {
              "name": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" },
              "source": { "type": "string", "format": "uri" }, "truncated": { "type": "boolean" },
              "summary": { "type": "object" }, "versions": { "type": "array", "items": { "type": "object" } }
            } } }
        }
      },
      "RegistrySnapshot": {
        "type": "object",
        "required": ["syncedAt", "windowDays", "truncated", "stale", "entries"],
        "properties": {
          "syncedAt": { "type": "string", "format": "date-time" },
          "windowDays": { "type": "integer" },
          "truncated": { "type": "boolean" },
          "stale": { "type": "boolean" },
          "dataMode": { "const": "frozen-preview" },
          "entries": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "version", "updatedAt", "transports"],
              "properties": {
                "name": { "type": "string" },
                "version": { "type": "string" },
                "updatedAt": { "type": "string", "format": "date-time" },
                "transports": { "type": "array", "items": { "type": "string" } }
              }
            }
          }
        }
      }
    }
  }
}
