> ## 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.

# Integration Guides

> One line change. Same code. World model prediction on every request.

Stratus is a **drop-in replacement** for the OpenAI API. Change the `baseURL`, swap the model name, and your existing code gains prediction, planning, and semantic state understanding on every request.

```typescript theme={null}
// Before
baseURL: 'https://api.openai.com/v1'

// After — everything else stays the same
baseURL: 'https://api.stratus.run/v1'
```

That's it. Pick your framework below.

***

## Agent Platforms

<CardGroup cols={2}>
  <Card title="OpenClaw" icon="robot" color="#ef4444" href="/docs/openclaw-integration">
    Native plugin for OpenClaw's SIGBART agent runtime. Drops the full model catalog, embeddings, and rollout tools directly into your agent.
  </Card>
</CardGroup>

***

## Framework Integrations

<CardGroup cols={2}>
  <Card title="OpenAI SDK" icon="bolt" color="#22d3ee" href="#openai-sdk">
    The most common path. Works in TypeScript, Python, and anywhere the OpenAI SDK runs.
  </Card>

  <Card title="Anthropic SDK" icon="brain" color="#c084fc" href="#anthropic-sdk">
    Use the Anthropic SDK with Stratus for Claude-backed X1 models via the `/v1/messages` endpoint.
  </Card>

  <Card title="LangChain" icon="link" color="#34d399" href="#langchain">
    Plug Stratus into LangChain agents, chains, and memory — no wrappers needed.
  </Card>

  <Card title="Vercel AI SDK" icon="triangle" color="#f59e0b" href="#vercel-ai-sdk">
    Streaming UI in Next.js App Router with server actions and route handlers.
  </Card>

  <Card title="cURL" icon="terminal" color="#6ee7f7" href="#curl">
    Raw HTTP — for quick tests, CI pipelines, and shell scripts.
  </Card>
</CardGroup>

***

## Migration Guide

Already on OpenAI or Anthropic? The switch takes seconds.

### From OpenAI Direct

```typescript theme={null}
// Before
const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

// After
const client = new OpenAI({
  baseURL: 'https://api.stratus.run/v1',
  apiKey: process.env.STRATUS_API_KEY
});
```

**Model name mapping:**

| OpenAI        | Stratus                          |
| ------------- | -------------------------------- |
| `gpt-4o`      | `stratus-x1ac-base-gpt-4o`       |
| `gpt-4o-mini` | `stratus-x1ac-small-gpt-4o-mini` |

OpenRouter models are also available directly via slash notation — `stratus-x1ac-base-deepseek/deepseek-r1`, `stratus-x1ac-base-meta-llama/llama-3.3-70b-instruct`, `stratus-x1ac-base-google/gemini-2.5-pro`, and more. See [Models](/docs/api-reference/models) for the full list.

### From Anthropic Direct

```typescript theme={null}
// Before
const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});

// After
const client = new Anthropic({
  baseURL: 'https://api.stratus.run',
  apiKey: process.env.STRATUS_API_KEY
});
```

**Model name mapping:**

| Anthropic                    | Stratus                               |
| ---------------------------- | ------------------------------------- |
| `claude-sonnet-4-5-20250514` | `stratus-x1ac-base-claude-sonnet-4-5` |

***

## OpenAI SDK

The most common integration path. Works in TypeScript, Node.js, Python, and anywhere the OpenAI SDK runs.

### Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install openai dotenv
  ```

  ```bash yarn theme={null}
  yarn add openai dotenv
  ```

  ```bash pnpm theme={null}
  pnpm add openai dotenv
  ```

  ```bash bun theme={null}
  bun add openai dotenv
  ```
</CodeGroup>

### TypeScript / Node.js

```typescript theme={null}
import OpenAI from 'openai';
import 'dotenv/config';

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: User on homepage, search box visible.'
    },
    {
      role: 'user',
      content: 'Search for "best laptops 2024"'
    }
  ]
});

console.log(response.choices[0].message.content);
console.log(response.stratus.overall_confidence);       // X1 confidence score
console.log(response.stratus.planning_time_ms); // planning overhead
```

### Streaming

```typescript theme={null}
const stream = await client.chat.completions.create({
  model: 'stratus-x1ac-base-gpt-4o',
  messages: [{ role: 'user', content: 'Navigate to checkout' }],
  stream: true
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) process.stdout.write(content);
}
```

### Error Handling

```typescript theme={null}
try {
  const response = await client.chat.completions.create({
    model: 'stratus-x1ac-base-gpt-4o',
    messages: [...]
  });
} catch (error) {
  if (error.status === 401) console.error('Invalid API key');
  else if (error.status === 402) console.error('Insufficient credits');
  else if (error.status === 429) console.error('Rate limit exceeded');
  else console.error('API error:', error.message);
}
```

***

## Anthropic SDK

Use the Anthropic SDK to hit Stratus via the `/v1/messages` endpoint — useful when your codebase is already Anthropic-shaped.

### Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @anthropic-ai/sdk dotenv
  ```

  ```bash yarn theme={null}
  yarn add @anthropic-ai/sdk dotenv
  ```

  ```bash pnpm theme={null}
  pnpm add @anthropic-ai/sdk dotenv
  ```

  ```bash bun theme={null}
  bun add @anthropic-ai/sdk dotenv
  ```
