Bring your own keys. Share a free one with the pool if you want. [ GET YOUR VAULT ]

Model Catalog API

The catalog API is how you read what SpiderGate knows about each model: its specs, its live per-provider pricing, the benchmarks behind it, and its score in each of nine capability categories. It is the surface behind the dashboard's Models page, and your agents read exactly the same data.

Five endpoints. One is public; the other four take a bearer token.

Base URL

https://spideriq.ai/api/gate/v1

All paths below are relative to that base.

Authentication

Authorization: Bearer <client_id>:<api_key>:<api_secret>
Authorization: Bearer spideriq_pat_…

Note: only /catalog/leaderboard is public. The other four endpoints return 401 without a token. See Authentication for the token formats.

Endpoint summary

  • GET /catalog/leaderboard — public · Rank models globally, by task type, or by capability category

  • GET /catalog/categories — token required · List the nine capability categories

  • GET /catalog/models — token required · List the enriched catalog with filters and a field projection

  • GET /catalog/models/{model_id} — token required · One model's full enriched record

  • GET /catalog/models/{model_id}/evals — token required · A model's eval aggregate

Reads are not metered and not billable. Meters fire only on a completion, never on a catalog read.

GET /catalog/leaderboard

Rank models. Public, no token needed.

Pass category to rank by a capability percentile from the taxonomy scorer. Pass task_type to rank by auto-eval success rate instead. category takes precedence over task_type; omit both for the global ranking.

  • task_type — type string · Rank for this task type. Max length 64.

  • category — type string · Capability key, e.g. coding. Max length 64. Wins over task_type.

  • sort — type string · default score · Only score is supported (within-category percentile, best first). Max length 32.

  • limit — type integer · default 100 · 1 to 500.

curl -s "https://spideriq.ai/api/gate/v1/catalog/leaderboard?category=coding&sort=score&limit=2"

Response — the envelope carries the category metadata, then the ranked list:

{
  "category": "coding",
  "label": "Coding",
  "emoji": "💻",
  "is_scored": true,
  "found": true,
  "count": 2,
  "total": 129,
  "leaderboard": [
    {
      "rank": 1,
      "id": "openai/gpt-5",
      "provider": "openrouter",
      "model_id": "openai/gpt-5",
      "display_name": "OpenAI: GPT-5",
      "owned_by": "openai",
      "context_window": 400000,
      "pricing_input": 1.25,
      "pricing_output": 10.0,
      "is_free": false,
      "score": 99.0,
      "n_signals": 4,
      "confidence": "med",
      "components": [ { "name": "SWE-Bench Verified", "self_reported": false } ]
    }
  ]
}

score is the within-category percentile, rank is the position, and total is the denominator that rank counts against. components lists the benchmarks that produced the score, each flagged self_reported when the number came from the vendor.

Note: an unknown category returns 200 with found: false and an empty leaderboard, not a 404. Check found before trusting an empty list.

GET /catalog/categories

List the capability categories. Requires a token.

  • include_inactive — type boolean · default false · Include categories that are not published.

curl -s -H "Authorization: Bearer $SPIDERGATE_TOKEN" \
  "https://spideriq.ai/api/gate/v1/catalog/categories"
{
  "count": 9,
  "categories": [
    {
      "key": "coding",
      "label": "Coding",
      "description": "Code generation, debugging, software engineering (SWE-Bench, HumanEval, LiveCodeBench, Terminal-Bench).",
      "emoji": "💻",
      "parent_key": null,
      "sort_order": 1,
      "is_scored": true,
      "is_active": true
    }
  ]
}

The nine keys are coding, design_frontend, reasoning, math, vision, research, tool_use, chat and translation. Use key as the category value on the leaderboard.

GET /catalog/models

