> ## Documentation Index
> Fetch the complete documentation index at: https://dev.writer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Web search
> Search the web for information about a given query and return relevant results with source URLs.
**Deprecation notice**: The [web search API endpoint](/api-reference/tool-api/web-search) at `/v1/tools/web-search` is deprecated and will be removed on **December 22, 2025**.
**Migration path**: Use the [web search tool](/home/web-search-tool) in chat completions to perform web searches during conversations. The web search tool provides the same search capabilities within a chat completion workflow. See the [migration guide](/api-reference/migration-guides/web-search) for detailed instructions.
## OpenAPI
````yaml post /v1/tools/web-search
openapi: 3.0.3
info:
title: API
version: '1.0'
servers:
- url: https://api.writer.com
security:
- bearerAuth: []
paths:
/v1/tools/web-search:
post:
tags:
- Tools API
summary: Web search
description: >-
Search the web for information about a given query and return relevant
results with source URLs.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/web_search_request'
example:
query: How do I get an API key for the Writer API?
include_domains:
- dev.writer.com
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/web_search_response'
example:
query: How do I get an API key for the Writer API?
answer: >-
To get an API key for the Writer API, you need to create one
in the AI Studio. Here's how to do it:
1. Go to the AI Studio home page.
2. Click on "API Keys" in the navigation menu.
Once you've created your API key, you can use it to make API
calls. It's recommended to set the API key as an environment
variable named `WRITER_API_KEY` for easier access.
For example, you can store it in a `.env` file and then
initialize the Writer client, which will automatically look
for the `WRITER_API_KEY` environment variable.
sources:
- url: https://dev.writer.com/home/sdks
raw_content: null
- url: >-
https://dev.writer.com/api-guides/api-reference/application-api/applications
raw_content: null
- url: https://dev.writer.com/api-reference/api-keys
raw_content: null
- url: https://dev.writer.com/home/quickstart
raw_content: null
- url: https://dev.writer.com/framework/chat-assistant
raw_content: null
security:
- bearerAuth: []
x-codeSamples:
- lang: cURL
source: >-
curl --location --request POST
https://api.writer.com/v1/tools/web-search \
--header "Authorization: Bearer " \
--header "Content-Type: application/json" \
--data-raw '{"query":"How do I get an API key for the Writer
API?","include_domains":["dev.writer.com"]}'
components:
schemas:
web_search_request:
type: object
properties:
query:
type: string
description: The search query.
topic:
type: string
enum:
- general
- news
default: general
description: >-
The search topic category. Use `news` for current events and news
articles, or `general` for broader web search.
search_depth:
type: string
enum:
- basic
- advanced
default: basic
description: |-
Controls search comprehensiveness:
- `basic`: Returns fewer but highly relevant results
- `advanced`: Performs a deeper search with more results
chunks_per_source:
type: integer
format: int32
description: >-
Only applies when `search_depth` is `advanced`. Specifies how many
text segments to extract from each source. Limited to 3 chunks
maximum.
max_results:
type: integer
format: int32
description: >-
Limits the number of search results returned. Cannot exceed 20
sources.
time_range:
type: string
enum:
- day
- week
- month
- year
- d
- w
- m
- 'y'
description: >-
Filters results to content published within the specified time range
back from the current date. For example, `week` or `w` returns
results from the past 7 days.
days:
type: integer
format: int32
description: >-
For news topic searches, specifies how many days of news coverage to
include.
include_raw_content:
oneOf:
- type: string
enum:
- text
- markdown
- type: boolean
default: false
description: >-
Controls how raw content is included in search results:
- `text`: Returns plain text without formatting markup
- `markdown`: Returns structured content with markdown formatting
(headers, links, bold text)
- `true`: Same as `markdown`
- `false`: Raw content is not included (default if unset)
include_answer:
type: boolean
default: true
description: >-
Whether to include a generated answer to the query in the response.
If `false`, only search results are returned.
include_domains:
type: array
items:
type: string
description: >-
Domains to include in the search. If unset, the search includes all
domains.
exclude_domains:
type: array
items:
type: string
description: >-
Domains to exclude from the search. If unset, the search includes
all domains.
country:
type: string
enum:
- afghanistan
- albania
- algeria
- andorra
- angola
- argentina
- armenia
- australia
- austria
- azerbaijan
- bahamas
- bahrain
- bangladesh
- barbados
- belarus
- belgium
- belize
- benin
- bhutan
- bolivia
- bosnia and herzegovina
- botswana
- brazil
- brunei
- bulgaria
- burkina faso
- burundi
- cambodia
- cameroon
- canada
- cape verde
- central african republic
- chad
- chile
- china
- colombia
- comoros
- congo
- costa rica
- croatia
- cuba
- cyprus
- czech republic
- denmark
- djibouti
- dominican republic
- ecuador
- egypt
- el salvador
- equatorial guinea
- eritrea
- estonia
- ethiopia
- fiji
- finland
- france
- gabon
- gambia
- georgia
- germany
- ghana
- greece
- guatemala
- guinea
- haiti
- honduras
- hungary
- iceland
- india
- indonesia
- iran
- iraq
- ireland
- israel
- italy
- jamaica
- japan
- jordan
- kazakhstan
- kenya
- kuwait
- kyrgyzstan
- latvia
- lebanon
- lesotho
- liberia
- libya
- liechtenstein
- lithuania
- luxembourg
- madagascar
- malawi
- malaysia
- maldives
- mali
- malta
- mauritania
- mauritius
- mexico
- moldova
- monaco
- mongolia
- montenegro
- morocco
- mozambique
- myanmar
- namibia
- nepal
- netherlands
- new zealand
- nicaragua
- niger
- nigeria
- north korea
- north macedonia
- norway
- oman
- pakistan
- panama
- papua new guinea
- paraguay
- peru
- philippines
- poland
- portugal
- qatar
- romania
- russia
- rwanda
- saudi arabia
- senegal
- serbia
- singapore
- slovakia
- slovenia
- somalia
- south africa
- south korea
- south sudan
- spain
- sri lanka
- sudan
- sweden
- switzerland
- syria
- taiwan
- tajikistan
- tanzania
- thailand
- togo
- trinidad and tobago
- tunisia
- turkey
- turkmenistan
- uganda
- ukraine
- united arab emirates
- united kingdom
- united states
- uruguay
- uzbekistan
- venezuela
- vietnam
- yemen
- zambia
- zimbabwe
description: >-
Localizes search results to a specific country. Only applies to
general topic searches.
stream:
type: boolean
default: false
description: Enables streaming of search results as they become available.
web_search_response:
title: web_search_response
required:
- query
- sources
type: object
properties:
query:
type: string
description: The search query that was submitted.
answer:
type: string
description: >-
Generated answer based on the search results. Not included if
`include_answer` is `false`.
sources:
type: array
description: The search results found.
items:
type: object
properties:
url:
type: string
description: URL of the search result.
raw_content:
type: string
description: >-
Raw content from the source URL. Not included if
`include_raw_content` is `false`.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Bearer authentication header of the form `Bearer `, where
`` is your [Writer API
key](https://dev.writer.com/api-reference/api-keys).
````