Skip to main content
POST
/
v1
/
messages
claude-sonnet-4-5-20250929 (web search)
curl --request POST \
  --url https://api.example.com/v1/messages
curl --location --request POST 'https://gptproto.com/v1/messages' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'anthropic-version: 2023-06-01' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "model": "claude-sonnet-4-5-20250929",
  "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

ParameterTypeRequiredDefaultRangeDescription
modelstring✅ Yesclaude-sonnet-4-5-20250929-The 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/assistant) and content. See Messages Structure below for details
max_tokensinteger✅ Yes10241-64000The 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.00.0-1.0Controls randomness in output. Use lower values (closer to 0.0) for analytical tasks, higher values (closer to 1.0) for creative tasks. Note: Even at 0.0, results are not fully deterministic
top_pnumber❌ No1.00.0-1.0Nucleus sampling threshold. Controls diversity by considering only tokens with cumulative probability up to top_p. Recommended for advanced use only. Do not use with temperature
top_kinteger❌ Nonull>0Only sample from the top K options for each token. Removes low probability responses. Recommended for advanced use only
streamboolean❌ Nofalse-Whether to incrementally stream the response using server-sent events
stop_sequencesarray❌ No-Max 8191 sequencesCustom text sequences that will cause the model to stop generating. Each sequence must contain non-whitespace characters

​
Messages Array Structure

Each message object in the messages array should have the following structure:
FieldTypeRequiredRangeDescription
rolestring✅ Yes-The role of the message. Can be: user or assistant
contentarray/string✅ Yes-The content of the message

​
Content Array Structure (when content is an array)

FieldTypeRequiredRangeDescription
typestring✅ Yes-The type of content
textstring✅ Yes-The text content when type is text

​
Tools Array Structure

For web search functionality, the tools array should contain a web search tool object:
FieldTypeRequiredRangeDescription
typestring✅ Yes-The type of tool. Must be web_search_20250305 for web search
namestring✅ Yes-The name of the tool
max_usesinteger❌ No1-10Maximum number of times the web search tool can be used in a single request
allowed_domainsarray❌ No-Only include search results from these domains
blocked_domainsarray❌ No-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:
FieldTypeRequiredRangeDescription
typestring✅ Yes-The type of location (must be approximate)
citystring✅ Yes-The city name
regionstring✅ Yes-The region or state
countrystring✅ Yes-The country code
timezonestring✅ Yes-The 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"
  }
}