Claude Messages API Guide

The Claude Messages API accepts structured conversation turns and returns one assistant message. Sublyx exposes an Anthropic Messages-compatible endpoint at https://api.sublyx.org/v1/messages, allowing Claude clients to use a unified Sublyx key and account.

Minimal Claude Messages request

curl https://api.sublyx.org/v1/messages \
  -H "Authorization: Bearer $SUBLYX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 300,
    "messages": [
      {"role": "user", "content": "Explain token rate limits briefly."}
    ]
  }'

The model ID above is an example from the current Sublyx catalog. Always confirm the available model and its limits in the model catalog because aliases and versions can change.

Endpoint, headers and authentication

Field	Value	Purpose
Endpoint	POST https://api.sublyx.org/v1/messages	Creates a Claude message.
Authorization	Bearer YOUR_KEY	Recommended Sublyx authentication.
Alternative key header	x-api-key: YOUR_KEY	Supported by the documented compatible entry point.
API version	anthropic-version: 2023-06-01	Selects the Messages API contract.
Content type	application/json	Required for the request body.

Do not send two different keys in different headers. It makes authentication failures difficult to diagnose and can cause a client library to use a stale credential.

Core request parameters

Parameter	Required	Meaning
model	Yes	The Claude model ID available to the account.
max_tokens	Yes	The maximum number of tokens Claude may generate.
messages	Yes	Alternating user and assistant conversation turns.
system	No	Top-level system instructions; it is not a system role inside messages.
temperature	No	Sampling variability. Use conservative values for repeatable workflows.
top_p	No	Nucleus sampling control; avoid tuning it and temperature without a test plan.
stop_sequences	No	Custom sequences that stop generation.
stream	No	Requests incremental server-sent events.
tools	No	Declares tools Claude may call.
tool_choice	No	Controls tool selection when supported.

System prompts and multi-turn messages

Claude Messages places system instructions in a top-level system field. Conversation turns go in messages. Preserve only history required for the current answer; repeatedly sending an entire conversation increases input tokens, latency, and the chance of hitting a token rate limit.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 500,
  "system": "You are a concise production API reviewer.",
  "messages": [
    {"role": "user", "content": "Review this retry policy."},
    {"role": "assistant", "content": "Share the policy and constraints."},
    {"role": "user", "content": "Maximum four retries with jitter."}
  ]
}

Python request

import os
import requests

response = requests.post(
    "https://api.sublyx.org/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['SUBLYX_API_KEY']}",
        "anthropic-version": "2023-06-01",
        "content-type": "application/json",
    },
    json={
        "model": "claude-sonnet-4-6",
        "max_tokens": 300,
        "messages": [{"role": "user", "content": "Define a circuit breaker."}],
    },
    timeout=(10, 120),
)
response.raise_for_status()
print(response.json())

Node.js request

const response = await fetch("https://api.sublyx.org/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUBLYX_API_KEY}`,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-6",
    max_tokens: 300,
    messages: [{ role: "user", content: "Explain request coalescing." }],
  }),
});

if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(await response.json());

Streaming and stop reasons

With stream: true, the server sends incremental events rather than one final JSON document. A production consumer should parse event types, append text deltas in order, capture usage information, recognize normal message completion, and treat a disconnected stream as an incomplete result.

The final response can include a stop reason such as a natural end, a maximum-token boundary, a custom stop sequence, or a tool-use transition. Do not assume every successful HTTP response contains only plain text; content can be represented as typed blocks.

Tool use

A tool definition gives Claude a name, description, and JSON input schema. The model proposes a tool call; your application validates the input, executes trusted code, then sends the result back in a later message. Never execute model-generated arguments without schema validation, authorization checks, timeouts, and output-size limits.

Tool calling is an application protocol, not permission to run arbitrary code. The server remains responsible for access control, validation, side-effect safety, and audit logs.

Rate limits and common errors

Status	Likely cause	Action
400	Invalid body, role sequence, parameter, or model input.	Fix the request; do not retry unchanged.
401	Missing or invalid key.	Check host, header and key status.
402	Insufficient Sublyx balance.	Check the account before retrying.
429	Request, token, concurrency, or account quota.	Respect retry guidance, reduce load, and back off.
5xx	Gateway or upstream failure.	Retry a limited number of times with jitter.

Long prompts can exhaust token throughput even when request count is low. Record input size, requested output, model, status, request ID, and retry count. Read the general AI API 429 guide for queue and backoff patterns.

Claude Code configuration

export ANTHROPIC_BASE_URL=https://api.sublyx.org
export ANTHROPIC_API_KEY=your-sublyx-key
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

Use one authentication variable and verify the configured model exists. If Claude Code reports an authentication conflict, remove stale token variables instead of repeatedly regenerating keys.

Native Anthropic vs compatible behavior

The endpoint and core Messages structure are compatible, but model availability, billing, rate limits, routing, and some newly introduced provider features may differ. Confirm native details in the Anthropic Messages documentation and confirm Sublyx availability in the console. Do not assume a newly announced beta header or feature is forwarded until it has been tested.