Skip to main content
POST
/
v1
/
messages
claude-opus-4-1-20250805 (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-opus-4-1-20250805",
  "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-opus-4-1-20250805-The model identifier. Use claude-opus-4-1-20250805 for this model
messagesarray✅ Yes--Input messages for the conversation. Each message must have a role (user/assistant) and content (string or array of content blocks)
max_tokensinteger✅ Yes-1-32000Maximum number of tokens to generate. The model may stop before reaching this limit
toolsarray✅ Yes--Array of tool objects. For web search, must include the web_search tool configuration with type web_search_20250305
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❌ No-0.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❌ No->0Only sample from the top K options for each token. Removes low probability responses. Recommended for advanced use only
streamboolean❌ Nofalse-Whether to stream the response incrementally 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
contentstring/array✅ Yes-The content of the message. Can be a simple string for text-only messages, or an array of content blocks for multimodal content

​
Content Block Structure (when content is an array)

FieldTypeRequiredRangeDescription
typestring✅ Yes-Must be text
textstring✅ Yes-The text content

​
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. Use web_search
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. Cannot be used with blocked_domains
blocked_domainsarray❌ No-Never include search results from these domains. Cannot be used with allowed_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 (e.g., San Francisco)
regionstring✅ Yes-The region or state (e.g., California)
countrystring✅ Yes-The country code (e.g., US)
timezonestring✅ Yes-The IANA timezone ID (e.g., America/Los_Angeles)

​
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"
  }
}