<Intro>

<EndpointHeader />

<Description>

Search the Bird documentation and return the most relevant sections for a query. Each result links to the matching section heading.

</Description>

</Intro>

<Parameters in="query">

<Parameter name="q" type="string">

<Description>

The text to search for.

</Description>

</Parameter>

<Parameter name="locale" type="string">

<Description>

Documentation locale to search, as a language-region code such as en-us. Defaults to en-us when omitted or unavailable.

</Description>

</Parameter>

<Parameter name="limit" type="integer">

<Description>

Maximum number of results to return (1–25).

</Description>

</Parameter>

<Parameter name="contents" type="string">

<Description>

How much of each matching section to return. snippet (default) returns a short preview; highlights returns the passages that match the query. For the full text, fetch a result's markdown_url.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="query" type="string" required>

<Description>

The search query that produced these results.

</Description>

</Field>

<Field name="locale" type="string" required>

<Description>

The documentation locale the results were drawn from.

</Description>

</Field>

<Field name="results" type="array of object" required>

<Description>

Matching documentation sections, ordered by descending relevance.

</Description>

<FieldChildren kind="response">

<Field name="title" type="string" prefix="results." required>

<Description>

Title of the documentation page this result belongs to.

</Description>

</Field>

<Field name="section" type="string" prefix="results." required>

<Description>

Heading of the matching section within the page.

</Description>

</Field>

<Field name="url" type="string" prefix="results." required>

<Description>

Relative path to the matching section, including the heading anchor.

</Description>

</Field>

<Field name="doc_url" type="string" prefix="results." required>

<Description>

Relative path to the page, without the section anchor. Results from the same page share it, so it can be used to group them.

</Description>

</Field>

<Field name="markdown_url" type="string" prefix="results." required>

<Description>

Absolute URL that returns the page's full content as Markdown. Fetch it to read the whole page.

</Description>

</Field>

<Field name="snippet" type="string" prefix="results.">

<Description>

Short excerpt of the matching content, with the query terms in context. Always returned.

</Description>

</Field>

<Field name="highlights" type="array of string" prefix="results.">

<Description>

The passages of the section that match the query, longer than the snippet. Returned only when contents is highlights.

</Description>

</Field>

<Field name="token_estimate" type="integer" prefix="results." required>

<Description>

Approximate token count of the full page returned by markdown_url, to budget reading it. Results from the same page share it.

</Description>

</Field>

<Field name="score" type="number" prefix="results." required>

<Description>

Relevance score. Higher is more relevant; results are ordered by descending score.

</Description>

</Field>

</FieldChildren>

</Field>

</Payload>