POST/v1/messages

Create a message

The Anthropic Messages API, the protocol Claude Code speaks. Authenticate with x-api-key or Authorization: Bearer; errors use the Anthropic envelope. Any model in the catalog can be called here, not only Claude.

usage.cost and provider appear on the response, or on the final message_delta frame of a stream. This route does not honor Idempotency-Key (Anthropic defines none).

Authentication: Bearer API key in the Authorization header

Headers

  • anthropic-versionstring

    Accepted for SDK compatibility.

  • anthropic-betastring

    Beta tokens. Forwarded to Anthropic routes where the feature needs them.

Request body

  • modelstringrequired

    A slug from GET /v1/models. Anthropic's dashed ids (claude-sonnet-5-5) are accepted spellings of the dotted slug; dated ids are not.

  • max_tokensintegerrequired

    Required output cap. Lowered to the model's maximum when above it.

  • messagesarray<object>required

    Alternating user and assistant turns of text, image, document, tool_use, tool_result and thinking blocks.

  • systemstring | array<object>

    System prompt.

  • streamboolean
    Default: false
  • temperaturenumber
  • top_pnumber
  • top_kinteger
  • stop_sequencesarray<string>
  • toolsarray<object>

    Custom tools, plus the web search, advisor and tool search server tools.

  • tool_choiceobject
  • thinkingobject

    Forwarded to models that honor it, for example {"type": "enabled", "budget_tokens": 4000}.

  • metadataobject
  • providerobject

    OpenRouter's routing-preference object, resolved against the model's own provider routes. Only tightens, never loosens, your organization's policy.

    provider
    • zdrboolean

      true serves only zero-data-retention routes for this request, or refuses with a 403 naming the excluded providers.

    • onlyarray<string>

      Keep only these providers.

    • ignorearray<string>

      Drop these providers.

    • orderarray<string>

      Try these providers first, in order; the rest stay as fallbacks.

    • allow_fallbacksboolean

      false with order serves only the listed providers; without order, only the first eligible route.

  • gatewayobject

    Per-request retry and routing bounds, never sent to a provider. SDKs send it through extra_body.

    gateway
    • retryobject
      retry
      • max_attempts_per_routeinteger

        Calls per route, including the first. Default 2.

      • max_total_attemptsinteger

        Calls in total, including retries and fallbacks. Default 8.

      • backoffobject

        {"type": "none"} or {"type": "exponential", "base_delay_ms", "max_delay_ms", "multiplier"} (defaults 500, 8000, 2).

    • routingobject
      routing
      • allow_fallbacksboolean

        false keeps the first eligible route; no failover.

        Default: true
      • route_idstring

        Pin a route by its opaque handle (route_ + 64 hex), from GET /api/models/{slug}/providers.

Responses

  • 200

    The message. With stream set, Anthropic's stream events.

    Response
    • idstring
    • typestring
    • rolestring
    • modelstring
    • providerstring

      Experiential extension. The provider that served this request.

    • contentarray<object>
    • stop_reasonstring | null
    • stop_sequencestring | null
    • usageany
      usage
      • input_tokensinteger
      • output_tokensinteger
      • cache_creation_input_tokensinteger
      • cache_read_input_tokensinteger
      • costnumber

        USD actually charged to your credits for this request, as a float (promotions and plan discounts already applied). 0 on your own provider key.

      • is_byokboolean

        True when the request ran on your own provider key, which the platform never charges.

      • cost_detailsobject

        Present only in two cases: upstream_inference_cost (USD, your own key: the provider's list charge to you) or list_cost (USD, a platform-funded call charged below list: what it would have cost).

        cost_details
        • upstream_inference_costnumber
        • list_costnumber
  • 400

    Invalid request, in the Anthropic envelope. The message names the field.

    Response
    • typestring
    • errorobject
      error
      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, api_error.

      • messagestring
  • 401

    The key is missing or invalid.

    Response
    • typestring
    • errorobject
      error
      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, api_error.

      • messagestring
  • 402

    The organization must act first (card verification, account review). The message names the step.

    Response
    • typestring
    • errorobject
      error
      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, api_error.

      • messagestring
  • 403

    The model is not callable by this key.

    Response
    • typestring
    • errorobject
      error
      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, api_error.

      • messagestring
  • 429

    Rate limited (wait Retry-After) or out of credits (add credits).

    Response
    • typestring
    • errorobject
      error
      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, api_error.

      • messagestring
  • 503

    Temporarily unavailable. Retry with backoff.

    Response
    • typestring
    • errorobject
      error
      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, api_error.

      • messagestring

Request

curl https://api.experientiallabs.ai/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5.5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Explain a mutex in one sentence."}]
  }'

Response

{
  "id": "msg_3c9e1a7f5b2d48e0a6c4f1b8d2e5a970",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5.5",
  "provider": "anthropic",
  "content": [
    {
      "type": "text",
      "text": "A mutex is a lock that lets only one thread at a time enter a critical section."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 16,
    "output_tokens": 22,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "cost": 0.000252,
    "is_byok": false
  }
}

https://api.experientiallabs.ai/v1/messages