Skip to content
Nexus Docs
↑↓Navigate↵SelectescClose

0012 - Anthropic Messages-compatible edge as a second gateway dialect

Native Anthropic Messages edge decision for agentic SDK clients

Last updated on:
  • Status: Accepted
  • Date: 2026-06-14
  • Deciders: nexus core team
  • Tags: gateway, wire-contract, sdk, edge
  • Supersedes: none

Context and Problem Statement

Section titled “Context and Problem Statement”

0005 - OpenAI-compatible API as the gateway contract chose the OpenAI-compatible shape as the primary gateway edge and deferred an Anthropic Messages edge as an additive expansion. Agentic clients — Claude Code, the official Anthropic Python and TypeScript SDKs, and tools that speak the Anthropic Messages wire — expect the native request body, SSE event sequence, error envelope, and /v1/messages path layout.

Serving those clients through the OpenAI edge would require every caller to accept an OpenAI translation layer and would drop or re-derive Anthropic-only fields (thinking, signed thinking blocks, per-block cache_control, block-array system, anthropic-beta headers) on cross-provider routes.

Decision Drivers

Section titled “Decision Drivers”
  • Claude Code and the Anthropic SDKs must work with a base-URL swap and a nexus API key only.
  • Extended-thinking signatures and prompt-cache hints must survive routing when the selected upstream is Anthropic.
  • Classification, routing, fallback, policy, audit, analytics, and cost accounting must match the OpenAI edge for the same logical request.
  • The OpenAI /v1/* namespace must remain reserved for the OpenAI-compatible contract.

Considered Options

Section titled “Considered Options”
  • OpenAI edge only with client-side adaptation — Rejected: loses native SSE, error shapes, and thinking/cache fidelity.
  • Parallel Anthropic pipeline — Rejected: duplicates policy, audit, and routing logic.
  • Translator edge over the shared attempt pipeline (chosen) — Anthropic-shaped HTTP in and out; internal OpenAI-shaped contract plus a native-field preservation envelope for Anthropic-targeted attempts.

Decision Outcome

Section titled “Decision Outcome”

Chosen option: a native Anthropic Messages edge mounted under /anthropic.

Contract surface:

  • POST /anthropic/v1/messages — Anthropic Messages request and response bodies, buffered or streaming.
  • POST /anthropic/v1/messages/count_tokens — returns {"input_tokens": N}; proxies to Anthropic when the resolved route targets Anthropic, otherwise returns a documented byte-length estimate.
  • Authentication: nexus API key via x-api-key: nxs_... (Anthropic SDK default) or Authorization: Bearer nxs_.... Upstream Anthropic credentials are never accepted at the edge.
  • Errors: {"type": "error", "error": {"type", "message"}} with Anthropic status conventions (invalid_request_error 400, authentication_error 401, permission_error 403, not_found_error 404, rate_limit_error 429, overloaded_error 529, api_error 500).
  • Streaming: Anthropic SSE (event: + data: frames); terminal upstream failures after bytes were sent surface as an in-band error event.
  • Unknown routes under /anthropic return not_found_error with HTTP 404.
  • Native-only fields ride a preservation envelope attached to the internal request; Anthropic-targeted attempts reconstruct upstream bodies from the raw inbound JSON, non-Anthropic attempts receive a stripped OpenAI-shaped body. Extended thinking pins to Anthropic upstreams.

This edge is a second dialect, not a replacement for 0005 - OpenAI-compatible API as the gateway contract’s primary OpenAI edge. Both share AttemptBuilder, AttemptExecutor, registry resolution, and analytics.

Consequences

Section titled “Consequences”
  • Anthropic SDK clients and Claude Code point ANTHROPIC_BASE_URL at https://<gateway>/anthropic and supply a nexus key.
  • Certification suites in test-suite/compat/ and test-suite/node/ lock the pinned SDK versions named in test-suite/compat/spec/anthropic-sdk-provenance.json.
  • Wire details live in the Wire Contracts reference.
  • The edge is mounted under the /anthropic prefix and the SDK appends /v1/messages; clients set ANTHROPIC_BASE_URL to the gateway’s /anthropic URL.

More Information

Section titled “More Information”