Multi-turn Conversation

curl --request POST \
  --url https://api.anthropic.com/v1/messages/multi-turn \
  --header 'Content-Type: application/json' \
  --header 'anthropic-version: <anthropic-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "My name is Chisaneme and I am a technical writer."
    },
    {
      "role": "assistant",
      "content": "Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?"
    },
    {
      "role": "user",
      "content": "What is my name and what do I do?"
    }
  ]
}
'

import requests

url = "https://api.anthropic.com/v1/messages/multi-turn"

payload = {
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": "My name is Chisaneme and I am a technical writer."
        },
        {
            "role": "assistant",
            "content": "Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?"
        },
        {
            "role": "user",
            "content": "What is my name and what do I do?"
        }
    ]
}
headers = {
    "anthropic-version": "<anthropic-version>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'anthropic-version': '<anthropic-version>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    messages: [
      {role: 'user', content: 'My name is Chisaneme and I am a technical writer.'},
      {
        role: 'assistant',
        content: 'Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?'
      },
      {role: 'user', content: 'What is my name and what do I do?'}
    ]
  })
};

fetch('https://api.anthropic.com/v1/messages/multi-turn', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.anthropic.com/v1/messages/multi-turn",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'claude-sonnet-4-6',
    'max_tokens' => 1024,
    'messages' => [
        [
                'role' => 'user',
                'content' => 'My name is Chisaneme and I am a technical writer.'
        ],
        [
                'role' => 'assistant',
                'content' => 'Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?'
        ],
        [
                'role' => 'user',
                'content' => 'What is my name and what do I do?'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "anthropic-version: <anthropic-version>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.anthropic.com/v1/messages/multi-turn"

	payload := strings.NewReader("{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is Chisaneme and I am a technical writer.\"\n    },\n    {\n      \"role\": \"assistant\",\n      \"content\": \"Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"What is my name and what do I do?\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("anthropic-version", "<anthropic-version>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.anthropic.com/v1/messages/multi-turn")
  .header("anthropic-version", "<anthropic-version>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is Chisaneme and I am a technical writer.\"\n    },\n    {\n      \"role\": \"assistant\",\n      \"content\": \"Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"What is my name and what do I do?\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.anthropic.com/v1/messages/multi-turn")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["anthropic-version"] = '<anthropic-version>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is Chisaneme and I am a technical writer.\"\n    },\n    {\n      \"role\": \"assistant\",\n      \"content\": \"Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"What is my name and what do I do?\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-4-6",
  "stop_reason": "end_turn",
  "stop_details": {},
  "usage": {
    "input_tokens": 17,
    "output_tokens": 12,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  },
  "request_id": "req_011CdDNcA4MfikfhDdfNYDNj"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  },
  "request_id": "req_011CdDNcA4MfikfhDdfNYDNj"
}

POST

messages

multi-turn

Multi-turn Conversation

curl --request POST \
  --url https://api.anthropic.com/v1/messages/multi-turn \
  --header 'Content-Type: application/json' \
  --header 'anthropic-version: <anthropic-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "My name is Chisaneme and I am a technical writer."
    },
    {
      "role": "assistant",
      "content": "Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?"
    },
    {
      "role": "user",
      "content": "What is my name and what do I do?"
    }
  ]
}
'

import requests

url = "https://api.anthropic.com/v1/messages/multi-turn"

payload = {
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": "My name is Chisaneme and I am a technical writer."
        },
        {
            "role": "assistant",
            "content": "Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?"
        },
        {
            "role": "user",
            "content": "What is my name and what do I do?"
        }
    ]
}
headers = {
    "anthropic-version": "<anthropic-version>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'anthropic-version': '<anthropic-version>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    messages: [
      {role: 'user', content: 'My name is Chisaneme and I am a technical writer.'},
      {
        role: 'assistant',
        content: 'Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?'
      },
      {role: 'user', content: 'What is my name and what do I do?'}
    ]
  })
};

