{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/0xinsider-com/json-schema/0xinsider-com-api-discovery-schema.json",
  "title": "ApiDiscovery",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/0xinsider-com-system-api-openapi.yml#/components/schemas/ApiDiscovery",
  "type": "object",
  "required": [
    "api_base_url",
    "docs_url",
    "openapi_url",
    "health_url",
    "authentication",
    "protected_resource_metadata_url",
    "authenticated_routes"
  ],
  "properties": {
    "api_base_url": {
      "type": "string",
      "format": "uri",
      "description": "Canonical API origin for public V1 requests."
    },
    "docs_url": {
      "type": "string",
      "format": "uri",
      "description": "Full agent-readable API reference."
    },
    "openapi_url": {
      "type": "string",
      "format": "uri",
      "description": "Canonical web-origin OpenAPI JSON document."
    },
    "health_url": {
      "type": "string",
      "format": "uri",
      "description": "Unauthenticated API health endpoint."
    },
    "authentication": {
      "type": "string",
      "const": "Bearer API key required for data endpoints; discovery (/api/v1), health, coverage (/api/v1/coverage, and its deprecated alias /api/v1/platforms), the Pick of the Day commitment ledger (/api/v1/pick-of-the-day/ledger), and the MCP handshake (initialize, ping, tools/list on /api/v1/mcp) are public. A 401 carries WWW-Authenticate with the resource_metadata URL."
    },
    "protected_resource_metadata_url": {
      "type": "string",
      "format": "uri",
      "description": "RFC 9728 protected-resource metadata for the API origin: the document every V1 401 names in its WWW-Authenticate challenge (resource, bearer_methods_supported, resource_documentation). The remote MCP server has its own document at /.well-known/oauth-protected-resource/api/v1/mcp."
    },
    "authenticated_routes": {
      "type": "array",
      "description": "The complete authenticated route index: one entry per authenticated route this spec documents, in \"<METHOD> <path>\" form, not a representative subset. GET /api/v1 is the unauthenticated entrypoint an agent hits first, so it hands back the whole authenticated surface rather than a sample the caller would have to guess around. The example on GET /api/v1 is abridged for readability -- the live response returns all of them. Kept in lockstep with this spec by review: it is a hand-maintained const in backend/src/api_v1/discovery.rs and no automated check compares the two, so treat this spec as authoritative if they ever disagree.",
      "items": {
        "type": "string"
      }
    }
  }
}