Developer portal

Everything you need to integrate SIMOSphere AI into your stack — quickstart, authentication, error handling, streaming, rate limits, and discovery files for AI agents.

1. Quickstart

Sign up at /register and copy your API key from the dashboard. Then send your first request:

curl https://api.simosphereai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-simo-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-8b",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

That's it — the response is the standard OpenAI Chat Completions envelope. Any client that speaks OpenAI speaks SIMOSphere AI.

2. Authentication

Every request must carry an API key. Two equivalent header formats are accepted:

  • Authorization: Bearer sk-simo-…
  • X-API-Key: sk-simo-…

Keys never expire automatically. Rotate them via the dashboard (or POST /admin/keys/rotate). Rotation invalidates the old key immediately and emits a key.rotated webhook event.

For agent-driven sign-up flows, RFC 9728 metadata is published at /.well-known/oauth-protected-resource.

3. SDKs

Because the API surface is OpenAI-compatible, the official openai SDK works out of the box — just override the base URL.

# Python
from openai import OpenAI
client = OpenAI(
    base_url="https://api.simosphereai.com/v1",
    api_key="sk-simo-...",
)
r = client.chat.completions.create(
    model="qwen/qwen3-8b",
    messages=[{"role": "user", "content": "Hello"}],
)
print(r.choices[0].message.content)
// TypeScript / Node
import OpenAI from 'openai';
const client = new OpenAI({
  baseURL: 'https://api.simosphereai.com/v1',
  apiKey: process.env.SIMO_API_KEY,
});
const r = await client.chat.completions.create({
  model: 'qwen/qwen3-8b',
  messages: [{ role: 'user', content: 'Hello' }],
});
console.log(r.choices[0].message.content);

4. Streaming responses

Add "stream": true to switch the response to Server-Sent Events. Each chunk is the standard OpenAI delta envelope; the stream terminates with data: [DONE].

for chunk in client.chat.completions.create(
    model="qwen/qwen3-8b",
    messages=[{"role": "user", "content": "Stream me"}],
    stream=True,
):
    print(chunk.choices[0].delta.content or "", end="", flush=True)

5. Rate limits

Every response carries rate-limit headers so your client can self-throttle without parsing 429s:

X-RateLimit-Limit: 600X-RateLimit-Remaining: 437X-RateLimit-Reset: 1714809600Retry-After: 12 # only on 429

Default per-plan limits: Starter 60 req/min, Professional 600 req/min, Enterprise negotiated.

6. Error format

Errors are always JSON in the OpenAI shape. HTTP status codes follow the OpenAI conventions (400, 401, 402, 403, 404, 429, 500, 503).

{
  "error": {
    "type": "invalid_request_error",
    "code": "model_not_found",
    "message": "Model 'gpt-5' is not available on this tenant.",
    "param": "model"
  }
}

7. Webhooks

Register webhook URLs via the dashboard or POST /admin/webhooks. Events:

  • usage.threshold_reached
  • key.rotated
  • invoice.created
  • audit.flagged

Payloads are signed with X-SIMO-Signature: sha256=<hex> (HMAC-SHA-256 of the body using the per-webhook secret).

8. Agent discovery

For autonomous agents:

Next steps