fetch('https://api.anthropic.com/v1/messages/multi-turn', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.anthropic.com/v1/messages/multi-turn",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'claude-sonnet-4-6',
    'max_tokens' => 1024,
    'messages' => [
        [
                'role' => 'user',
                'content' => 'My name is Chisaneme and I am a technical writer.'
        ],
        [
                'role' => 'assistant',
                'content' => 'Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?'
        ],
        [
                'role' => 'user',
                'content' => 'What is my name and what do I do?'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "anthropic-version: <anthropic-version>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.anthropic.com/v1/messages/multi-turn"

	payload := strings.NewReader("{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is Chisaneme and I am a technical writer.\"\n    },\n    {\n      \"role\": \"assistant\",\n      \"content\": \"Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"What is my name and what do I do?\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("anthropic-version", "<anthropic-version>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.anthropic.com/v1/messages/multi-turn")
  .header("anthropic-version", "<anthropic-version>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is Chisaneme and I am a technical writer.\"\n    },\n    {\n      \"role\": \"assistant\",\n      \"content\": \"Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"What is my name and what do I do?\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.anthropic.com/v1/messages/multi-turn")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["anthropic-version"] = '<anthropic-version>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"claude-sonnet-4-6\",\n  \"max_tokens\": 1024,\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"My name is Chisaneme and I am a technical writer.\"\n    },\n    {\n      \"role\": \"assistant\",\n      \"content\": \"Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?\"\n    },\n    {\n      \"role\": \"user\",\n      \"content\": \"What is my name and what do I do?\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-4-6",
  "stop_reason": "end_turn",
  "stop_details": {},
  "usage": {
    "input_tokens": 17,
    "output_tokens": 12,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  },
  "request_id": "req_011CdDNcA4MfikfhDdfNYDNj"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  },
  "request_id": "req_011CdDNcA4MfikfhDdfNYDNj"
}

Overview

The Claude API is stateless — Claude has no memory between requests. Every request starts fresh. To maintain context across a conversation, your application must pass the full conversation history with every request. This is not a limitation, it is a deliberate design decision that gives developers complete control over what context Claude sees at any point in the conversation.

How Context Works

Every message in the conversation is passed as an object in the messages array. Claude reads the entire array on every request and responds based on the full history you provide.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "My name is Chisaneme and I am a technical writer."
    },
    {
      "role": "assistant",
      "content": "Nice to meet you, Chisaneme! Technical writing is a great field. How can I help you today?"
    },
    {
      "role": "user",
      "content": "What is my name and what do I do?"
    }
  ]
}

Claude’s response to the third message:

“Your name is Chisaneme and you are a technical writer.”

Claude knew the answer because you passed the full history. Without it, Claude would have no context.

The Alternating Role Pattern

Messages must strictly alternate between user and assistant roles: user → assistant → user → assistant → user The array must always:

Start with a user message
Alternate between user and assistant roles throughout

The API does not always throw an error for consecutive messages of the same role — but the behavior is unpredictable. In real testing, two consecutive user messages caused Claude to answer only the second message and silently drop context from the first. Always maintain the alternating pattern for reliable behavior.

Token Accumulation

Every message in the history consumes input tokens. As a conversation grows, input tokens increase with every request:

Turn	Messages in History	Input Tokens
1	1 user message	17
2	1 user + 1 assistant	38
3	2 user + 1 assistant	63
4	2 user + 2 assistant	91

Input tokens are billed on every request — a long conversation history means higher costs on every subsequent turn.

For long-running conversations, consider summarizing older messages into a single context block rather than passing the full raw history. This keeps token counts manageable without losing important context.

Context Window Limit

The total conversation history including all messages and the system prompt, must fit within the model’s context window:

Model	Context Window
`claude-sonnet-4-6`	200,000 tokens
`claude-opus-4-6`	200,000 tokens
`claude-haiku-4-5`	200,000 tokens

200,000 tokens is approximately 150,000 words. For most applications this limit is rarely reached — but document-heavy or very long conversations can approach it. If the limit is exceeded the API returns:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "prompt is too long: 201000 tokens > 200000 maximum"
  }
}

Who Manages History

Your application manages conversation history — not the API. A typical implementation looks like this:

User sends a message
Your app appends it to the history array as a user turn
Your app sends the full history to the API
Claude responds
Your app appends Claude’s response to the history as an assistant turn
Repeat from step 1

The API receives the full history every time. It never stores anything between requests.

Messages

Deep dive into the messages array structure

Tokens

How token accumulation affects cost in long conversations

System Prompt

Add a system prompt to shape behavior across all turns

Tool Use

Maintain context across tool use cycles

Authorizations

x-api-key

string

header

required

Headers

anthropic-version

string

required

Example:

"2023-06-01"

Body

application/json

model

enum<string>

required

The Claude model to use.

Available options:

claude-sonnet-4-6,

claude-opus-4-6,

claude-haiku-4-5

Example:

"claude-sonnet-4-6"

max_tokens

integer

required

Maximum number of output tokens to generate.

Required range: x >= 1

Example:

1024

messages

object[]

required

Show child attributes

Response

Successful response

string

Example:

"msg_01XFDUDYJgAACzvnptvVoYEL"

type

string

Example:

"message"

role

string

Example:

"assistant"

content

object[]

Show child attributes

model

string

Example:

"claude-sonnet-4-6"

stop_reason

enum<string>

Available options:

end_turn,

max_tokens,

stop_sequence,

tool_use

Example:

"end_turn"

stop_details

object | null

usage

object

Show child attributes

System Prompt Streaming

Endpoints

Multi-turn Conversation

Overview

How Context Works

The Alternating Role Pattern

Token Accumulation

Context Window Limit

Who Manages History

Further Reading

Messages

Tokens

System Prompt

Tool Use

Authorizations

Headers

Body

Response

​Overview

​How Context Works

​The Alternating Role Pattern

​Token Accumulation

​Context Window Limit

​Who Manages History

​Further Reading

Messages

Tokens

System Prompt

Tool Use

Authorizations

Headers

Body

Response

Overview

How Context Works

The Alternating Role Pattern

Token Accumulation

Context Window Limit

Who Manages History

Further Reading