Skip to content
Developers

Developer Hub

Open API specifications, MCP manifests, OAuth endpoints and LLM sitemaps for integrating with SIMOSphere AI.

API Documentation

OpenAPI 3.1 specification with all endpoints, authentication and error codes.

/openapi.json

SDKs & Libraries

Official client libraries for Python, Node.js and Go — type-safe and versioned.

Coming soon

MCP Specification

MCP manifest, server card and surface endpoints. WebMCP via Streamable HTTP (JSON-RPC 2.0).

/.well-known/mcp/manifest.json

MCP Server

WebMCP endpoint with JSON-RPC 2.0 over Streamable HTTP. Browser agents can call tools directly.

/mcp

Agent Skills

Skills index for AI agents: tools, prompts and resources as machine-readable manifests.

/.well-known/agent-skills/index.json

Changelog

All platform changes documented — breaking changes, new features and bug fixes.

Authentication

All API endpoints under /v1/* require a Bearer token in the Authorization header. Tokens are API keys created in the SIMOSphere AI Dashboard, scoped to a single tenant. The platform supports API key authentication today, with OAuth 2.0 (Authorization Code + PKCE) planned for Q4 2026.

1. Create an Account

Register at app.simosphereai.com/register. All plans include a 14-day free trial without requiring a credit card. After email verification, you gain access to the Dashboard.

2. Generate an API Key

In the Dashboard, navigate to Settings > API Keys and click Create New Key. Choose the scopes your application needs (chat, embeddings, files, models). Copy the key immediately — it is shown only once.

3. Authenticate Requests

Include the key as a Bearer token: Authorization: Bearer sk_live_YOUR_KEY. The gateway validates the key, checks rate limits, verifies plan entitlements, and routes the request to the appropriate model backend.

Code Examples

SIMOSphere AI provides an OpenAI-compatible REST API. You can use any OpenAI SDK or standard HTTP client to interact with the platform. Below are examples for the chat completions endpoint, which accepts messages and returns model-generated responses.

curl — Chat Completions

Send a chat completion request from the command line. Replace sk_live_YOUR_API_KEY with your actual API key. The response follows the OpenAI chat completions format.

curl -X POST https://api.simosphereai.com/v1/chat/completions \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-small-latest",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the EU AI Act?"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

TypeScript — OpenAI SDK

Use the official OpenAI Node.js SDK with the SIMOSphere AI base URL. This approach gives you full type safety, automatic retries, and streaming support out of the box.

import OpenAI from "openai";

// SIMOSphere AI is OpenAI-compatible — use any OpenAI SDK
const client = new OpenAI({
  apiKey: process.env.SIMOSPHERE_API_KEY,
  baseURL: "https://api.simosphereai.com/v1",
});

const response = await client.chat.completions.create({
  model: "mistral-small-latest",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Summarise the GDPR in 3 sentences." },
  ],
  temperature: 0.7,
  max_tokens: 512,
});

console.log(response.choices[0].message.content);
// Token usage: response.usage.total_tokens

Python — OpenAI SDK

The Python OpenAI SDK works identically. Point the base_url to SIMOSphere AI and use your API key. All OpenAI-compatible features including streaming, function calling, and JSON mode are supported.

from openai import OpenAI

client = OpenAI(
    api_key="sk_live_YOUR_API_KEY",
    base_url="https://api.simosphereai.com/v1",
)

response = client.chat.completions.create(
    model="mistral-small-latest",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain data sovereignty in the EU."},
    ],
    max_tokens=512,
)

print(response.choices[0].message.content)

Rate Limits

Rate limits are applied per API key and depend on your plan tier. Limits are enforced on both requests per minute (RPM) and tokens per month (TPM). When a limit is exceeded, the API returns HTTP 429 with a Retry-After header indicating when the next request can be sent.

PlanRequests / minTokens / month
Personal605M
Freelancer12020M
Professional300100M
Business600500M
Enterprise1,2002B

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers for proactive monitoring.

Error Codes

All error responses use a consistent JSON envelope with type, message, and code fields. Implement retry logic for transient errors (429, 500, 503) and credential refresh logic for persistent 401 errors.

401

Invalid API Key

Check that the Authorization: Bearer header contains a valid, non-revoked key.

401

Expired Token

Re-authenticate via the login endpoint to obtain a fresh JWT token.

403

Insufficient Scope

The API key lacks the required scope. Add the missing scope in Dashboard > API Keys.

403

Plan Limit Exceeded

Your current plan does not include this feature. Upgrade at app.simosphereai.com/billing.

429

Rate Limit Exceeded

Too many requests. Wait for the number of seconds specified in the Retry-After header.

500

Internal Server Error

An unexpected error occurred. Retry with exponential backoff. If persistent, contact support.

Roadmap

  • NPM package @simosphere/sdk-js (auto-generated from OpenAPI)
  • PyPI package simosphere-sdk
  • CLI simosphere via Homebrew
  • MCP registry listings on mcp.run / mcphub.io / Smithery
Back to homepage
Developers — SIMOSphere AI