Skip to main content
POST
/
v1
/
chat
/
completions
claude-sonnet-4-20250514 (web search)
curl --request POST \
  --url https://api.example.com/v1/chat/completions
curl -X POST "https://gptproto.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "claude-sonnet-4-20250514",
  "messages": [
    {
      "role": "user",
      "content": "What'\''s the weather in NYC?"
    }
  ],
  "tools": [
    {
      "type": "web_search_20250305",
      "name": "web_search",
      "max_uses": 5
    }
  ],
  "stream": false
}'

{
  "error": {
    "message": "Invalid signature",
    "type": "401"
  }
}

​
Parameters

ParameterTypeRequiredDefaultRangeDescription
modelstring✅ Yesclaude-sonnet-4-20250514-The model to use for the request
messagesarray✅ Yes--Array of message objects for the conversation. Each message must have a role (user/assistant) and content (string or array of content blocks)
toolsarray✅ Yes--Array of tool objects. For web search, must include the web_search tool configuration with type web_search_20250305
max_tokensinteger❌ No-1-32000Maximum number of tokens to generate in the response
temperaturenumber❌ No1.00.0-2.0Controls randomness in output. Use lower values (closer to 0.0) for analytical tasks, higher values (closer to 2.0) for creative tasks
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
stoparray❌ No-Max 8191 sequencesCustom text sequences that will cause the model to stop generating. Each sequence must contain non-whitespace characters
presence_penaltynumber❌ No0-2.0 to 2.0Positive values penalize new tokens based on whether they appear in the text so far
frequency_penaltynumber❌ No0-2.0 to 2.0Positive values penalize new tokens based on their existing frequency in the text so far

​
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. 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 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

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