> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Anthropic Messages API

> POST /ai/v2/direct/anthropic/v1/messages — Anthropic's Messages API for Claude models, so the official Anthropic SDKs work with your Gloo API key.

**Anthropic Messages** is a [direct endpoint](/api-guides/endpoint-types) that speaks Anthropic's own Messages API. Point an official Anthropic SDK at Gloo, use your Gloo API key, and your existing Claude code keeps working: the same request body, the same response and streaming events, and the same error types your SDK already handles.

**Direct endpoints add no platform fee.** You pay the model's published rate (see the Models page and `GET /platform/v2/models`).

Like the other direct endpoints, nothing here applies guardrails, output moderation, values-alignment (`tradition`) or routing. Your request goes to the Claude model you name.

## When to use it

| You have | Use |
| :- | :- |
| Code written for the Anthropic SDK or the Messages API, and you want Claude | **Anthropic Messages** (this page) |
| A new integration, or you want to switch between model providers | [Direct Responses](/api-guides/direct-responses) |
| Tooling built on OpenAI Chat Completions | [Direct Completions](/api-guides/direct-completions) |

Anthropic Messages serves **Claude models only**. To call models from other providers with the same code, use [Direct Responses](/api-guides/direct-responses) or [Direct Completions](/api-guides/direct-completions), which also serve Claude.

## Set up the SDK

**Base URL:** `https://platform.ai.gloo.com/ai/v2/direct/anthropic`

The SDK adds `/v1/messages` to the base URL. Pass your Gloo API key as the SDK's **auth token**, which sends it as `Authorization: Bearer <key>`. Get a key from the [API Keys page](/studio/manage-api-credentials) in Gloo AI Studio.

```python Python theme={null}
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://platform.ai.gloo.com/ai/v2/direct/anthropic",
    auth_token=os.environ["GLOO_API_KEY"],
)
```

```typescript TypeScript theme={null}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://platform.ai.gloo.com/ai/v2/direct/anthropic",
  authToken: process.env.GLOO_API_KEY,
});
```

> [!NOTE]
>
> Use `auth_token` (`authToken` in TypeScript), not `api_key`. The SDKs send `api_key` as an `x-api-key` header, and this endpoint reads your Gloo key from `Authorization: Bearer`. You can also set `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` in the environment and construct the client with no arguments.

## Send a message

```python Python theme={null}
message = client.messages.create(
    model="gloo-anthropic-claude-opus-5.5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain prompt caching in two sentences."}],
)
for block in message.content:
    if block.type == "text":
        print(block.text)
```

```typescript TypeScript theme={null}
const message = await client.messages.create({
  model: "gloo-anthropic-claude-opus-5.5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Explain prompt caching in two sentences." }],
});
for (const block of message.content) {
  if (block.type === "text") console.log(block.text);
}
```

```bash cURL theme={null}
curl https://platform.ai.gloo.com/ai/v2/direct/anthropic/v1/messages \
  -H "Authorization: Bearer $GLOO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gloo-anthropic-claude-opus-5.5",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Explain prompt caching in two sentences." }
    ]
  }'
```

The response is an Anthropic `message` object. Its `model` field is the model ID you sent, and `usage` reports input, output and cache tokens as Anthropic defines them.

`anthropic-version` is optional. If you send it, it must be `2023-06-01`, the version the SDKs send.

## Models

Name a Claude model by its Gloo model ID or by Anthropic's own model ID. Both of these call Claude Opus 5.5:

* `gloo-anthropic-claude-opus-5.5`
* `claude-opus-5-5`

Other current choices are Claude Sonnet 5.5 (`gloo-anthropic-claude-sonnet-5.5`) and Claude Haiku 5.5 (`gloo-anthropic-claude-haiku-5.5`). See [Supported Models](/api-guides/supported-models) for every Claude model and its rates.

* **Claude only.** A model from another provider returns `404` with `model_not_available`. Use [Direct Responses](/api-guides/direct-responses) for those models.
* **Retired models return an error instead of a replacement.** On this endpoint, a retired Claude model ID returns `404` with `model_retired`, and the message names the model to use instead. Your `thinking` and effort settings were written for the model you named, so Gloo does not move them to another model for you. (Other direct endpoints serve the replacement; see [Model Lifecycle](/api-guides/model-lifecycle).)

## Streaming

Set `stream: true`, or use the SDK's streaming helpers. Events are Anthropic's own (`message_start`, `content_block_delta`, `message_stop` and the rest), passed through as Claude sends them.

