Your First Request (curl)

The Messages API is one endpoint. Send a POST with a model, max_tokens, and messages.

Everything you do with the Claude API goes through a single endpoint: POST https://api.anthropic.com/v1/messages.

The required pieces

  • Headers — x-api-key (your key) and anthropic-version: 2023-06-01.
  • Body — a JSON object with model, max_tokens, and a messages array.

The messages array

Each message has a role (user or assistant) and content. Your conversation always starts with a user message.

A Messages API request and its responseRequest (you send)POST /v1/messagesx-api-key: ...model: claude-opus-4-8max_tokens: 256messages: [ user: "Hi" ]Response (Claude sends)role: assistantcontent: [ text: "Hello!" ]stop_reason: end_turnusage: { input, output }
You send a request; Claude returns a structured response with content, a stop reason, and token usage.

Example

Example · bash
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

When to use it

  • Test your API key and confirm the endpoint works before adding the SDK to your project.
  • Prototype a prompt shape quickly from the terminal before writing any Node code.
  • Script a one-off content-generation task using curl in a bash pipeline without a full Node project.

More examples

Minimal curl POST to Messages API

The three required headers and a minimal JSON body — the absolute minimum to get a response.

Example · bash
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":64,"messages":[{"role":"user","content":"Hello"}]}'

Pretty-print the JSON response

Pipes the raw response through Python's json.tool to make the structure readable in the terminal.

Example · bash
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":64,"messages":[{"role":"user","content":"Ping"}]}' \
  | python3 -m json.tool

Extract just the text from the reply

Uses a one-liner Python pipe to pull out only the text field from the response content array.

Example · bash
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":64,"messages":[{"role":"user","content":"What year is it?"}]}' \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['content'][0]['text'])"

Related

claude api js sdkclaude api systemclaude api responses

Discussion

  • Be the first to comment on this lesson.