Claude-Opus-4 - Web Search

POST

messages

claude-opus-4 (web search)

curl --request POST \
  --url https://api.example.com/v1/messages

import requests

url = "https://api.example.com/v1/messages"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.example.com/v1/messages', 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.example.com/v1/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.example.com/v1/messages"

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

	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.example.com/v1/messages")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/messages")

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

request = Net::HTTP::Post.new(url)

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

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-opus-4",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "What'\''s the weather in NYC?"
    }
  ],
  "tools": [{
    "type": "web_search_20250305",
    "name": "web_search",
    "max_uses": 5
  }]
}'

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://gptproto.com"
)

message = client.messages.create(
    model="claude-opus-4",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "What's the weather in NYC?"}
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5
    }]
)

print(message.content)

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://gptproto.com'
});

const message = await client.messages.create({
  model: 'claude-opus-4',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: "What's the weather in NYC?" }
  ],
  tools: [{
    type: 'web_search_20250305',
    name: 'web_search',
    max_uses: 5
  }]
});

console.log(message.content);

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://gptproto.com/v1/messages"

    payload := []byte(`{
  "model": "claude-opus-4",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "What's the weather in NYC?"
    }
  ],
  "tools": [{
    "type": "web_search_20250305",
    "name": "web_search",
    "max_uses": 5
  }]
}`)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
    req.Header.Set("Authorization", "YOUR_API_KEY")
    req.Header.Set("anthropic-version", "2023-06-01")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

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

{
  "error": {
    "type": "invalid_request_error",
    "message": "messages: field required"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "api_error",
    "message": "Internal server error"
  }
}

{
  "error": {
    "type": "overloaded_error",
    "message": "Service is temporarily overloaded"
  }
}

Parameters

Parameter	Type	Required	Default	Description
`model`	string	✅ Yes	`claude-opus-4`	The model to use for the request
`messages`	array	✅ 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_tokens`	integer	✅ Yes	`1024`	The maximum number of tokens to generate before stopping
`tools`	array	✅ Yes	-	Array of tool objects. For web search, must include the web_search tool configuration.
`temperature`	number	❌ No	`1.0`	Amount of randomness injected into the response. Ranges from 0.0 to 1.0
`top_p`	number	❌ No	`1.0`	Use nucleus sampling. Ranges from 0.0 to 1.0
`top_k`	integer	❌ No	`null`	Only sample from the top K options for each subsequent token
`stream`	boolean	❌ No	`false`	Whether to incrementally stream the response using server-sent events
`stop_sequences`	array	❌ 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:

Field	Type	Required	Description
`role`	string	✅ Yes	The role of the message. Can be: `user`, `assistant`, or `system`
`content`	array/string	✅ Yes	The content of the message

Content Array Structure (when content is an array)

Field	Type	Required	Example	Description
`type`	string	✅ Yes	`text`	The type of content
`text`	string	✅ 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:

Field	Type	Required	Example	Description
`type`	string	✅ Yes	`web_search_20250305`	The type of tool. Must be `web_search_20250305` for web search
`name`	string	✅ Yes	`web_search`	The name of the tool
`max_uses`	integer	❌ No	`5`	Maximum number of times the web search tool can be used in a single request
`allowed_domains`	array	❌ No	`["example.com", "trusteddomain.org"]`	Only include search results from these domains
`blocked_domains`	array	❌ No	`["untrustedsource.com"]`	Never include search results from these domains
`user_location`	object	❌ 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:

Field	Type	Required	Example	Description
`type`	string	✅ Yes	`approximate`	The type of location (must be `approximate`)
`city`	string	✅ Yes	`San Francisco`	The city name
`region`	string	✅ Yes	`California`	The region or state
`country`	string	✅ Yes	`US`	The country code
`timezone`	string	✅ Yes	`America/Los_Angeles`	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"
  }
}

Claude-Opus-4 - Text To Text

Claude-Opus-4 - File Analysis - openai

​Parameters

​Messages Array Structure

​Content Array Structure (when content is an array)

​Tools Array Structure

​Max Uses

​Domain Filtering

​User Location Structure

​Complete Tool Configuration Example