```python Python theme={null}
with client.messages.stream(
    model="gloo-anthropic-claude-opus-5.5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Write a short story about a lighthouse."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()
```

```typescript TypeScript theme={null}
const stream = client.messages.stream({
  model: "gloo-anthropic-claude-opus-5.5",
  max_tokens: 16000,
  messages: [{ role: "user", content: "Write a short story about a lighthouse." }],
});
stream.on("text", (text) => process.stdout.write(text));
const final = await stream.finalMessage();
```

* **Errors before the stream starts are real HTTP errors.** Nothing is sent until Claude's first event arrives, so a request that fails before then gets an HTTP status (`429`, `529` and so on) that your SDK can retry, never an error inside a `200`.
* **Errors after the stream starts** end the stream with an `event: error`, as on Anthropic's API.
* **Use streaming for long outputs.** A non-streaming request with `max_tokens` above 21,333 returns `400`, the same limit the SDKs apply. Long non-streaming requests can also time out with `504`.

## Thinking and effort

`thinking` and `output_config` are sent to Claude as you write them, so you control reasoning exactly as you would on Anthropic's API.

```python theme={null}
message = client.messages.create(
    model="gloo-anthropic-claude-opus-5.5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "How many prime numbers are there below 100?"}],
)
for block in message.content:
    if block.type == "thinking":
        print("Thinking:", block.thinking)
    elif block.type == "text":
        print("Answer:", block.text)
```

* **Adaptive thinking.** Claude 5 models, such as Opus 5.5 and Sonnet 5.5, think adaptively. Set the depth with `output_config.effort` (`low`, `medium`, `high`, `xhigh` or `max`).
* **Showing the reasoning.** On current Claude models, `thinking` blocks come back with empty text unless you set `display: "summarized"`, which returns a readable summary of the reasoning. With the `thinking-display-updates-2026-08-18` beta, `display: "updates"` returns short progress notes between tool calls instead.
* **Multi-turn.** You can send the assistant's turns back as the SDK returns them, thinking blocks included. Gloo doesn't pass earlier `thinking` or `redacted_thinking` blocks to the model; each new turn starts its own reasoning, and tool loops continue as normal. The `x-gloo-ignored-params` response header lists `messages.thinking` when this happens.
* **`max_tokens` covers thinking.** Thinking tokens count toward `max_tokens`. If you ask for more than the model's output limit, Gloo lowers `max_tokens` to that limit and names the value it used in the `x-gloo-adjusted-params` response header, for example `max_tokens=128000`.

See Anthropic's documentation for which thinking settings each Claude model accepts.

## Tool use

Define your own tools in `tools`, exactly as in Anthropic's API, and send results back in `tool_result` blocks. `tool_choice` is passed through.

These Anthropic-defined tools are also supported:

| Tool | `type` | Runs on |
| :- | :- | :- |
| Web search | `web_search_20250305` and later versions | Anthropic's servers. Each search is billed in addition to tokens. |
| Bash | `bash_*` | Your application, like any client tool |
| Text editor | `text_editor_*` | Your application, like any client tool |

```python theme={null}
message = client.messages.create(
    model="gloo-anthropic-claude-opus-5.5",
    max_tokens=4096,
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 3}],
    messages=[{"role": "user", "content": "What changed in the latest Python release?"}],
)
```

Other Anthropic-defined tools, such as web fetch, code execution, computer use and the memory tool, return `400` with `tool_not_supported`.

## Prompt caching

`cache_control` works as it does on Anthropic's API: set it at the top level to cache automatically, or on individual blocks for fine-grained control. Check `usage.cache_creation_input_tokens` and `usage.cache_read_input_tokens` to confirm cache hits. See [Prompt Caching](/api-guides/prompt-caching) for how cached tokens are billed.

## What the request can include

**Body fields:** `model`, `messages`, `system`, `max_tokens`, `stop_sequences`, `stream`, `temperature`, `top_p`, `top_k`, `tools`, `tool_choice`, `thinking`, `output_config`, `cache_control`, `metadata`, and `context_management` with the `context-management-2025-06-27` beta.

Any other top-level field is dropped and named in the `x-gloo-ignored-params` response header; the request still runs.

* **Content blocks:** text, images (base64 or URL), documents (base64, plain text, custom content or URL), search results, tool use and tool results, thinking blocks, and web search blocks when the request includes the web search tool. File ID sources are not supported.
* **Messages** take the `user` and `assistant` roles. Put instructions in the top-level `system` field; messages with the `system` role return `400`.
* **`metadata`:** only `user_id` is used, and Gloo does not pass your value to the model provider as you sent it.

