Use Anthropic Messages

Send a direct Messages request

For direct HTTP, use the complete path POST https://api.provod.ai/v1/messages, Bearer authorization, and an Anthropic version header:

export PROVOD_API_KEY="sk_..."

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/messages \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 64,
    "messages": [
      { "role": "user", "content": "Reply with ok" }
    ]
  }'

A representative response is:

{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    { "type": "text", "text": "ok" }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "output_tokens": 1
  }
}

For this text-only request, read the answer from content[0].text. Real responses can contain more than one content block, including tool-use blocks, so clients should branch on each block's type.

Direct HTTP uses /v1/messages; Claude Code receives the base URL without /v1.

Choose Messages when the client expects its format

Messages is an Anthropic-compatible wire format: its request fields, content blocks, response shape, and streaming events follow that client contract. Streaming means receiving incremental events before the final completion. The endpoint is not restricted to Anthropic models: it accepts supported chat model IDs from the current provod.ai catalog and aliases published for those models.

Current shipped examples include these canonical ID and alias pairs:

Use GET /v1/models for the current catalog. Clients that send anthropic-version or identify as Claude receive Anthropic-shaped model discovery with the preferred published IDs. Do not invent an alias by removing punctuation from an arbitrary model ID.

Use /v1/chat/completions when your client expects OpenAI Chat Completions fields and response choices. Use /v1/messages when it expects Anthropic Messages content blocks. Model ownership does not decide the endpoint; the client protocol does.

Handle Messages streams safely

Set stream: true to receive Anthropic SSE. A successful text stream follows this event sequence and terminates at message_stop; Messages does not send an OpenAI [DONE] marker:

event: message_start
data: {"type":"message_start","message":{"id":"msg_example","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-6","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":8,"output_tokens":0}}}

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":"ok"}}

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":1}}

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

An Anthropic error event can use this shape. Do not rely on receiving one: depending on when the failure occurs, the connection can close before message_stop without a final event.

event: error
data: {"type":"error","error":{"type":"api_error","message":"Request failed"}}

Treat event: error or a connection close before message_stop as incomplete. A bounded retry is reasonable only before any content delta arrives. Once a content_block_delta has delivered output, keep the partial result and do not retry automatically because replaying the request can duplicate work and cost.

Connect Claude Code with the correct base

Claude Code appends /v1/messages itself, so set ANTHROPIC_BASE_URL=https://api.provod.ai without /v1. Follow the dedicated Claude Code guide for installer and manual paths, explicit model selection, and verification.

A public error code is a client-facing code in an API error response. The Messages error envelope is Anthropic-shaped, so also record its error.type, HTTP status, exact endpoint, and message when a separate error.code is not present.

Troubleshooting