# Messages API The Anthropic Messages API over your org's models. Anthropic-shape requests and responses. `POST /v1/messages` serves the Anthropic Messages API. A client written for the Anthropic SDKs or Claude Code works with PrivateMind once you change its base URL and key. It runs on the same models, keys, budgets and rate limits as [chat completions](https://docs.privatemind.com/chat-completions.html), so use whichever format your code already speaks. **cURL** ```bash curl -s "https://api.privatemind.com/v1/messages" \ -H "x-api-key: $PMIND_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "fast", "max_tokens": 400, "system": "You are a concise assistant.", "messages": [ {"role": "user", "content": "Explain the CAP theorem."} ], "temperature": 0.2 }' ``` **Python** ```python import anthropic client = anthropic.Anthropic( base_url="https://api.privatemind.com", api_key="PMIND...:abcdef...", ) message = client.messages.create( model="fast", max_tokens=400, system="You are a concise assistant.", messages=[{"role": "user", "content": "Explain the CAP theorem."}], temperature=0.2, ) print(next(b.text for b in message.content if b.type == "text")) ``` **TypeScript** ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ baseURL: 'https://api.privatemind.com', apiKey: process.env.PMIND_KEY, }); const message = await client.messages.create({ model: 'fast', max_tokens: 400, system: 'You are a concise assistant.', messages: [{ role: 'user', content: 'Explain the CAP theorem.' }], temperature: 0.2, }); console.log(message.content.find((b) => b.type === 'text')?.text); ``` The base URL has no `/v1`, because the Anthropic SDKs add it. The key goes in `x-api-key` or `Authorization: Bearer` (see [Authentication](https://docs.privatemind.com/authentication.html)). The SDKs send `anthropic-version`, and hand-written clients should too: it tells shared paths such as `/v1/models` and `/v1/files` to answer in this API's shape. > [!NOTE] > On a model server registered with [No translation](https://docs.privatemind.com/model-deployments.html#no-translation), the request goes to your vLLM as sent, apart from the model name, and its answer comes back unchanged. Parameters, thinking and usage then follow your vLLM's own Messages API support. The rest of this page describes the translated path. ## Parameters - **`model`** (required): id or alias of a chat model from [`GET /v1/models`](https://docs.privatemind.com/models.html). Anthropic's own `claude-*` ids don't exist here, so use your catalog's model ids. - **`max_tokens`** (required): maximum tokens to generate, thinking included. - **`messages`** (required): alternating `user` and `assistant` turns. `content` is a string or an array of blocks: `text`, `image`, `document`, `tool_use`, `tool_result`, `thinking`. Consecutive turns with the same role are merged. See [Vision](https://docs.privatemind.com/vision.html#messages-api) and [Tool use](https://docs.privatemind.com/tool-use.html#messages-api). - **`system`**: a string or an array of `text` blocks, joined in order. - **`temperature`**, **`top_p`**, **`top_k`**: sampling controls. - **`stop_sequences`**: strings that end generation. A match reports `stop_reason: "stop_sequence"` with the matched `stop_sequence`. - **`stream`** (default `false`): when `true`, the response arrives as Messages API events. See [Streaming](https://docs.privatemind.com/streaming.html#messages-api). - **`tools`**, **`tool_choice`**: client tools with an `input_schema`. A tool's `strict` flag is passed to the model server, and whether the call is held to the schema depends on the model's engine. `tool_choice` takes `auto`, `any`, `none` or `{"type": "tool", "name": ...}`, and `disable_parallel_tool_use`. See [Tool use](https://docs.privatemind.com/tool-use.html#messages-api). - **`thinking`**, **`output_config.effort`**: how much the model thinks. See [Thinking](https://docs.privatemind.com/messages-api.html#thinking) below. - **`output_config.format`**: `{"type": "json_schema", "schema": {...}}` for structured output. - **`metadata`**: `user_id` is passed to the model as the end-user id, and other keys are ignored. Unlike `metadata` on chat completions, it isn't stored as [usage tags](https://docs.privatemind.com/usage.html#tagging-requests). A final `assistant` turn is a prefill: the model continues from its text. Fields the API does not use, such as `cache_control`, `context_management` and beta flags, are accepted and ignored, so SDK upgrades do not break calls. ## Thinking Reasoning models answer with `thinking` blocks before their text. You set how deep they think with `thinking` or `output_config.effort`, which map onto the same levels as [`reasoning_effort`](https://docs.privatemind.com/chat-completions.html#reasoning-effort) on chat completions: | You send | Effort | | --- | --- | | Nothing, or `thinking: {type: "adaptive"}` | The model's default | | `thinking: {type: "enabled", budget_tokens: N}` | `low` below 4096, `medium` below 16384, `high` from 16384 | | `output_config: {effort: "low"}`, `"medium"`, `"high"` | That level | | `output_config: {effort: "xhigh"}` or `"max"` | `max` | | `thinking: {type: "disabled"}` | `off` | Runtime modes and levels work as for [`reasoning_effort`](https://docs.privatemind.com/chat-completions.html#reasoning-effort), including a level missing from the model's [`capabilities.reasoning_effort_levels`](https://docs.privatemind.com/models.html#capabilities). A thinking-only model, such as Kimi K3.1 Pro or GLM 5.3, can't stop thinking, so it returns `400` for `thinking: {type: "disabled"}`. On a [model server you launched](https://docs.privatemind.com/model-deployments.html), the level reaches your vLLM as on [chat completions](https://docs.privatemind.com/chat-completions.html#reasoning-effort). `thinking: {display: "omitted"}` keeps the thinking blocks but empties their text. Every thinking block carries a `signature`. Send thinking blocks back unchanged in later turns, as the SDKs do, and the earlier reasoning is passed back to the model. Whether the model uses it depends on its chat template: many keep only the reasoning of the current tool loop. ## Response ```json { "id": "msg_abc123", "type": "message", "role": "assistant", "model": "fast", "content": [ { "type": "thinking", "thinking": "The user wants a short ...", "signature": "privatemind" }, { "type": "text", "text": "The CAP theorem says ..." } ], "stop_reason": "end_turn", "stop_sequence": null, "usage": { "input_tokens": 42, "output_tokens": 128, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0 } } ``` `model` echoes what you sent. Content comes thinking first, then text, then any `tool_use` blocks. ## Usage and prompt caching Prompt caching works as on [chat completions](https://docs.privatemind.com/chat-completions.html#prompt-caching): it is automatic and needs no `cache_control`. The Messages API reports it the Anthropic way. `input_tokens` counts only the part of the prompt that was not read from the cache, and `cache_read_input_tokens` counts the part that was. Their sum is the full prompt, the same number chat completions reports as `prompt_tokens`. `cache_creation_input_tokens` is always `0`: there is no cache-write charge. ## Stop reasons | Value | Meaning | | --- | --- | | `end_turn` | Natural end of the answer | | `max_tokens` | Hit `max_tokens` or the context window. If the cut falls inside a tool call, its `tool_use` input is incomplete or empty: don't run that call. Raise `max_tokens` and retry | | `stop_sequence` | One of `stop_sequences` matched; see `stop_sequence` | | `tool_use` | The model called one or more tools. See [Tool use](https://docs.privatemind.com/tool-use.html#messages-api) | | `refusal` | Output was blocked by a content filter. The models this endpoint serves do not produce it today | ## What is not supported | Feature | Behaviour | | --- | --- | | Server tools (`web_search`, `web_fetch`, `code_execution`, the MCP connector) | Not run; the model answers without them | | PDF documents | `400`, so a PDF is never silently dropped. Text documents work | | Vendor provider models (Claude served through a provider card) | `400` naming the dialect; use [chat completions](https://docs.privatemind.com/chat-completions.html) for those | ## Related endpoints | Endpoint | Page | | --- | --- | | `POST /v1/messages/count_tokens` | [Count tokens](https://docs.privatemind.com/count-tokens.html#messages-api) | | `GET /v1/models`, `GET /v1/models/{id}` | [Models](https://docs.privatemind.com/models.html#messages-api) | | `/v1/files` | [Files](https://docs.privatemind.com/files.html#messages-api) | | `/v1/messages/batches` | [Message Batches](https://docs.privatemind.com/message-batches.html) | ## Where next - [Anthropic SDK](https://docs.privatemind.com/anthropic-sdk.html) for client setup in each language. - [Streaming](https://docs.privatemind.com/streaming.html#messages-api) for the event stream. - [Coding agents](https://docs.privatemind.com/coding-agents.html#claude-code) to point Claude Code at PrivateMind. - [Errors](https://docs.privatemind.com/errors.html#messages-api) for the error shape and status codes.