POST /v1/messages

The /v1/messages endpoint is Anthropic-native. Claude Code, the Anthropic Python/TypeScript SDK, and any agent built against Anthropic’s Messages API works unchanged by pointing at the gateway. Beyond plain pass-through, the gateway preserves tool-call streaming deltas byte-for-byte (load-bearing for agentic CLIs) and forwards cache_control blocks identically (load-bearing for the 90% Anthropic cache discount).

Request

POST /v1/messages
x-api-key: vk-lw-<ULID>     # or Authorization: Bearer vk-lw-...
anthropic-version: 2023-06-01
Content-Type: application/json

Body matches Anthropic’s Messages API verbatim. Example:

{
  "model":      "claude-haiku-4-5-20251001",
  "max_tokens": 1024,
  "system":     "You are concise.",
  "messages":   [
    { "role": "user", "content": "Hi" }
  ],
  "stream":     false,
  "temperature": 0.2,
  "tools":      [...],
  "tool_choice": {"type": "auto"}
}

Anthropic requires max_tokens, omitting it returns a 400 from upstream which the gateway surfaces.

Cache-aware system prompts

{
  "model":      "claude-sonnet-4-6",
  "max_tokens": 2048,
  "system":     [
    {
      "type": "text",
      "text": "Very long system prompt here (30k tokens+)...",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages":   [
    { "role": "user", "content": "What's the first paragraph?" }
  ]
}

cache_control blocks are forwarded byte-identically to upstream Anthropic by default (see Caching Passthrough).

LangWatch-specific headers

Same as POST /v1/chat/completions:

X-LangWatch-Cache: respect|force|disable|ttl=<s>
X-LangWatch-Trace-Metadata: {...}
Trace-context headers (traceparent, X-LangWatch-Trace-Id, etc.), see SDKs → trace propagation.

Response (non-streaming)

Anthropic-shaped. Response headers:

HTTP/1.1 200 OK
Content-Type: application/json
X-LangWatch-Request-Id: grq_01HZX9K3M...
X-LangWatch-Provider: anthropic
X-LangWatch-Model: claude-haiku-4-5-20251001
X-LangWatch-Cache: hit

{
  "id":            "msg_01...",
  "type":          "message",
  "role":          "assistant",
  "content":       [{"type": "text", "text": "Hi!"}],
  "model":         "claude-haiku-4-5-20251001",
  "stop_reason":   "end_turn",
  "usage": {
    "input_tokens":              12,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens":   1024,
    "output_tokens":             4
  }
}

The cache_read_input_tokens and cache_creation_input_tokens are forwarded as-is; they also flow into the debit call so budget ledgers reflect the correct cache-discounted cost.

Response (streaming)

Set "stream": true. SSE events:

event: message_start
data: {"type":"message_start","message":{"id":"msg_...","type":"message","role":"assistant","content":[],"model":"claude-haiku-4-5-20251001","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"!"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":4}}

event: message_stop
data: {"type":"message_stop"}

The gateway forwards these byte-for-byte after the first chunk, including content_block_start, content_block_delta, content_block_stop events for tool use. See Streaming for the full contract.

Tool use

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "...",
      "input_schema": {...}
    }
  ],
  "messages": [
    {"role": "user", "content": "weather in Paris?"}
  ]
}

Subject to VK policy_rules.tools, a blocked tool name returns 403 tool_not_allowed before the request leaves the gateway. See Policy Rules.

Extended thinking (Claude Opus 4.7, Sonnet 4.6)

{
  "model":      "claude-opus-4-7",
  "max_tokens": 8192,
  "thinking":   { "type": "enabled", "budget_tokens": 5000 },
  "messages":   [...]
}

Thinking tokens are billed separately by Anthropic. The gateway forwards the thinking field unchanged; usage counts appear in response.usage.thinking_tokens, roll into langwatch.usage.output_tokens on the trace, and debit the budget. (A dedicated langwatch.reasoning_tokens span attribute that separates thinking from non-thinking output tokens is a v1.1 observability follow-up.)

Routing via `model` field

model is resolved via the VK’s model_aliases map (see Model Aliases):

"claude-haiku-4-5-20251001" → VK maps to anthropic/claude-haiku-4-5-20251001 (or bedrock/..., vertex/... if the alias points there).
"claude" → whatever the VK defines as “default Claude”.
"anthropic/claude-opus-4-7" → explicit form, bypasses aliases.

If the resolved model isn’t served by any provider in the VK, returns 403 model_not_allowed.

Errors

See API: Errors: the full type enum applies. Errors use the OpenAI-compatible envelope (not Anthropic’s native {type: "error", error: {...}}) for consistency across /v1/messages and /v1/chat/completions. This is a small deviation from stock Anthropic, the tradeoff is a single error-handling code path for clients that hit both endpoints.

Example: Claude Code CLI

Claude Code uses /v1/messages natively. Setup is:

export ANTHROPIC_BASE_URL="https://gateway.langwatch.ai"
export ANTHROPIC_AUTH_TOKEN="vk-lw-..."
claude

See Claude Code for governance recipes (blocking shell tools, per-engineer budgets, fallback to Bedrock).

Get Started

SDK Integration

Coding CLI Integrations

Virtual Keys & Budgets

Governance

Providers

Features

API Reference

Self-Hosting

Cookbooks

Request

Cache-aware system prompts

LangWatch-specific headers

Response (non-streaming)

Response (streaming)

Tool use

Extended thinking (Claude Opus 4.7, Sonnet 4.6)

Routing via `model` field

Errors

Example: Claude Code CLI

​Request

​Cache-aware system prompts

​LangWatch-specific headers

​Response (non-streaming)

​Response (streaming)

​Tool use

​Extended thinking (Claude Opus 4.7, Sonnet 4.6)

​Routing via model field

​Errors

​Example: Claude Code CLI

Request

Cache-aware system prompts

LangWatch-specific headers

Response (non-streaming)

Response (streaming)

Tool use

Extended thinking (Claude Opus 4.7, Sonnet 4.6)

Routing via `model` field

Errors

Example: Claude Code CLI