Docs API Reference SDK Reference Agentic Usage AI Skills

Web Search

Web search

Tavily-compatible `POST /v1/search` returns ranked results without calling a language model. Authenticate with `Authorization: Bearer <BazaarLink key>` or put `api_key` in the JSON body. Use `https://api.bazaarlink.ai/v1` or the fully supported `https://bazaarlink.ai/api/v1` base URL. All frozen OpenAPI fields are validated; unknown fields are ignored. Search depth, date, language, domain, image, answer, and raw-content options follow the contract below. The free allowance requires a verified email and resets daily at 00:00 UTC; accounts without balance and funded accounts have different allowances. The current N/M values come from the database through `getPublicFreeSearchAllowance()`; see the pricing page for the current daily allowance. When the free allowance is exhausted and there is no balance, the response is 432. Customer price equals credits multiplied by the per-credit price configured in the admin. No dollar price is hard-coded here: see the pricing page and read `usage.cost` in each response. Python: `TavilyClient(api_key=..., api_base_url='https://api.bazaarlink.ai/v1')`; JavaScript: `tavily({ apiKey, apiBaseURL })`; LangChain: `TavilySearch(api_base_url=...)`.

POST/v1/search

Authorizations

Authorizationrequired

string · header

API key as bearer token in the Authorization header.

Body

queryrequired

string

The search query to execute.

required; non-empty search query

Example: who is Leo Messi?

search_depth

string

Controls latency, relevance, and result-content generation. Default: `basic`; `basic`, `fast`, and `ultra-fast` cost 1 credit each, while `advanced` costs 2 credits.

default: basic

advancedbasicfastultra-fast

chunks_per_source

integer

Maximum relevant content chunks per source. Default: 3; allowed range: 1–3. Available for `advanced`, `basic`, and `fast`.

default: 3; 1..3

max_results

integer

Maximum number of search results to return. Default: 10; allowed range: 0–20.

default: 10; 0..20

Example: 1

topic

string

Search topic. Default: `general`; use `news` for current news and `finance` for financial content.

default: general

generalnewsfinance

time_range

string

Filters by publication or update date. Default: not set. Allowed values: `day`, `week`, `month`, `year`, `d`, `w`, `m`, `y`.

default: null

dayweekmonthyeardwmy

start_date

string

Returns results published or updated after this date. Format: YYYY-MM-DD.

default: null; format YYYY-MM-DD

Example: 2025-02-09

end_date

string

Returns results published or updated before this date. Format: YYYY-MM-DD.

default: null; format YYYY-MM-DD

Example: 2025-12-29

include_published_date

boolean

Includes the estimated publication or update date in each result. Automatically enabled for the `news` topic. Default: `false`.

default: false

filter_by_published_date

boolean

Removes results outside the `time_range`, `start_date`, or `end_date` window, including results without a detectable date. Default: `false`; `true` also enables `include_published_date`.

default: false

include_answer

boolean | string

Includes an LLM-generated answer. Default: `false`; accepts a boolean or `basic`/`advanced`.

default: false

basicadvanced

include_raw_content

boolean | string

Includes cleaned HTML content for each result. Default: `false`; accepts a boolean or `markdown`/`text`.

default: false

markdowntext

include_images

boolean

Includes query-related images at the top level and source images inside each result. Default: `false`.

default: false

include_image_descriptions

boolean

When `include_images` is `true`, adds a description to each image. Default: `false`.

default: false

include_favicon

boolean

Whether to include a favicon URL for each result. Default: `false`.

default: false

include_domains

string[]

Restricts results to the listed domains; maximum 300 domains. Default: an empty array.

default: []; maximum 300 items

exclude_domains

string[]

Excludes results from the listed domains; maximum 150 domains. Default: an empty array.

default: []; maximum 150 items

include_domains_mode

string

Controls how `include_domains` is applied. `restrict` limits results to those domains; `prefer` prioritizes them but may return others. Requires `include_domains`, otherwise returns 400. Default: not set.

default: null; requires include_domains

restrictprefer

country

string

Boosts results from a selected country. Available only when `topic` is `general`. Default: not set.

default: null; only when topic is general

