Documentation search #

View this page as Markdown

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:

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.

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:

{
  "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 #

Related #

• How an AI reads these docs explains read_documentation, which reads the pages and sections a search finds.
• The generated reference for search_documentation gives each member and its limits.
• Refusals lists every refusal by name.