Core Concepts

SpiderGate has a small set of concepts. Once you understand task aliases, providers, the vault, and tokens, the rest of the API follows naturally.

Task aliases

A task alias is a name for a job rather than a specific model — for example spideriq/coding, spideriq/extraction, or agent/chat. You pass it as the model field of a request, and SpiderGate resolves it to a concrete model from a ranked fallback chain.

{ "model": "spideriq/coding", "messages": [...] }

This decouples your code from any one provider. If a model is busy, rate-limited, or retired, SpiderGate routes around it without you changing anything. There are 26 aliases in two families:

• **spideriq/* (18) — tuned for workers**: scrapers, batch jobs, single-shot calls. Biased toward fast, free-tier providers because cost dominates at scale.

• **agent/* (8) — tuned for live conversational agents**: chat UIs, assistants, multi-turn sessions. Biased toward subscription primaries where coherence and uptime matter most.

The full list is in the Task Aliases reference.

Providers and the pool

A provider is an upstream LLM service — Groq, Mistral, OpenRouter, Cerebras, NVIDIA NIM, and others. SpiderGate holds one or more keys per provider and rotates across them so you exhaust free quotas before paying.

Keys come from two places:

• Pool keys — shared, SpiderGate-managed keys available to everyone. This is the default; you can start calling the gateway without registering anything.

• Brand keys — your own keys, scoped to your workspace. When present, your keys are tried before the shared pool. This is bring-your-own-key (BYOK).

Health is tracked per key. After repeated failures a key is marked unhealthy and skipped, and the router reorders fallback chains so healthy providers are tried first.

The key vault

The vault is where provider keys live, encrypted at rest. You add a key once and every request that needs that provider can use it. The vault also supports a contributor invite flow: an admin sends a signed link, the contributor pastes their own key or completes OAuth in their browser, and the encrypted credential lands in the vault — the admin never sees the raw key.

See The Key Vault for the full flow.

Tokens and identity

Every request authenticates with a token, and SpiderGate accepts two formats:

• Client credential — client_id:api_key:api_secret, validated against your workspace.

• Agent token (PAT) — spideriq_pat_…, a per-agent credential you mint in the dashboard with its own budget, rate limits, model restrictions, and scopes.

Behind both, client_id is the ground truth — it identifies your brand and is what usage, spend, and traces are attributed to. Agent tokens resolve to a client_id at auth time, so per-agent controls layer on top of brand-level identity.

See Authentication for the exact formats and Agent Keys for per-token controls.

How a request flows

Your request (Bearer token, model = "spideriq/coding")
   → Auth          resolve the token to a client_id; check budget, rate limit, model allow-list
   → Task router   resolve the alias to a ranked model chain, reordered by live provider health
   → Engine        call the first model; on failure, fall through the chain (and across aliases)
   → Callbacks     log usage, cost, and a full trace
   → Response      OpenAI-shaped, with the actual model in the `model` field

When the served model differs from the alias's first choice, SpiderGate tells you via the X-SpiderGate-Fallback-From response header. Pass ?include_route_trace=true to see every attempt inline.

Next steps

1. Browse the Task Aliases and pick one for your job.

2. Read Chat Completions for the full parameter set.

3. Set up Agent Keys with budgets and limits.