Quickstart

This page takes you from nothing to a working chat completion in about two minutes. You need one thing: a SpiderGate token (see Authentication for how to get one).

1. Set your token

SpiderGate accepts two token formats in the Authorization: Bearer header — a client credential triple or a per-agent token. Either works everywhere a token is required.

# Client credential (client_id:api_key:api_secret)
export SPIDERIQ_TOKEN="cli_abc123:key_xxx:secret_xxx"

# …or a per-agent token (recommended for agents)
export SPIDERIQ_TOKEN="spideriq_pat_0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d"

2. Send your first completion

The base URL is https://spideriq.ai/api/gate/v1. Pass a task alias as the model and SpiderGate chooses the model for you.

curl -X POST "https://spideriq.ai/api/gate/v1/chat/completions" \
  -H "Authorization: Bearer $SPIDERIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "spideriq/fast",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Say hello in three languages."}
    ]
  }'

The response is the standard OpenAI chat-completion shape:

{
  "id": "chatcmpl-1a2b3c4d5e6f7a8b9c0d1e2f",
  "object": "chat.completion",
  "created": 1780690000,
  "model": "llama-3.1-8b-instant",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hello! Hola! Bonjour!"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 24, "completion_tokens": 8, "total_tokens": 32}
}

Notice that model in the response is the actual model that served the request — the alias you sent resolved to a concrete model.

3. Use the OpenAI SDK

Because the API is OpenAI-compatible, you can use the official openai SDK by changing only the base_url and api_key.

from openai import OpenAI

client = OpenAI(
    base_url="https://spideriq.ai/api/gate/v1",
    api_key="spideriq_pat_0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
)

resp = client.chat.completions.create(
    model="spideriq/coding",
    messages=[{"role": "user", "content": "Write a haiku about caching."}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://spideriq.ai/api/gate/v1",
  apiKey: process.env.SPIDERIQ_TOKEN,
});

const resp = await client.chat.completions.create({
  model: "spideriq/coding",
  messages: [{ role: "user", content: "Write a haiku about caching." }],
});
console.log(resp.choices[0].message.content);

4. Stream the response

Set stream: true to receive tokens over Server-Sent Events as they're generated.

curl -N -X POST "https://spideriq.ai/api/gate/v1/chat/completions" \
  -H "Authorization: Bearer $SPIDERIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "spideriq/chat",
    "stream": true,
    "messages": [{"role": "user", "content": "Count to five."}]
  }'

See Streaming for the chunk format.

Explore without a token

The read-only catalog endpoints need no authentication. Try them now:

curl "https://spideriq.ai/api/gate/v1/health"
curl "https://spideriq.ai/api/gate/v1/aliases"
curl "https://spideriq.ai/api/gate/v1/models?limit=5"

Next steps

1. Understand Core Concepts — aliases, providers, the vault, and tokens.

2. Pick the right alias from the Task Aliases reference.

3. Read the full Chat Completions parameters.