API Reference

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:

Chat Completions

POST /v1/chat/completionsOpenAI-format predictions with world model planning

Messages

POST /v1/messagesAnthropic-format predictions (Claude SDK compatible)

Embeddings

POST /v1/embeddingsGet semantic embeddings for state descriptions

Rollout

POST /v1/rolloutMulti-step action prediction and plan validation

LLM Key Management

POST/GET/DELETE /v1/account/llm-keysSecurely store user LLM provider keys (BYOK)

Health Check

GET /healthAPI status, model availability, and vault connection

Authentication

All endpoints (except /health) require authentication using your Stratus API key in the Authorization header:

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. See 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:

Inline headers (X-OpenAI-Key, X-Anthropic-Key, X-Google-Key, X-OpenRouter-Key) — highest priority
Vault-stored keys (set via POST /v1/account/llm-keys) — used automatically when present
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 for vault storage setup and Authentication for the full breakdown.

Quick Start

TypeScript / Node.js

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

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

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:

{
  "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:

{
  "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 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):

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:

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 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:

curl https://api.stratus.run/v1/models \
  -H "Authorization: Bearer stratus_sk_live_your_key"

See Models for the complete list and all provider categories.

Monitoring & Observability

Health Check

Monitor API status and model availability:

curl https://api.stratus.run/health

Returns:

API health status
Loaded world models
LLM provider availability
Vault connection status

See Health Check for details.

Request Logging

Best practice: Log request metadata for debugging:

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

Quickstart Guide

Build your first integration in 5 minutes

Authentication

Setup and manage API keys

Use Cases

Real-world examples and patterns

Support

Contact support for help

What’s Next?

Chat Completions - Main prediction endpoint
Messages - Anthropic-compatible format
Rollout - Multi-step planning
LLM Keys - Bring-your-own-key setup

​Overview

​Available Endpoints

Chat Completions

Messages

Embeddings

Rollout

LLM Key Management

Health Check

​Authentication

​API Key Format

​LLM Keys (Optional)

​Quick Start

​TypeScript / Node.js

​Python

​cURL

​SDK Compatibility

​Response Format

​Error Handling

​Rate Limits

​Streaming

​Tools & Function Calling

​Models

​Monitoring & Observability

​Health Check

​Request Logging

​Getting Help

Quickstart Guide

Authentication

Use Cases

Support

​What’s Next?

Overview

Available Endpoints

Authentication

API Key Format

LLM Keys (Optional)

Quick Start

TypeScript / Node.js

Python

cURL

SDK Compatibility

Response Format

Error Handling

Rate Limits

Streaming

Tools & Function Calling

Models

Monitoring & Observability

Health Check

Request Logging

Getting Help

What’s Next?