The Web Search API allows you to search the web for information and get real-time results. This tool is useful for finding current information, news, and facts that may not be available in your model’s training data or in your Knowledge Graphs.
You need an API key to access the Writer API. Get an API key by following the steps in the API quickstart.We recommend setting the API key as an environment variable in a .env file with the name WRITER_API_KEY.

​
Overview

The web search tool enables you to:
  • Search for current information and news
  • Find factual information from reliable sources
  • Get real-time data that may not be in your model’s training data
  • Filter results by domain, time range, and geographic location
  • Control search depth and result comprehensiveness

​
Request example

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?",
        "topic": "general", 
        "search_depth": "basic",
        "include_answer": true
    }'

​
Request parameters

ParameterTypeRequiredDescription
querystringYesThe search query to execute
topicstringNoThe search topic category. Use news for current events and news articles, or general for broader web search. Default: general
search_depthstringNoControls search comprehensiveness. Use basic for fewer but highly relevant results, or advanced for deeper search with more results. Default: basic
chunks_per_sourceintegerNoOnly applies when search_depth is advanced. Specifies how many text segments to extract from each source. Limited to 3 chunks maximum
max_resultsintegerNoLimits the number of search results returned. Cannot exceed 20 sources
time_rangestringNoFilters results to content published within the specified time range. Options: day, week, month, year, d, w, m, y
daysintegerNoFor news topic searches, specifies how many days of news coverage to include
include_raw_contentstring | BooleanNoControls how raw content is included. Options: text, markdown, true (same as markdown), false (not included). Default: false
include_answerBooleanNoWhether to include a generated answer to the query in the response. Default: true
include_domainsarrayNoDomains to include in the search
exclude_domainsarrayNoDomains to exclude from the search
countrystringNoLocalizes search results to a specific country. Only applies to general topic searches
streamBooleanNoEnables streaming of search results as they become available. Default: false

​
Response format

The response contains the search query, generated answer if requested, and an array of sources with their URLs and raw content if requested.
ParameterTypeDescription
querystringThe search query that was submitted
answerstringGenerated answer based on the search results. null if include_answer is false
sourcesarrayThe search results found
sources[].urlstringURL of the search result
sources[].raw_contentstringRaw content from the source URL. null if include_raw_content is false
{
  "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
    },
    {
      "url": "https://www.crescendo.ai/news/latest-ai-news-and-updates",
      "raw_content": null
    },
    {
      "url": "https://www.sciencedaily.com/news/computers_math/artificial_intelligence/",
      "raw_content": null
    },
    {
      "url": "https://news.microsoft.com/source/features/ai/6-ai-trends-youll-see-more-of-in-2025/",
      "raw_content": null
    },
    {
      "url": "https://hai.stanford.edu/ai-index/2025-ai-index-report",
      "raw_content": null
    }
  ]
}

​
Streaming response

When streaming is enabled, the response is delivered as Server-Sent Events (SSE). Each event contains a payload with the query, answer, and sources array. The response is delivered as a stream of events, and the client must listen for each event to receive the complete response. Learn more about streaming responses. Below is an example of a streaming response: 
data: {"query":"What are the most significant developments in artificial intelligence this year?","answer":"","sources":[]}

data: {"query":"What are the most significant developments in artificial intelligence this year?","answer":"Several","sources":[]}

data: {"query":"What are the most significant developments in artificial intelligence this year?","answer":" significant","sources":[]}

​
Usage examples

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?",
        "topic": "general", 
        "search_depth": "basic",
        "include_answer": true
    }'

​
News search with time filtering

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 latest developments in smartphone technology?",
        "topic": "news",
        "time_range": "week", 
        "include_raw_content": "markdown",
        "max_results": 10
    }'

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 some good tutorials for learning machine learning?",
        "include_domains": ["github.com", "stackoverflow.com"],
        "exclude_domains": ["quora.com"],
        "search_depth": "advanced",
        "chunks_per_source": 2
    }'

​
Best practices

  • Use specific queries: More specific queries tend to yield better results
  • Choose appropriate topic: Use news for current events and general for broader searches
  • Filter by domains: Use include_domains and exclude_domains to focus on reliable sources
  • Control search depth: Use basic for quick searches and advanced for comprehensive research
  • Set time ranges: Use time_range to get current information when needed
  • Limit results: Use max_results to control response size and processing time

​
Next steps

Learn about other tools available in the Writer API: