---
title: "Search the web"
method: POST
path: "/web/search"
tags: ["Web Search"]
---

# Search the web

`POST /web/search`

## Request

- Base URL: `https://api.textcortex.com/v1`
- URL: `https://api.textcortex.com/v1/web/search`
- Auth: HTTP bearer

Search the web and return titles, URLs and snippets.
This request does not generate an AI answer, fetch full pages, or select a chat model.
Check `GET /capabilities` for access and current pricing.

### Search, then answer

1. Send `{"query":"What changed in Python 3.13?","website":"docs.python.org","limit":3}`.
2. Read `data[].title`, `url` and `snippet`. Results can be fewer than `limit`,
   including an empty array. Snippets are excerpts, not complete page contents.
3. To generate an answer, make a separate `POST /chat/completions` request.
   Include the snippets and their URLs alongside the user's question in `messages`.
   Ask the model to cite those URLs and treat retrieved text as reference material,
   not instructions. That chat request has its own model selection and billing.

### Query length and site filtering

The API accepts 1–1000 characters in `query`. The current search provider uses
at most 500 characters **including the added site filter**;
longer combined searches are shortened, usually at a word boundary. If the site
filter alone exceeds that limit, its URL/path can be cut mid-token and change
the restriction. Keep both the query and site filter short enough to fit together.
The response echoes your normalized query, not the shortened provider query.

Set `website` to a domain such as `docs.python.org`, or an HTTP(S) URL with a path
such as `https://docs.python.org/3/`. This adds a `site:` search restriction;
it does not crawl that website. URL query strings and fragments are removed.
Omit `website` to search across the web.

### Billing and results

Each successful search costs 0.01 eur
as a final retail price, including a search with no results. No contract markup or
overage multiplier is added. `GET /capabilities` identifies the funding source.
When PAYG wallet billing applies, searches use that wallet unless the caller is
explicitly enrolled to spend existing API credits and those credits cover the
full search fee. Enrolled credit-funded searches are charged after provider success.
If the legacy remainder cannot cover the fee, the search uses the PAYG wallet;
the remainder stays available for model requests.
Wallet charges are converted once to the wallet currency, with `usage.billing`
set to `organization_payg_wallet`. Credit charges use eur and
`usage.billing` is `api_credits`. Ordinary API-credit callers reserve the fee before
provider work, including when PAYG wallet billing is disabled or PAYG entitlement ends.

Wallet capacity is checked before provider work and again at settlement. If capacity
is lost before settlement, the request returns 402 without a charge or search results.
Unavailable wallet funding returns 503. Neither case falls back to API credits.
Failed provider calls do not charge; any reserved API credits are released.
Insufficient API credits also returns 402. These errors use the `detail` response field.

Each HTTP request performs a new search. Retrying after a lost response can incur
another charge: this endpoint does not support request-level idempotency keys.
Duplicate settlement of the same server-side search charge is prevented.

`meta.filtered_result_count` counts parsed results removed by filtering; it does
not count every unavailable search result. `usage` reports this search's charge.

## Request body

- ApiPlatformWebSearchRequest
  - `limit` integer: Maximum results to return (1–10, default 5), not a guarantee of result count.
  - `query` string, required: Search text, 1–1000 characters. The provider shortens the combined query and site filter to 500 characters.
  - `website` union: Optional domain or HTTP(S) URL/path used as a site search filter.
    - string
    - unknown

## Response `200`

Successful search. usage.cost is the final charge in usage.currency; usage.billing identifies API credits or the PAYG wallet.

- WebSearchResponse
  - `data` WebSearchResult[], required
    - `object` 'web_search_result'
    - `published_at` string, date-time, nullable
    - `score` number, nullable
    - `snippet` string, nullable
    - `title` string, nullable
    - `url` string, nullable
  - `limit` integer, required
  - `meta` object, required
    - `filtered_result_count` integer
  - `object` 'web_search', required
  - `query` string, required
  - `usage` object, required
    - `billing` 'api_credits' | 'organization_payg_wallet', required
    - `cost` number, required
    - `currency` string, required
  - `website` string, nullable, required

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `402`: Insufficient funding
- `403`: Access denied
- `404`: Resource not found
- `422`: Request validation failed
- `500`: Server error
- `502`: Upstream provider failed
- `503`: Wallet funding temporarily unavailable

## Changes

- **2026-10-13** `43d212dab9fa`: 1 warning, 1 info
  - added the new `organization_payg_wallet` enum value to the `usage/billing` response property for the response status `200`
  - added the non-success response with the status `503`
- **2026-10-08** `254204fd17bd`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/textcortex/apis/textcortex-api/changes/web/search/post.md)

---

[API](https://skmtc.dev/textcortex/apis/textcortex-api.md) - [All operations](https://skmtc.dev/textcortex/apis/textcortex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/textcortex/apis/textcortex-api/revisions/b27459bd3c96?raw)