List the enriched catalog. Requires a token.

  • provider — type string · Filter by provider. Max length 64.

  • search — type string · Match against id and display name. Max length 200.

  • tag — type string · Filter by an authored tag. Max length 64.

  • fields — type string · CSV projection, e.g. capabilities,pricing,per_provider,evals. Max length 256.

  • configured_only — type boolean · default false · Only rows whose stored is_configured flag is true. A saved flag, not a live check: a returned row can have call_as: null.

  • free_only — type boolean · default false · Only free-tier models.

  • servable_only — type boolean · default false · Only rows whose servable is true right now: a pooled key may serve that model on that row. Never returns a Codex row.

  • include_hidden — type boolean · default false · Include models hidden from the public catalog.

  • limit — type integer · default 200 · 1 to 1000.

  • offset — type integer · default 0 · Pagination offset.

curl -s -H "Authorization: Bearer $SPIDERGATE_TOKEN" \
  "https://spideriq.ai/api/gate/v1/catalog/models?fields=pricing&limit=3"
{
  "total": 3,
  "count": 3,
  "fields": [
    "pricing"
  ],
  "models": [
    {
      "id": "gpt-6-sol-codex",
      "provider": "codex",
      "model_id": "gpt-6-sol",
      "spidergate_id": "gpt-6-sol-codex",
      "display_name": "gpt-6-sol",
      "owned_by": "",
      "pricing_input": 0.0,
      "pricing_output": 0.0,
      "servable": false,
      "call_as": "codex/gpt-6-sol",
      "delisting": null
    },
    {
      "id": "lease-model-anthropic",
      "provider": "anthropic",
      "model_id": "lease-model",
      "spidergate_id": "lease-model-anthropic",
      "display_name": "lease-model",
      "owned_by": "",
      "pricing_input": 0.0,
      "pricing_output": 0.0,
      "servable": false,
      "call_as": null,
      "delisting": null
    },
    {
      "id": "llama-x-groq",
      "provider": "groq",
      "model_id": "llama-x",
      "spidergate_id": "llama-x-groq",
      "display_name": "llama-x",
      "owned_by": "",
      "pricing_input": 0.0,
      "pricing_output": 0.0,
      "servable": true,
      "call_as": "llama-x-groq",
      "delisting": null
    }
  ]
}

This example is the service's own test fixtures run through the catalog read with fields=pricing. The model names and prices are synthetic. The shape and the call_as values are exact. Without fields, each row also carries its spec, editorial copy, is_configured, benchmarks, per-provider pricing, links, evals and category scores.

Calling a model: send call_as

Every row carries call_as: the exact model string to send on /chat/completions for that row right now, or null. If it is null, the shared pool cannot serve that row now. Do not send a row's id because a filter returned the row. call_as is present under every fields projection, and on the single-model record below.

The cases, in the order they are applied:

  • A row of a lease-only provider, whose logins are lent to the owner's own CLI — call_as is null, always.

  • A row whose delisting.state is confirmed — the liveness probe read the model as removed and the provider's own model list dropped it too — servable is false · call_as is null.

  • A servable row — call_as is the row's own id.

  • A Codex row while the gateway holds a pooled Codex seat, for a model SpiderGate still offers, on a row that is not hidden — servable is false · call_as is codex/<model_id>. The row's id and its model_id are both refused as model.

  • Anything else, including a Codex row with no seat — call_as is null.

servable is per row. It is true when a request naming the row's id would reach that row on a pooled key: the row is not hidden, its provider holds a pooled key that may serve this model (a free-purpose key reaches only a model that is free at that provider), and no Codex row answers to the same id first. Where rows of two providers answer to one id, a call with that id goes to the best-ranked row that has a key.

call_as answers for the shared pool, per row. It does not see your brand's own unshared keys: a model only your own key can serve reads null here, and GET /subscriptions answers for your own keys, with a call_as on each of its rows. It is not a check of your token's allowed models. It is read from one gateway process's in-memory key state on each request. The gateway runs several processes, so call_as can differ between two reads for a moment. Read it close to the call.

delisting is null on most rows. When the liveness probe read a model as removed (a 404 or 410), it says which kind: confirmed — the provider's own model list dropped it too; the row is not callable and reason reads "the provider removed this model on <date>" — or unconfirmed — one key answered 404 while the provider still lists the model; the row stays callable. Nothing is stored: the next probe that reads ok makes the row callable again. delisting is present under every fields projection.

Neither filter selects on call_as. configured_only=true can return a row whose call_as is null, and a Codex row whose id is refused. servable_only=true never returns a Codex row, even one whose call_as is set.

Tip: total counts what the query can return, which excludes hidden models unless you pass include_hidden=true. Use fields to keep responses small when you only need pricing or capabilities.

GET /catalog/models/{model_id}

One model's full record, including its per-category scores. Requires a token.

model_id is a path parameter and usually contains a slash, so URL-encode it: openai/gpt-4o becomes openai%2Fgpt-4o.

curl -s -H "Authorization: Bearer $SPIDERGATE_TOKEN" \
  "https://spideriq.ai/api/gate/v1/catalog/models/openai%2Fgpt-4o"

The record carries everything from the list shape, call_as included, plus sort_order, hidden, and category_scores. The model_id in the path is a lookup key. What you send as model on a completion is the record's call_as.

{
  "id": "openai/gpt-4o",
  "display_name": "OpenAI: GPT-4o",
  "category_scores": [
    {
      "category_key": "translation",
      "label": "Translation",
      "emoji": "🌐",
      "score": 50,
      "rank": 33,
      "n_signals": 1,
      "confidence": "low",
      "components": [
        { "name": "MMMLU", "self_reported": true, "normalized_score": 0.814 }
      ]
    }
  ]
}

A model with no benchmark evidence returns an empty category_scores. That means not scored yet, not scored zero.

GET /catalog/models/{model_id}/evals

A model's eval aggregate: automated runs, human ratings, and a summary. Requires a token.

  • model_id — type string (path) · Required. URL-encode the slash.

  • task_type — type string · Scope the aggregate to one task type. Max length 64.

curl -s -H "Authorization: Bearer $SPIDERGATE_TOKEN" \
  "https://spideriq.ai/api/gate/v1/catalog/models/openai%2Fgpt-4o/evals"
{
  "model": "gpt-4o",
  "model_id": "openai/gpt-4o",
  "display_name": "OpenAI: GPT-4o",
  "task_type": null,
  "auto": [],
  "human": [],
  "summary": { "auto_count": 0, "human_count": 0, "avg_stars": null }
}

Note: evals are just getting started. The endpoint and its shape are live, but coverage is currently very thin, so expect empty auto and human arrays for most models. Treat summary.avg_stars: null as no data, never as a low rating.

Errors

  • 401 — No token, or a malformed one, on any endpoint except /catalog/leaderboard. · Send Authorization: Bearer <client_id>:<api_key>:<api_secret> or a spideriq_pat_… token.

  • 404 — model_id does not match any catalog row. · Check the id against /catalog/models. Remember to URL-encode the slash.

  • 422 — A parameter failed validation, e.g. limit=99999 against a max of 500. · The body is {"error": {"code": "SCHEMA_VALIDATION_FAILED", …}}. Read error.what_was_expected.errors[].loc to find the offending parameter, then apply the limits listed under that endpoint above.

  • 500 — The catalog query failed server-side. · Retry. If it persists, the response body carries a generic message; check the gateway status page.

An unknown category on the leaderboard is not an error. It returns 200 with found: false.

Reading the catalog from an agent

The same data is available to agents through the @spideriq/gateway-skills marketplace package and the mcp-gate MCP slice, which wrap these endpoints as gate_catalog_list, gate_catalog_get, gate_catalog_model_evals and gate_leaderboard. An agent picking a model for a task ranks it exactly the way the dashboard does. Leaderboard rows carry id and no call_as, so an agent reads the winner's record and sends that record's call_as.