---
title: Documentation search
description: Search the documentation from a connected AI tool or over HTTP with no sign-in, read the ranked sections it returns, and stay within its limits.
slug: /reference/documentation-search
order: 12
visibility: public
redirects_from: []
---

# Documentation search

`search_documentation` searches the documentation and returns the best matching sections. A connected AI tool calls it as a tool. A web page's search box or a script can call it over HTTP with no sign-in. A search over the same documentation ranks the same way for both. Signed out, it covers only the documentation open to everyone.

## Request

The search takes three members:

| Member | Required | Value |
| --- | --- | --- |
| `query` | Yes | The words to search for, 1 to 200 characters, holding at least one word. |
| `tree` | No | One documentation tree to search, such as `cloud`, `tzdocs`, or `tztrack`. Leave it out to search every tree you can read. |
| `limit` | No | The most sections to return, a whole number from 1 to 20. The default is 8. |

Over HTTP, send a `GET` to `https://turnzero.ai/api/v1/actions/search_documentation` with the members as query parameters. Send each one once. A `POST` with the members as a JSON body works too.

```sh
curl -s 'https://turnzero.ai/api/v1/actions/search_documentation?query=custom+domain&limit=3'
```

## Response

A search answers `200` with a JSON object. Its `hits` list holds the matching sections, best first:

```json
{
  "contract_version": 1,
  "query": "custom domain",
  "trees": ["cloud", "tzdocs", "tztrack"],
  "hits": [
    {
      "tree": "cloud",
      "title": "Attach your own domain",
      "route": "/cloud/guides/attach-your-own-domain/",
      "heading": "2. Declare the domain in the manifest",
      "anchor": "2-declare-the-domain-in-the-manifest",
      "excerpt": "{ \"kind\": \"custom_domain\", \"domain\": \"app.example.com\" }",
      "score": 25.7348
    }
  ],
  "text": "…"
}
```

Each hit gives:

- `tree`: the documentation tree, such as `cloud`.
- `title`: the page's title.
- `route`: the page's address on this site.
- `heading`: the section's heading, or `null` for the text before the page's first heading.
- `anchor`: the heading's anchor, or `null`. Link to `route` followed by `#` and the anchor to open the section.
- `excerpt`: the section's line that holds the most search words, at most 200 characters.
- `score`: how well the section matches. Compare scores within one answer only.

`text` holds the same hits as Markdown lines, one per hit, for an AI tool to read. Each line is the page title and the section heading as a link to the section, then the excerpt. `trees` lists the trees searched. An answer with no match has an empty `hits` list and an empty `text`, except that a search for one rule code still gets the line saying what a rule code is.

To read a hit, call `read_documentation` with its `route` as `page` and its `anchor` as `section`.

## Signed in or signed out

Signed in, through your AI tool's connection or with a token, the search covers every documentation tree your account can read.

Signed out, a request that sends no token (no `Authorization` header, an empty one, or a scheme other than `Bearer`), the search covers only the documentation anyone can read without signing in. A tree that needs an invitation never appears, and neither does a product that is not public yet. Browsers and caches may keep a signed-out `GET` answer for 60 seconds. A signed-out search writes no record.

A request that sends a token the platform does not accept is refused `authentication_required`, never answered as a signed-out search.

## How sections are ranked

Each page is split into sections at its headings. A section ranks higher when it holds more of the search words and when the words are rare across the documentation. It also ranks higher when the words are in the page title or the section heading rather than only in the text.

A section that holds every search word ranks above one that holds only some of them. A common word such as "deploy" counts for little, so the word that names your task decides the order. A short section that holds a word ranks above a long one that holds it as often. A word inside a code sample counts half as much as the same word in the text.

A search phrased as a question, one holding a question mark or starting with a word such as "what" or "how", lifts each page's opening text. A page's opening says what the page is about, so it often answers the question best.

This method is called Okapi BM25, the same one tzTrack's issue search uses.

Letter case does not matter. Common words such as "the", "how", and "is" are dropped. A search word of four or more letters also matches longer words that start with it, so `deploy` matches `deploys` and `deployment`, and a plural matches its singular. At most 12 different words are searched.

Pages of the generated reference rank after the written guides and concepts. At most 3 sections of one page are returned.

## Limits

Each address may make 120 signed-out searches a minute. These are counted apart from page views and from other calls to the management API, so searching never uses up an address's other limits. A signed-in search counts as any other call does.

## Refusals

| Status | `error` | When | What to do |
| --- | --- | --- | --- |
| 400 | `invalid_request` | `query` is missing, empty, longer than 200 characters, holds no word, or is sent twice. Or `tree` names a tree you cannot search, `limit` is not a whole number from 1 to 20, or another member is sent. A signed-out search also takes `q` in place of `query`. | Read `detail`, fix the named member, and search again. |
| 401 | `authentication_required` | The request sent a token the platform does not accept. | Sign in again, or send no token to search signed out. |
| 429 | `rate_capped` | The address made more than 120 signed-out searches in the last minute. | Wait the seconds `Retry-After` gives, then search again. |
| 503 | `context_unavailable` | The server does not hold the documentation yet, as can happen for a few seconds after it starts. | Search again shortly. |

## Related

- [How an AI reads these docs](/cloud/concepts/reading-this-documentation-as-a-tool/) explains `read_documentation`, which reads the pages and sections a search finds.
- The generated reference for [search_documentation](/cloud/reference/actions/search-documentation/) gives each member and its limits.
- [Refusals](/cloud/reference/refusals/) lists every refusal by name.