> ## Documentation Index > Fetch the complete documentation index at: https://www.stratus.run/docs/llms.txt > Use this file to discover all available pages before exploring further. # API Reference > Complete reference for the Stratus X1 API ## Overview The Stratus X1 API provides world model predictions for autonomous agents. It's designed to be **OpenAI-compatible**, allowing you to use existing SDKs and tools with minimal changes. **Base URL:** `https://api.stratus.run/v1` ## Available Endpoints Stratus provides 6 core endpoints: **POST** `/v1/chat/completions` OpenAI-format predictions with world model planning **POST** `/v1/messages` Anthropic-format predictions (Claude SDK compatible) **POST** `/v1/embeddings` Get semantic embeddings for state descriptions **POST** `/v1/rollout` Multi-step action prediction and plan validation **POST/GET/DELETE** `/v1/account/llm-keys` Securely store user LLM provider keys (BYOK) **GET** `/health` API status, model availability, and vault connection ## Authentication All endpoints (except `/health`) require authentication using your Stratus API key in the `Authorization` header: ```bash theme={null} Authorization: Bearer stratus_sk_live_your_key_here ``` ### API Key Format All Stratus API keys use the format `stratus_sk_live_*`. Generate yours from the [dashboard](https://stratus.run/dashboard). See [Authentication](/docs/authentication) for detailed setup instructions. ### LLM Keys (Optional) Stratus includes Formation's shared OpenRouter pool as a universal fallback — no provider API account needed. LLM provider keys are optional and used as an upgrade path to remove the 25% pool markup. Key resolution order per request: 1. **Inline headers** (`X-OpenAI-Key`, `X-Anthropic-Key`, `X-Google-Key`, `X-OpenRouter-Key`) — highest priority 2. **Vault-stored keys** (set via `POST /v1/account/llm-keys`) — used automatically when present 3. **Formation's pool** — transparent fallback; 25% markup applied to credit cost When Formation's pool is used, the response includes `stratus.key_source: "formation"` and `stratus.formation_markup_applied: 0.25`. BYOK requests return `key_source: "user"` and `formation_markup_applied: null`. See [LLM Key Management](/docs/api-reference/llm-keys) for vault storage setup and [Authentication](/docs/authentication#key-resolution-priority) for the full breakdown. ## Quick Start ### TypeScript / Node.js ```typescript theme={null} import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.stratus.run/v1', apiKey: process.env.STRATUS_API_KEY }); const response = await client.chat.completions.create({ model: 'stratus-x1ac-base-gpt-4o', messages: [ { role: 'system', content: 'Current state: Homepage with login button' }, { role: 'user', content: 'Click the login button' } ] }); console.log(response.choices[0].message.content); ``` ### Python ```python theme={null} from openai import OpenAI client = OpenAI( base_url="https://api.stratus.run/v1", api_key=os.environ["STRATUS_API_KEY"] ) response = client.chat.completions.create( model="stratus-x1ac-base-gpt-4o", messages=[ {"role": "system", "content": "Current state: Homepage with login button"}, {"role": "user", "content": "Click the login button"} ] ) print(response.choices[0].message.content) ``` ### cURL ```bash theme={null} curl https://api.stratus.run/v1/chat/completions \ -H "Authorization: Bearer stratus_sk_live_your_key" \ -H "Content-Type: application/json" \ -d '{ "model": "stratus-x1ac-base-gpt-4o", "messages": [ {"role": "system", "content": "Current state: Homepage with login button"}, {"role": "user", "content": "Click the login button"} ] }' ``` ## SDK Compatibility Stratus is compatible with official SDKs from OpenAI and Anthropic: | SDK | Compatible | Usage | | ----------------- | ---------- | ---------------------------------------------------- | | **OpenAI SDK** | ✅ Yes | Use with `/v1/chat/completions` and `/v1/embeddings` | | **Anthropic SDK** | ✅ Yes | Use with `/v1/messages` | | **LangChain** | ✅ Yes | Use `ChatOpenAI` with custom `baseURL` | | **LlamaIndex** | ✅ Yes | Configure OpenAI client with custom base URL | No custom SDK needed - just point existing tools to `https://api.stratus.run/v1`. ## Response Format All Stratus responses include standard fields plus optional Stratus-specific metadata: ```json theme={null} { "id": "stratus-chatcmpl-abc123", "object": "chat.completion", "created": 1702500000, "model": "stratus-x1ac-base-gpt-4o", "choices": [...], "usage": { "prompt_tokens": 85, "completion_tokens": 42, "total_tokens": 127 }, "stratus": { "stratus_model": "x1ac-base", "execution_llm": "gpt-4o", "key_source": "formation", "formation_markup_applied": 0.25, "action_sequence": ["type", "click", "scroll"], "confidence": 0.92, "planning_time_ms": 45, "execution_time_ms": 890 } } ``` The `stratus` field provides insight into world model planning and billing: * **stratus\_model** - World model size used * **execution\_llm** - LLM used for text generation * **key\_source** - `"user"` (BYOK) or `"formation"` (Formation's pool) * **formation\_markup\_applied** - `0.25` when pool was used; `null` for BYOK * **action\_sequence** - Predicted action sequence * **confidence** - Planning confidence (0-1) * **planning\_time\_ms** - Time spent in world model * **execution\_time\_ms** - Time spent in LLM ## Error Handling Stratus uses standard HTTP status codes and returns errors in OpenAI-compatible format: ```json theme={null} { "error": { "message": "Invalid API key", "type": "invalid_request_error", "code": "invalid_api_key" } } ``` Common status codes: * **400** - Bad request (invalid parameters) * **401** - Authentication failed (invalid API key) * **403** - Permission denied * **404** - Resource not found * **429** - Rate limit exceeded * **500** - Server error * **503** - Service unavailable See [Errors](/docs/api-reference/errors) for complete reference. ## Rate Limits Rate limiting is not currently enforced. If you receive a `429` response in the future, implement exponential backoff and retry. ## Streaming Both Chat Completions and Messages endpoints support streaming via Server-Sent Events (SSE): ```typescript theme={null} const stream = await client.chat.completions.create({ model: 'stratus-x1ac-base-gpt-4o', messages: [...], stream: true }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content || ''); } ``` ## Tools & Function Calling Stratus supports OpenAI-compatible function calling with up to 100 tools per request: ```typescript theme={null} const response = await client.chat.completions.create({ model: 'stratus-x1ac-base-gpt-4o', messages: [...], tools: [ { type: 'function', function: { name: 'get_weather', description: 'Get current weather', parameters: { type: 'object', properties: { location: { type: 'string' } }, required: ['location'] } } } ] }); ``` See [Chat Completions - Tools & Function Calling](/docs/api-reference/chat-completions#tools-function-calling) for complete documentation. ## Models Stratus supports **2,050+ model combinations** across: * **5 world model sizes:** small, base, large, xl, huge * **Native LLM variants:** GPT-4o, GPT-4o Mini, Claude Sonnet/Opus/Haiku 4.5, etc. * **OpenRouter models:** Every model in OpenRouter's catalog via `{or-provider}/{or-model}` notation **Native format:** `stratus-x1ac-{size}-{llm}` **OpenRouter format:** `stratus-x1ac-{size}-{or-provider}/{or-model}` **Native examples:** * `stratus-x1ac-base-gpt-4o` - Recommended for production * `stratus-x1ac-small-gpt-4o-mini` - Fastest/cheapest for development * `stratus-x1ac-base-claude-sonnet-4-20250514` - Claude Sonnet 4 **OpenRouter examples:** * `stratus-x1ac-base-deepseek/deepseek-r1` - DeepSeek R1 reasoning * `stratus-x1ac-base-meta-llama/llama-3.3-70b-instruct` - Llama 3.3 70B * `stratus-x1ac-base-google/gemini-2.5-pro` - Gemini 2.5 Pro * `stratus-x1ac-base-x-ai/grok-4` - xAI Grok 4 * `stratus-x1ac-base-mistralai/mistral-large-2411` - Mistral Large * `stratus-x1ac-base-qwen/qwen-2.5-72b-instruct` - Qwen 2.5 72B List all available models programmatically: ```bash theme={null} curl https://api.stratus.run/v1/models \ -H "Authorization: Bearer stratus_sk_live_your_key" ``` See [Models](/docs/api-reference/models) for the complete list and all provider categories. ## Monitoring & Observability ### Health Check Monitor API status and model availability: ```bash theme={null} curl https://api.stratus.run/health ``` Returns: * API health status * Loaded world models * LLM provider availability * Vault connection status See [Health Check](/docs/api-reference/health) for details. ### Request Logging Best practice: Log request metadata for debugging: ```typescript theme={null} const response = await client.chat.completions.create({...}); console.log({ request_id: response.id, model: response.model, tokens: response.usage.total_tokens, planning_time: response.stratus?.planning_time_ms, execution_time: response.stratus?.execution_time_ms, confidence: response.stratus?.overall_confidence }); ``` ## Getting Help Build your first integration in 5 minutes Setup and manage API keys Real-world examples and patterns Contact support for help ## What's Next? * [Chat Completions](/docs/api-reference/chat-completions) - Main prediction endpoint * [Messages](/docs/api-reference/messages) - Anthropic-compatible format * [Rollout](/docs/api-reference/rollout) - Multi-step planning * [LLM Keys](/docs/api-reference/llm-keys) - Bring-your-own-key setup