# Migrating from Anthropic

There are two ways to move an Anthropic-based application to The Grid. They differ in surface area, not in what they unlock. Both give you the same instrument strings, the same competitive market for inference, and the same per-token metering.

* **Path 1: Keep the Anthropic SDK.** Point it at our Messages API beta endpoint. Two URL changes; the rest of your code stays put.
* **Path 2: Switch to the OpenAI SDK.** Point it at our main Consumption API. Stable, fully supported, and the recommended path for new builds.

## Pick Path 1 to keep your SDK, Path 2 for long-term stability

| Situation                                                                                             | Path                                                                                                                    |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| You're using Claude Code, the Anthropic SDK, or any tool built around Anthropic's `messages.create()` | Using Claude Code? See the [Claude Code integration](broken://pages/QGmc0VUqa6QuDOdKpAzG). Otherwise, use Path 1 below. |
| You want a stable, fully supported API and you're willing to swap SDKs                                | **Path 2.** OpenAI SDK against the Consumption API                                                                      |
| You use both Anthropic and OpenAI today                                                               | **Path 2.** Consolidates both behind one endpoint, one key, one balance                                                 |
| You depend on Anthropic-only features (prompt caching, computer use, extended thinking)               | Neither. Those are Anthropic product features, not part of the inference contract                                       |
| You need long-term API stability                                                                      | **Path 2.** Path 1 is a beta endpoint and can change without notice                                                     |

If you're building something new, Path 2 is the recommended choice. If you have an existing application built on the Anthropic SDK and you'd rather not refactor, Path 1 gets you running with minimal change.

## Path 1: Anthropic Messages API beta

Point the Anthropic SDK at our Anthropic-compatible Messages endpoint. Change the base URL and API key. The model name becomes an instrument string. Everything else, including the `messages` array, the `system` parameter, `max_tokens`, streaming, and tool use blocks, works the way it does with Anthropic directly.

**Endpoint:** `https://messages-beta.api.thegrid.ai/v1` **Auth header:** `x-api-key: YOUR_GRID_API_KEY` (not `Authorization: Bearer`)

{% tabs %}
{% tab title="Python (anthropic-sdk-python)" %}

```python
from anthropic import Anthropic

client = Anthropic(
    base_url="https://messages-beta.api.thegrid.ai/v1",  # was: https://api.anthropic.com
    api_key="your-grid-api-key",                          # from app.thegrid.ai/profile/api-keys
)

response = client.messages.create(
    model="text-prime",                                   # was: claude-sonnet-4-6
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
```

{% endtab %}

{% tab title="TypeScript (anthropic-sdk-typescript)" %}

```typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://messages-beta.api.thegrid.ai/v1",
  apiKey: "your-grid-api-key",
});

const response = await client.messages.create({
  model: "text-prime",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});
```

{% endtab %}

{% tab title="curl" %}

```bash
curl https://messages-beta.api.thegrid.ai/v1/messages \
  -H "x-api-key: YOUR_GRID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "text-prime",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What makes a commodity market work?"}
    ]
  }'
```

{% endtab %}
{% endtabs %}

### Path 1 capabilities

* The `messages` array format with `user` and `assistant` roles
* The `system` parameter (separate from the messages array, the way Anthropic's SDK takes it)
* Streaming via `client.messages.stream()` or `stream=True`
* Tool use blocks (the Anthropic format)
* `max_tokens`, `temperature`, `top_p`, `stop_sequences`

### Path 1 limitations

* `anthropic-beta` headers. Features behind those headers (prompt caching, computer use, extended thinking) are Anthropic-specific.
* Artifacts and MCP passthrough. Anthropic product features, not inference.
* Anthropic's Files API and Batch API.

The Messages API endpoint is in beta and can change without notice. If you need long-term stability, use Path 2.

## Path 2: OpenAI SDK against the Consumption API

The Consumption API is our primary, stable API. It's OpenAI-compatible: same request body, same response shape, same streaming, same SDK. Migrating from Anthropic means swapping to the OpenAI SDK and pointing it at The Grid.

**Endpoint:** `https://api.thegrid.ai/v1` **Auth header:** `Authorization: Bearer YOUR_GRID_API_KEY`

{% tabs %}
{% tab title="Python (OpenAI SDK)" %}

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.thegrid.ai/v1",
    api_key="your-grid-api-key",          # from app.thegrid.ai/profile/api-keys
)

response = client.chat.completions.create(
    model="text-prime",                    # was: claude-sonnet-4-6
    max_tokens=1024,
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello"},
    ],
)
```

{% endtab %}

{% tab title="TypeScript (OpenAI SDK)" %}

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.thegrid.ai/v1",
  apiKey: "your-grid-api-key",
});

const response = await client.chat.completions.create({
  model: "text-prime",
  max_tokens: 1024,
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello" },
  ],
});
```

