Models & Direct Routing

Besides task aliases, you can target a specific model by name and browse the full catalog of what SpiderGate can route to. Both the catalog and direct routing use the same model field — an alias resolves to a chain, a model id pins one model.

List available models

GET /api/gate/v1/models returns the catalog in OpenAI list format. No authentication required.

curl "https://spideriq.ai/api/gate/v1/models?limit=10"

Each entry is an OpenAI-shaped model object with a SpiderGate extension:

{
  "id": "gpt-4o",
  "object": "model",
  "created": 1780689385,
  "owned_by": "openai",
  "spidergate_info": {
    "provider": "openrouter",
    "provider_model": "openai/gpt-4o",
    "display_name": "OpenAI: GPT-4o",
    "context_window": 128000,
    "max_output_tokens": 16384,
    "capabilities": ["chat", "vision", "function_calling"],
    "free_tier": false,
    "is_configured": true,
    "in_task_aliases": ["agent/tool-use"]
  }
}

The spidergate_info block tells you which provider serves the model, its context window and output cap, capabilities, whether it's free-tier, whether a key is configured for it, and which aliases include it.

Filtering the catalog

GET /models accepts query parameters to narrow the list:

::table
Parameter | Type | Default | Notes
`provider` | string | — | Only models from this provider.
`free_only` | boolean | `false` | Only free-tier models.
`configured_only` | boolean | `false` | Only models that have a usable key.
`search` | string | — | Match model name or id.
`capability` | string | — | e.g. `chat`, `vision`, `function_calling`.
`sort_by` | string | `usage` | `usage`, `name`, `provider`, `context`, or `cost`.
`limit` | integer | `500` | `1`–`2000`.
`offset` | integer | `0` | For pagination.

# Free models that support vision, sorted by context window
curl "https://spideriq.ai/api/gate/v1/models?free_only=true&capability=vision&sort_by=context"

One model

GET /api/gate/v1/models/{model_id} returns a single model, or 404 with code model_not_found if the id is unknown.

curl "https://spideriq.ai/api/gate/v1/models/gpt-4o"

Direct model routing

Pass a model id from the catalog as the model field to pin that exact model. There is no fallback chain — if that model is unavailable, the request fails rather than routing elsewhere.

curl -X POST "https://spideriq.ai/api/gate/v1/chat/completions" \
  -H "Authorization: Bearer $SPIDERIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Summarize the CAP theorem."}]
  }'

Use direct routing when you need a specific model's exact behavior (benchmarking, reproducibility, or a capability only one model has). Use an alias when you want resilience and automatic failover — which is most of the time.

Providers

GET /api/gate/v1/providers lists the upstream providers SpiderGate can route to, with model counts and key status. No authentication required.

curl "https://spideriq.ai/api/gate/v1/providers"

To make a provider usable, register a key for it in the vault.

Next steps

1. Prefer resilient routing? Use a Task Alias.

2. Need images, speech, or embeddings? See Images, Audio & Embeddings.

3. Add provider keys in The Key Vault.