Human Benchmark API and Agent Discovery

Public Endpoints

• GET /api/health returns service health and discovery links.
• GET /api/games returns the benchmark catalog.
• GET /api/games/{slug} returns details for a single benchmark.

Protected Agent Endpoint

GET /api/agent/summary requires a bearer token with the site.read scope. Tokens are issued through POST /oauth/token using the client_credentials grant when deployment credentials are configured.

Production deployments should set AGENT_CLIENT_ID, AGENT_CLIENT_SECRET, and AGENT_OAUTH_SECRET. Local development falls back to non-production defaults so the flow can be tested without secrets.

Discovery Documents

• /.well-known/api-catalog publishes an RFC 9727 API catalog in application/linkset+json.
• /openapi.json publishes the REST description in OpenAPI 3.1.
• /.well-known/oauth-authorization-server publishes OAuth authorization-server metadata.
• /.well-known/oauth-protected-resource publishes protected resource metadata for managed agent integrations.
• /.well-known/mcp/server-card.json publishes the MCP server card for /api/mcp.
• /.well-known/agent-skills/index.json publishes the agent skills discovery index and skill digests.

MCP and WebMCP

The read-only MCP endpoint at /api/mcp exposes structured catalog and discovery tools for off-page agents. On-page browser agents can also discover WebMCP tools that list benchmarks, open a benchmark page, and return discovery links.

Benchmark Catalog