{% endtab %}

{% tab title="curl" %}

```bash
curl https://api.thegrid.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-prime",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What makes a commodity market work?"}
    ],
    "max_tokens": 1024
  }'
```

{% endtab %}
{% endtabs %}

### Path 2 differences

* **Message format.** OpenAI's `chat.completions` uses a flat `messages` array with `role: "system"` instead of a separate `system` parameter.
* **Tool calling.** Uses the OpenAI `tools` and `tool_calls` schema, not Anthropic's tool use blocks. If you were using LangChain, LiteLLM, or another abstraction layer, the schema is handled for you and you mostly just change the provider config.
* **Response shape.** `choices[0].message.content` instead of `content[0].text`.

If you already use a cross-provider library (LangChain, LiteLLM, Vercel AI SDK), Path 2 is usually a config change rather than a code change.

## Model mapping

If you're migrating a Sonnet-based application, Text Prime is your starting point. Switch per-request as evidence accumulates. The full list is in [Current instruments](/docs/instrument-specifications/current-instruments.md).

### General text and reasoning

| What you use today | Recommended Grid instrument | Typical use cases                                              |
| ------------------ | --------------------------- | -------------------------------------------------------------- |
| Claude 4.6 Opus    | `text-max`                  | Deep reasoning, frontier-class research, long-context analysis |
| Claude Sonnet 4.6  | `text-prime`                | Everyday workhorse: coding, writing, Q\&A, analysis            |
| Claude Haiku 4.5   | `text-standard`             | High-throughput, classification, extraction, fast tasks        |

### Code generation (preview)

| What you use today           | Recommended Grid instrument | Typical use cases                                          |
| ---------------------------- | --------------------------- | ---------------------------------------------------------- |
| Claude 4.6 Opus (for code)   | `code-max`                  | Complex architecture, multi-file debugging, deep refactors |
| Claude Sonnet 4.6 (for code) | `code-prime`                | Daily coding: completion, review, standard debugging       |
| Claude Haiku 4.5 (for code)  | `code-standard`             | Autocomplete, linting, fast inline suggestions             |

### Agent tool calling (preview)

| What you use today            | Recommended Grid instrument | Typical use cases                                            |
| ----------------------------- | --------------------------- | ------------------------------------------------------------ |
| Claude 4.6 Opus (agent use)   | `agent-max`                 | Autonomous multi-step tasks, deep tool chains                |
| Claude Sonnet 4.6 (agent use) | `agent-prime`               | Reliable multi-step tool use, standard agent loops           |
| Claude Haiku 4.5 (agent use)  | `agent-standard`            | Fast tool calls, simple loops, high-throughput orchestration |

## Five differences from Anthropic that apply to both paths

* **Instrument strings, not model names.** Passing `claude-sonnet-4-6` returns a 404. Use one of [our nine instruments](/docs/instrument-specifications/current-instruments.md): `text-prime`, `code-max`, and so on.
* **Pricing is market-driven.** Per million tokens, set by supply and demand. Live pricing is in the app at [thegrid.ai/pricing](https://thegrid.ai/pricing).
* **Balance management.** Set up Auto-Reload in the dashboard to avoid `402` errors. See [Best practices](/docs/integrations-and-best-practices/best-practices.md).
* **No `anthropic-beta` features.** Prompt caching, computer use, and extended thinking are Anthropic-specific. Our instruments have their own capability profiles defined by benchmark specifications. The pool of qualifying suppliers updates as benchmarks run.
* **No Artifacts, no MCP passthrough.** Anthropic product features, not inference.

## After the switch, route honestly and handle retries

Read [Routing patterns](/docs/integrations-and-best-practices/routing-patterns.md) to allocate workloads honestly across tiers. The bulk of the savings come from running each request on the cheapest tier that meets your quality bar. For error handling, retries, and balance monitoring, see [Best practices](/docs/integrations-and-best-practices/best-practices.md) and [Troubleshooting](/docs/integrations-and-best-practices/troubleshooting.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://thegrid.ai/docs/integrations-and-best-practices/migrating-from-anthropic.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.