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

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 routes it to one of the models pooled behind that alias.

{ "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 32 aliases in three families, carrying 91 fallback slots between them:

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

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

  • **opvs/* (5) — tuned for the OPVS agent platform**, which splits its traffic by job size rather than by task.

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.

A workspace is served only on keys it may use, in this order:

  • Your own keys — scoped to your workspace and always tried first. This is bring-your-own-key (BYOK).

  • Your connected companies' keys — the keys of companies you have connected, unless they marked a key Keep private.

  • The shared pool — free-tier keys other workspaces chose to lend, open to a workspace while it lends at least one active free key of its own.

With no key it may use, a request is refused with no_access, naming the providers that would unlock the model. Add a key at setup before your first call.

Health is tracked per key. After repeated failures a key is marked unhealthy and left out of routing. Nothing is reordered: the models behind an alias are a pool, not a ranked list.

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 its slots; pool the ones with a usable key
   → Engine        route to the least busy slot; retry on failure; some aliases hand over to another alias
   → Callbacks     log usage, cost, and a full trace
   → Response      OpenAI-shaped, with the actual model in the `model` field

When the served model is not the alias's slot-0 model, SpiderGate sends the X-SpiderGate-Fallback-From response header. An alias is a pool, so that happens in normal operation. 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.