SpiderGate

This is the complete list of SpiderGate endpoints. Everything the dashboard, the SDKs, and your agents do goes through these. They're OpenAI-compatible, so an OpenAI client pointed at the base URL works against them directly.

Base URL

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

All paths below are relative to that base. For the OpenAI SDK, set base_url="https://spideriq.ai/api/gate/v1".

Authentication

Endpoints that read or write your data require a bearer token; the read-only catalog endpoints are public. See Authentication for the two token formats.

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

Chat & generation

These require authentication.

POST /chat/completions

Create a chat completion (streaming or non-streaming). The body is the OpenAI chat-completion request; model may be a task alias or a model id.

Query: include_route_trace (boolean, default false) — inline a per-attempt route trace in the response (non-streaming).
Response headers: X-SpiderGate-Fallback-From — present (non-streaming) when the served model differs from the alias's first choice.
Full parameters: Chat Completions. Streaming: Streaming.

POST /images/generations

Generate images with dall-e-3, dall-e-2, or gpt-image-1. Requires an OpenAI key in the vault. See Images, Audio & Embeddings.

POST /audio/speech

Text-to-speech with tts-1, tts-1-hd, or gpt-4o-mini-tts. Returns audio bytes. Voices: alloy, echo, fable, onyx, nova, shimmer. Formats: mp3, opus, aac, flac, wav, pcm.

POST /audio/transcriptions

Speech-to-text with whisper-1, gpt-4o-transcribe, or gpt-4o-mini-transcribe. multipart/form-data; file cap 25 MB.

POST /embeddings

Vector embeddings with text-embedding-3-large, text-embedding-3-small, or text-embedding-ada-002. dimensions up to 3072.

Catalog (public, no auth)

GET /models

List the model catalog in OpenAI list format, each entry with a spidergate_info block. Query params: provider, free_only, configured_only, search, capability, sort_by, limit (1–2000), offset. See Models.

GET /models/{model_id}

Return one model, or 404 model_not_found if unknown.

GET /aliases

List all 26 task aliases with their model fallback chains and recent usage. See Task Aliases.

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

GET /providers

List the upstream providers SpiderGate can route to, with model counts and key status.

GET /health

Process liveness check.

curl "https://spideriq.ai/api/gate/v1/health"
# {"status":"healthy","service":"spidergate","version":"…"}

Endpoint summary

::table
Method | Path | Auth | Purpose
POST | `/chat/completions` | required | Chat completion (streaming & non-streaming)
POST | `/images/generations` | required | Image generation
POST | `/audio/speech` | required | Text-to-speech
POST | `/audio/transcriptions` | required | Transcription (multipart)
POST | `/embeddings` | required | Vector embeddings
GET | `/models` | public | List models
GET | `/models/{model_id}` | public | Get one model
GET | `/aliases` | public | List task aliases + chains
GET | `/providers` | public | List providers
GET | `/health` | public | Liveness check

Dashboard endpoints

The dashboard surfaces (agents, usage, traces, vault) are served by brand-scoped endpoints under /api/v1/brands/{brand_id}/gate/* and are authenticated by your dashboard session rather than a gateway bearer token. They power the dashboard and are not part of the OpenAI-compatible surface; use the dashboard UI to drive them.

Next steps

Authenticate your calls — Authentication.
Handle failures correctly — Errors.
Stay within limits — Rate Limits & Budgets.

API Reference