</CodeGroup>

<Note>
  Stratus supports both `/v1/chat/completions` (OpenAI format) and `/v1/messages` (Anthropic format). Use whichever SDK fits your codebase.
</Note>

### TypeScript / Node.js

```typescript theme={null}
import Anthropic from '@anthropic-ai/sdk';
import 'dotenv/config';

const client = new Anthropic({
  baseURL: 'https://api.stratus.run',
  apiKey: process.env.STRATUS_API_KEY
});

const response = await client.messages.create({
  model: 'stratus-x1ac-base-claude-sonnet-4-5',
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content: 'Current state: Amazon product page. Goal: Add to cart and proceed to checkout.'
    }
  ]
});

console.log(response.content[0].text);
```

### Streaming

```typescript theme={null}
const stream = await client.messages.create({
  model: 'stratus-x1ac-base-claude-sonnet-4-5',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Navigate to settings' }],
  stream: true
});

for await (const event of stream) {
  if (event.type === 'content_block_delta') {
    process.stdout.write(event.delta.text);
  }
}
```

***

## LangChain

Plug Stratus into LangChain agents and chains without any custom wrappers.

### Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @langchain/openai dotenv
  ```

  ```bash pnpm theme={null}
  pnpm add @langchain/openai dotenv
  ```
</CodeGroup>

### Basic Usage

```typescript theme={null}
import { ChatOpenAI } from '@langchain/openai';
import 'dotenv/config';

const model = new ChatOpenAI({
  openAIApiKey: process.env.STRATUS_API_KEY,
  configuration: { baseURL: 'https://api.stratus.run/v1' },
  modelName: 'stratus-x1ac-base-gpt-4o'
});

const response = await model.invoke([
  { role: 'system', content: 'Current state: Google search results for "restaurants near me"' },
  { role: 'user', content: 'Click on the first result' }
]);

console.log(response.content);
```

### With Agents

```typescript theme={null}
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
import { pull } from 'langchain/hub';

const model = new ChatOpenAI({
  openAIApiKey: process.env.STRATUS_API_KEY,
  configuration: { baseURL: 'https://api.stratus.run/v1' },
  modelName: 'stratus-x1ac-base-gpt-4o'
});

const prompt = await pull('hwchase17/openai-functions-agent');
const agent = await createOpenAIFunctionsAgent({ llm: model, tools: yourTools, prompt });
const executor = new AgentExecutor({ agent, tools: yourTools });

const result = await executor.invoke({
  input: 'Navigate to the checkout page and fill in shipping details'
});

console.log(result.output);
```

### With Chains

```typescript theme={null}
import { PromptTemplate } from '@langchain/core/prompts';
import { RunnableSequence } from '@langchain/core/runnables';

const chain = RunnableSequence.from([
  PromptTemplate.fromTemplate('Current state: {state}\nGoal: {goal}\nWhat should I do next?'),
  model
]);

const result = await chain.invoke({
  state: 'Amazon homepage',
  goal: 'Find and purchase wireless headphones under $100'
});

console.log(result.content);
```

***

## Vercel AI SDK

Streaming UI in Next.js with server actions and route handlers.

### Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install ai @ai-sdk/openai dotenv
  ```

  ```bash pnpm theme={null}
  pnpm add ai @ai-sdk/openai dotenv
  ```
</CodeGroup>

### Server Action + Streaming UI

```typescript theme={null}
// app/actions.ts
'use server';

import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
import { createStreamableValue } from 'ai/rsc';

const model = openai('stratus-x1ac-base-gpt-4o', {
  baseURL: 'https://api.stratus.run/v1',
  apiKey: process.env.STRATUS_API_KEY
});

export async function navigateAction(state: string, goal: string) {
  const stream = createStreamableValue('');

  (async () => {
    const { textStream } = await streamText({
      model,
      messages: [
        { role: 'system', content: `Current state: ${state}` },
        { role: 'user', content: goal }
      ]
    });

    for await (const delta of textStream) stream.update(delta);
    stream.done();
  })();

  return { output: stream.value };
}
```

```tsx theme={null}
// app/page.tsx
'use client';

import { useState } from 'react';
import { readStreamableValue } from 'ai/rsc';
import { navigateAction } from './actions';

export default function Page() {
  const [response, setResponse] = useState('');

  const handleNavigate = async () => {
    const { output } = await navigateAction('Amazon homepage', 'Search for wireless headphones');
    for await (const delta of readStreamableValue(output)) {
      setResponse(prev => prev + delta);
    }
  };

  return (
    <div>
      <button onClick={handleNavigate}>Navigate</button>
      <div>{response}</div>
    </div>
  );
}
```

