Developer documentation
Three ways to access the model dataset: the public REST API, an MCP server for agent systems, and API keys to authenticate against both.
API keys
An API key authenticates against both POST /api/v1/recommend and the MCP server, via the header "Authorization: Bearer <key>".
Each key has a quota per calendar month (default: 1,000 requests). A request that exceeds the quota gets 429 — it still counts against the quota.
The full key value is shown only once, at creation, and is never stored anywhere afterwards. A lost key cannot be recovered, only revoked and replaced with a new one.
POST /api/v1/recommend
A structured request, not free text. Without an "Authorization" header the request runs anonymously and without a quota; with a valid key it counts against your monthly quota.
Request body fields
required_modalities- Required modalities (slugs, e.g. "text", "image").
required_capabilities- Required capability slugs.
required_languages- Required language slugs.
max_budget_amount/max_budget_currency- Monthly/flat budget — amount and currency (EUR or USD) only together, never alone.
compliance_interests- Compliance fact slugs. /ranking shows the currently active weighting.
exclude_deprecated- Exclude deprecated models from the result.
Error codes
- 401: key unknown or revoked (only when a key was sent but is invalid — without a header the request stays anonymous).
- 429: monthly quota exceeded.
- 422: request does not match the expected format.
Full OpenAPI reference at /docs (Swagger) — currently reachable only from the internal network, not over the public domain.
MCP server (/mcp)
For agent systems such as Hermes: an MCP server over Streamable HTTP at /mcp. Authentication is mandatory here, using the same API key as above.
Tool: recommend_model
Takes "task" (free text, evaluated by keyword matching like /search) and optional "constraints".
Four constraints from the flagship example: processing_region, dpa_required, training_on_input, max_eur_per_1k.
Each requested criterion comes back in the response with its own status: "filtered" (hard-excludes models) or "informational_only" (shown only, does not filter). As of today's data, only dpa_required filters hard — the other three are informational.