afghanistanalbaniaalgeriaandorraangolaargentinaarmeniaaustraliaaustriaazerbaijanbahamasbahrainbangladeshbarbadosbelarusbelgiumbelizebeninbhutanboliviabosnia and herzegovinabotswanabrazilbruneibulgariaburkina fasoburundicambodiacamerooncanadacape verdecentral african republicchadchilechinacolombiacomoroscongocosta ricacroatiacubacyprusczech republicdenmarkdjiboutidominican republicecuadoregyptel salvadorequatorial guineaeritreaestoniaethiopiafijifinlandfrancegabongambiageorgiagermanyghanagreeceguatemalaguineahaitihondurashungaryicelandindiaindonesiairaniraqirelandisraelitalyjamaicajapanjordankazakhstankenyakuwaitkyrgyzstanlatvialebanonlesotholiberialibyaliechtensteinlithuanialuxembourgmadagascarmalawimalaysiamaldivesmalimaltamauritaniamauritiusmexicomoldovamonacomongoliamontenegromoroccomozambiquemyanmarnamibianepalnetherlandsnew zealandnicaraguanigernigerianorth koreanorth macedonianorwayomanpakistanpanamapapua new guineaparaguayperuphilippinespolandportugalqatarromaniarussiarwandasaudi arabiasenegalserbiasingaporeslovakiasloveniasomaliasouth africasouth koreasouth sudanspainsri lankasudanswedenswitzerlandsyriataiwantajikistantanzaniathailandtogotrinidad and tobagotunisiaturkeyturkmenistanugandaukraineunited arab emiratesunited kingdomunited statesuruguayuzbekistanvenezuelavietnamyemenzambiazimbabwe

language

string

Boosts results in a selected language. Accepts an ISO 639-1 code or an English language name. Default: not set.

default: null

Example: en

filter_by_language

boolean

Strictly removes results that do not match `language`. Requires `language`, otherwise returns 400. Default: `false`.

default: false; requires language

auto_parameters

boolean

Automatically selects search parameters from query intent. Explicit values win; `include_answer`, `include_raw_content`, and `max_results` must be set manually. Adds 2 credits per request. Default: `false`.

default: false; costs 2 credits

exact_match

boolean

Returns only results containing quoted phrases from the query, bypassing synonyms and semantic variants. Default: `false`.

default: false

include_usage

boolean

Whether to include credit usage in the response. Default: `false`.

default: false

safe_search

boolean

Filters adult or unsafe content. Default: `false`; unsupported for `fast` and `ultra-fast`.

default: false; unsupported for fast and ultra-fast

api_key

string

Optional JSON-body authentication field. When no Bearer header is present, provide the BazaarLink API key here; it is removed before validation and forwarding.

days

integer

SDK compatibility field `days`. Accepted for compatibility; the plan allows it to be passed through or ignored, and it is not part of the frozen OpenAPI schema.

max_hours

integer

SDK compatibility field `max_hours`. Accepted for compatibility; the plan allows it to be passed through or ignored, and it is not part of the frozen OpenAPI schema.

fetch_timeout

number

SDK compatibility field `fetch_timeout`. Accepted for compatibility; the plan allows it to be passed through or ignored, and it is not part of the frozen OpenAPI schema.

cache_fallback

boolean

SDK compatibility field `cache_fallback`. Accepted for compatibility; the plan allows it to be passed through or ignored, and it is not part of the frozen OpenAPI schema.

timeout

number

SDK-compatible `timeout` field. Accepted for compatibility; search uses the service-side timeout, and unknown or unsupported fields are ignored.

POST /v1/search

1
2
3
4
5
6
7
8
9
10
curl https://api.bazaarlink.ai/v1/search \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest news on open-source language models",
    "search_depth": "basic",
    "max_results": 5,
    "topic": "news",
    "time_range": "week"
  }'

Response examples

A successful response contains `query`, optional `answer`, top-level `images`, `results` (each with `title`, `url`, `content`, `score`, and optional `raw_content`, `published_date`, `favicon`, `images`, and `id`), optional `auto_parameters`, `response_time`, `usage` (`credits` plus our additive `cost`), and `request_id`. `usage.cost` is the USD customer price charged for this request, never COGS; `request_id` is generated by BazaarLink for support and is ours, not an upstream ID.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "query": "Who is Leo Messi?",
  "answer": "Lionel Messi is an Argentine footballer.",
  "images": [
    {
      "url": "https://example.com/messi.jpg",
      "description": "Lionel Messi"
    }
  ],
  "results": [
    {
      "title": "Lionel Messi Facts | Britannica",
      "url": "https://www.britannica.com/facts/Lionel-Messi",
      "content": "Lionel Messi is an Argentine footballer.",
      "score": 0.81025416,
      "raw_content": null,
      "published_date": "Tue, 11 Mar 2025 17:00:00 GMT",
      "favicon": "https://britannica.com/favicon.png",
      "images": [
        {
          "url": "https://example.com/messi.jpg",
          "description": "Lionel Messi"
        }
      ],
      "id": "a3f9c2-04"
    }
  ],
  "auto_parameters": {
    "topic": "general",
    "search_depth": "basic"
  },
  "response_time": 1.67,
  "usage": {
    "credits": 1,
    "cost": "<customer_price_usd>"
  },
  "request_id": "123e4567-e89b-12d3-a456-426614174111"
}