A block, source or tool type outside these lists returns `400` naming what was refused.

### Beta features

Send betas in the `anthropic-beta` header, or with the SDK's `betas` option on `client.beta.messages`. These are supported:

| Beta | What it enables |
| :- | :- |
| `context-management-2025-06-27` | Context editing with `context_management` |
| `thinking-display-updates-2026-08-18` | `thinking.display: "updates"` |
| `interleaved-thinking-2025-05-14` | Thinking between tool calls on models that need the header |
| `fine-grained-tool-streaming-2025-05-14` | Streaming tool inputs as they are generated |

Any other beta is dropped and named in the `x-gloo-ignored-betas` response header. If the request needed that beta, Claude rejects it and you get `400` with `beta_not_forwarded`.

### Not available on this endpoint

Only `POST /v1/messages` is served. Token counting (`/v1/messages/count_tokens`) and the models list (`/v1/models`) return `404` with `endpoint_not_available`; use [`GET /platform/v2/models`](/api-reference/get-models/v2) for the model catalog. Message Batches and the Files API are not available.

## Limits

* **Request size:** up to 32 MB per request. A larger body returns `413` with `request_too_large`.
* **Concurrent requests:** each organization can have a limited number of Messages requests in flight at once. Past that, you get `429` with `rate_limit_error` and `retry-after: 1`. The SDKs retry it for you.
* **Output length:** `max_tokens` above the model's output limit is lowered to that limit (see [Thinking and effort](#thinking-and-effort)), except on non-streaming requests: there, `max_tokens` above 21,333 returns `400` rather than being lowered (see [Streaming](#streaming)).

## Errors

Errors use Anthropic's error shape, so the SDK raises its usual exception classes (`RateLimitError`, `InternalServerError` and so on) and applies its usual retry rules:

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "The model is temporarily unavailable. Retry shortly.",
    "details": {
      "code": "upstream_capacity",
      "retryable": true
    }
  },
  "request_id": "req_..."
}
```

`error.message` is safe to show your users. `error.details.code` is the value to branch on, and `details.developer_message`, when present, tells you what to change. The `request-id` header carries the same `request_id`; include it when you contact support.

| Status | `error.type` | When | What to do |
| :- | :- | :- | :- |
| `400` | `invalid_request_error` | The request is invalid, uses an unsupported tool, block or `anthropic-version`, or contains a phrase blocked on this platform | Fix the request; the message says what was refused |
| `401` | `authentication_error` | The API key is missing or invalid | Check the key and that it is sent with `auth_token` |
| `402` | `billing_error` | The organization has no credit left | Add credit in [Billing](/studio/billing) |
| `403` | `permission_error` | The API key's organization can't make this request | Check the key belongs to the right organization |
| `404` | `not_found_error` | Not a Claude model, a retired model, or an endpoint that isn't served | Use the model or path the message names |
| `413` | `request_too_large` | The body is over 32 MB | Send less, or use URL sources for large files |
| `429` | `rate_limit_error` | Too many requests in flight (`retry-after: 1`), or the organization's spending limit is reached (`spend_limit_reached`, `x-should-retry: false`) | Retry after `retry-after`; for a spending limit, raise the limit instead |
| `500` | `api_error` | Gloo couldn't complete the request | Retry with backoff |
| `504` | `timeout_error` | A non-streaming request ran too long (`x-should-retry: false`) | Use streaming |
| `529` | `overloaded_error` | Claude is temporarily unavailable, or the stream didn't start in time (`retry-after: 30`) | Retry after `retry-after`; the SDKs do this for you |

Requests on this endpoint are served by Anthropic only, with no failover to another provider, so retry a `529` rather than treating it as final.

## Pricing

You pay the Claude model's published rate for input, output and cache tokens, with no platform fee, the same as the other direct endpoints. Web searches are billed per search. See [Supported Models](/api-guides/supported-models) for rates.

## Related Documentation

> **[Endpoint Types](/api-guides/endpoint-types)**
>
> Direct, guarded and grounded endpoints compared.

> **[Direct Responses](/api-guides/direct-responses)**
>
> One request shape for every model in the catalog.

> **[API Reference](/api-reference/messages/anthropic)**
>
> Request and response fields for Anthropic Messages.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.