This guide shows you how to migrate from the deprecated web search API endpoint to the web search tool in chat completions. After completing these steps, you can search the web using the web search tool, which provides the same capabilities within a chat completion workflow.
Compare the APIs
The web search API and the web search tool provide similar search results, but the tool integrates web search into conversational workflows and requires specifying queries and configuration differently. The table below compares the two APIs.
| Aspect | Web search API | Web search tool |
|---|
| Endpoint | /v1/tools/web-search | /v1/chat with the prebuilt web search tool specification |
| Request structure | Pass search parameters such as query, search_depth, etc. directly in the request body | Provide the search query as part of the conversation messages and add the web search tool in the tools array. Additional parameters (like domains to include or exclude) are specified in the tool configuration, not as direct request fields. |
| Response format | Results in answer and sources fields | Answer in choices[0].message.content and data in web_search_data field |
| Parameter control | Explicit API parameters | Most parameters specified in message prompt; only include_domains and exclude_domains as tool configuration |
Migrate your code
The tabs below show a request using the web search API and the same request using the web search tool.
Before: Web search API
After: Web search tool
The web search API accepts search parameters directly in the request body. The following example shows an example request using the web search API. View the same request using the web search tool in the after migrating section.curl --location 'https://api.writer.com/v1/tools/web-search' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $WRITER_API_KEY" \
--data '{
"query": "What are the most significant developments in artificial intelligence this year?",
"include_domains": ["wikipedia.org", "github.com"],
"exclude_domains": ["quora.com"],
"search_depth": "advanced",
"max_results": 10
}'
{
"query": "What are the most significant developments in artificial intelligence this year?",
"answer": "This year has seen several significant developments...",
"sources": [
{
"url": "https://www.ibm.com/think/insights/artificial-intelligence-trends",
"raw_content": null
}
]
}
The web search tool uses the chat completions endpoint with a web search tool specification. The model handles the search based on your message and tool configuration. Parameters like search_depth and max_results are now specified in the message prompt:curl --location 'https://api.writer.com/v1/chat' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $WRITER_API_KEY" \
--data '{
"model": "palmyra-x5",
"messages": [
{
"role": "user",
"content": "What are the most significant developments in artificial intelligence this year? Use advanced search depth and limit to 10 results."
}
],
"tool_choice": "auto",
"tools": [
{
"type": "web_search",
"function": {
"include_domains": ["wikipedia.org", "github.com"],
"exclude_domains": ["quora.com"]
}
}
]
}'
{
"id": "2ac04514",
"object": "chat.completion",
"choices": [
{
"index": 0,
"finish_reason": "tool_calls",
"message": {
"content": "The latest developments in AI technology are happening at a rapid pace...",
"role": "assistant",
"web_search_data": {
"search_depth": "advanced",
"sources": [
{
"url": "https://en.wikipedia.org/wiki/AI_boom",
"raw_content": null
}
]
}
}
}
]
}
Map your parameters
The following table shows how web search API parameters map to the web search tool. To customize search behavior in the web search tool, include your requirements in the message prompt.
| Web search API | Web search tool |
|---|
query | Include in the message content field |
include_domains | tools[0].function.include_domains |
exclude_domains | tools[0].function.exclude_domains |
search_depth | Include in the message prompt (for example, “perform an advanced search”) |
max_results | Include in the message prompt (for example, “limit to 10 sources”) |
time_range | Include in the message prompt (for example, “from the last week”) |
include_raw_content | Include in the message prompt (for example, “include raw source text”) |
topic | Include in the message prompt (for example, “search news articles”) |
country | Include in the message prompt (for example, “localize results to the United States”) |
chunks_per_source | Include in the message prompt (for example, “extract 3 text segments per source”) |
With the web search tool, most search parameters are specified in your message prompt rather than as separate API parameters. The model interprets your requirements and configures the search accordingly.Only include_domains and exclude_domains are available as tool configuration parameters.
web_search_data field:
from writerai import Writer
# Initialize the Writer client. If you don't pass the `api_key` parameter,
# the client looks for the `WRITER_API_KEY` environment variable.
client = Writer()
messages = [{"role": "user", "content": "What are the most significant developments in artificial intelligence this year? Use advanced search depth and limit to 10 results."}]
tools = [{
"type": "web_search",
"function": {
"include_domains": ["wikipedia.org", "github.com"],
"exclude_domains": ["quora.com"]
}
}]
response = client.chat.chat(
model="palmyra-x5",
messages=messages,
tools=tools,
tool_choice="auto"
)
# Get the search answer
answer = response.choices[0].message.content
# Get search metadata
search_metadata = response.choices[0].message.web_search_data
search_depth = search_metadata.search_depth
sources = search_metadata.sources
print(f"Answer: {answer}")
print(f"Search depth: {search_depth}")
print(f"Found {len(sources)} sources")
for source in sources:
print(f"- {source.url}")
