Skip to main content
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.
AspectWeb search APIWeb search tool
Endpoint/v1/tools/web-search/v1/chat with the prebuilt web search tool specification
Request structurePass search parameters such as query, search_depth, etc. directly in the request bodyProvide 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 formatResults in answer and sources fieldsAnswer in choices[0].message.content and data in web_search_data field
Parameter controlExplicit API parametersMost 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
  }'
Response:
{
  "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
    }
  ]
}

​
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 APIWeb search tool
queryInclude in the message content field
include_domainstools[0].function.include_domains
exclude_domainstools[0].function.exclude_domains
search_depthInclude in the message prompt (for example, “perform an advanced search”)
max_resultsInclude in the message prompt (for example, “limit to 10 sources”)
time_rangeInclude in the message prompt (for example, “from the last week”)
include_raw_contentInclude in the message prompt (for example, “include raw source text”)
topicInclude in the message prompt (for example, “search news articles”)
countryInclude in the message prompt (for example, “localize results to the United States”)
chunks_per_sourceInclude 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.

​
Access search metadata

The web search tool response includes search metadata, including sources and raw text if requested, in the 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}")
Learn more about the web search tool and related features: