> ## 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"]}'
- lang: JavaScript
source: |-
import Writer from 'writer-sdk';
const client = new Writer({
apiKey: process.env['WRITER_API_KEY'], // This is the default and can be omitted
});
const response = await client.tools.webSearch({
include_domains: ['dev.writer.com'],
query: 'How do I get an API key for the Writer API?',
});
console.log(response.query);
- lang: Python
source: |-
import os
from writerai import Writer
client = Writer(
api_key=os.environ.get("WRITER_API_KEY"), # This is the default and can be omitted
)
response = client.tools.web_search(
include_domains=["dev.writer.com"],
query="How do I get an API key for the Writer API?",
)
print(response.query)
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).
````