### API Route Handler

```typescript theme={null}
// app/api/navigate/route.ts
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';

const model = openai('stratus-x1ac-base-gpt-4o', {
  baseURL: 'https://api.stratus.run/v1',
  apiKey: process.env.STRATUS_API_KEY
});

export async function POST(req: Request) {
  const { state, goal } = await req.json();

  const result = await streamText({
    model,
    messages: [
      { role: 'system', content: `Current state: ${state}` },
      { role: 'user', content: goal }
    ]
  });

  return result.toDataStreamResponse();
}
```

***

## cURL

For quick tests, CI pipelines, and shell scripts.

### Basic Request

```bash theme={null}
curl https://api.stratus.run/v1/chat/completions \
  -H "Authorization: Bearer $STRATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stratus-x1ac-base-gpt-4o",
    "messages": [
      {"role": "system", "content": "Current state: Google homepage. Search box visible."},
      {"role": "user", "content": "Search for best laptops 2024"}
    ]
  }'
```

### Streaming

```bash theme={null}
curl https://api.stratus.run/v1/chat/completions \
  -H "Authorization: Bearer $STRATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"stratus-x1ac-base-gpt-4o","messages":[{"role":"user","content":"Navigate to checkout"}],"stream":true}'
```

### Extract Fields with jq

```bash theme={null}
# Just the response text
curl -s https://api.stratus.run/v1/chat/completions \
  -H "Authorization: Bearer $STRATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"stratus-x1ac-base-gpt-4o","messages":[{"role":"user","content":"Test"}]}' \
  | jq -r '.choices[0].message.content'

# X1 planning metadata
  ... | jq '.stratus'
```

***

## Other Languages

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    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: E-commerce homepage"},
            {"role": "user", "content": "Search for wireless headphones"}
        ]
    )

    print(response.choices[0].message.content)
    print(response.stratus)  # X1 metadata
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    package main

    import (
        "bytes"
        "encoding/json"
        "fmt"
        "io"
        "net/http"
        "os"
    )

    func main() {
        body, _ := json.Marshal(map[string]any{
            "model": "stratus-x1ac-base-gpt-4o",
            "messages": []map[string]string{
                {"role": "system", "content": "Current state: Homepage"},
                {"role": "user", "content": "Navigate to products"},
            },
        })

        req, _ := http.NewRequest("POST", "https://api.stratus.run/v1/chat/completions", bytes.NewBuffer(body))
        req.Header.Set("Authorization", "Bearer "+os.Getenv("STRATUS_API_KEY"))
        req.Header.Set("Content-Type", "application/json")

        resp, _ := http.DefaultClient.Do(req)
        defer resp.Body.Close()
        result, _ := io.ReadAll(resp.Body)
        fmt.Println(string(result))
    }
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use reqwest::Client;
    use serde_json::json;
    use std::env;

    #[tokio::main]
    async fn main() -> Result<(), Box<dyn std::error::Error>> {
        let api_key = env::var("STRATUS_API_KEY")?;

        let response = Client::new()
            .post("https://api.stratus.run/v1/chat/completions")
            .header("Authorization", format!("Bearer {}", api_key))
            .json(&json!({
                "model": "stratus-x1ac-base-gpt-4o",
                "messages": [
                    {"role": "system", "content": "Current state: Homepage"},
                    {"role": "user", "content": "Navigate to products"}
                ]
            }))
            .send()
            .await?;

        println!("{}", response.text().await?);
        Ok(())
    }
    ```
  </Tab>
</Tabs>

***

## Troubleshooting

**"Invalid API Key"** — Confirm the key starts with `stratus_sk_live_` and the env var is actually loaded (`echo $STRATUS_API_KEY`).

**"Model Not Found"** — Use the Stratus model name, not the upstream provider name. `stratus-x1ac-base-gpt-4o` ✅ · `gpt-4o` ❌

**SSL errors** — Always `https://api.stratus.run/v1`, never `http://`.

**402 Insufficient Credits** — Top up from the [dashboard](https://stratus.run/dashboard).

***

## Next Steps

<CardGroup cols={3}>
  <Card title="API Reference" icon="code" color="#22d3ee" href="/docs/api-reference/introduction">
    Full endpoint docs, parameters, and response shapes.
  </Card>

  <Card title="Models" icon="cpu" color="#c084fc" href="/docs/api-reference/models">
    Every available model across all size tiers.
  </Card>

  <Card title="Authentication" icon="key" color="#34d399" href="/docs/authentication">
    API keys, BYOK, and key resolution priority.
  </Card>
</CardGroup>