Skip to main content
POST
/
v1
/
messages
claude-3-5-haiku-20241022 (web search)
curl --request POST \
  --url https://api.example.com/v1/messages
curl --location --request POST 'https://gptproto.com/v1/messages' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'anthropic-version: 2023-06-01' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "model": "claude-3-5-haiku-20241022",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "What'\''s the weather in NYC?"
    }
  ],
  "tools": [{
    "type": "web_search_20250305",
    "name": "web_search",
    "max_uses": 5
  }]
}'

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

​
Parameters

ParameterTypeRequiredDefaultDescription
modelstring✅ Yesclaude-3-5-haiku-20241022The model to use for the request
messagesarray✅ Yes[{'role': 'user', 'content': "What's the weather in NYC?"}]Array of message objects for the conversation. Each message must have a role (user or assistant) and content.
max_tokensinteger✅ Yes1024The maximum number of tokens to generate before stopping
toolsarray✅ Yes-Array of tool objects. For web search, must include the web_search tool configuration.
temperaturenumber❌ No1.0Amount of randomness injected into the response. Ranges from 0.0 to 1.0
top_pnumber❌ No1.0Use nucleus sampling. Ranges from 0.0 to 1.0
top_kinteger❌ NonullOnly sample from the top K options for each subsequent token
streamboolean❌ NofalseWhether to incrementally stream the response using server-sent events
stop_sequencesarray❌ No-Custom text sequences that will cause the model to stop generating

​
Messages Array Structure

Each message object in the messages array should have the following structure:
FieldTypeRequiredDescription
rolestring✅ YesThe role of the message. Can be: user, assistant, or system
contentarray/string✅ YesThe content of the message

​
Content Array Structure (when content is an array)

FieldTypeRequiredExampleDescription
typestring✅ YestextThe type of content
textstring✅ Yes"What's the weather in NYC?"The text content when type is text

​
Tools Array Structure

For web search functionality, the tools array should contain a web search tool object:
FieldTypeRequiredExampleDescription
typestring✅ Yesweb_search_20250305The type of tool. Must be web_search_20250305 for web search
namestring✅ Yesweb_searchThe name of the tool
max_usesinteger❌ No5Maximum number of times the web search tool can be used in a single request
allowed_domainsarray❌ No["example.com", "trusteddomain.org"]Only include search results from these domains
blocked_domainsarray❌ No["untrustedsource.com"]Never include search results from these domains
user_locationobject❌ No-Localize search results based on user’s location

​
Max Uses

The max_uses parameter limits the number of searches performed. If Claude attempts more searches than allowed, the web_search_tool_result will be an error with the max_uses_exceeded error code.

​
Domain Filtering

When using domain filters:
  • Domains should not include the HTTP/HTTPS scheme (use example.com instead of https://example.com)
  • Subdomains are automatically included (example.com covers docs.example.com)
  • Specific subdomains restrict results to only that subdomain (docs.example.com returns only results from that subdomain, not from example.com or api.example.com)
  • Subpaths are supported (example.com/blog)
  • You can use either allowed_domains or blocked_domains, but not both in the same request
  • Request-level domain restrictions must be compatible with organization-level domain restrictions configured in the Console

​
User Location Structure

The user_location object allows you to localize search results based on a user’s location:
FieldTypeRequiredExampleDescription
typestring✅ YesapproximateThe type of location (must be approximate)
citystring✅ YesSan FranciscoThe city name
regionstring✅ YesCaliforniaThe region or state
countrystring✅ YesUSThe country code
timezonestring✅ YesAmerica/Los_AngelesThe IANA timezone ID

​
Complete Tool Configuration Example

{
  "type": "web_search_20250305",
  "name": "web_search",
  "max_uses": 5,
  "allowed_domains": ["example.com", "trusteddomain.org"],
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}