Documents

Reference article: Part of the API reference. For the wiki in the app, see What is the Company Wiki.

Search your organization's knowledge from your own tools. The search endpoint looks through the Company Wiki and connected documents by meaning, not only by exact words, and returns the passages that best match your query. Use it to add Nimbus knowledge to an internal search box, a support tool, or your own retrieval pipeline.

Search documents

POST /v1/documents/search

Scope: documents:read

Body field	Type	Description
`query`	string	What to look for, in plain language, 1–2,000 characters.
`limit`	integer, optional	How many passages to return, 1–20. Default `8`.
`mode`	string, optional	`hybrid` (default) matches by meaning and also by exact words. `semantic` matches by meaning only.
`workspace`	string, optional	The workspace to search. Default `default`.

::: code-group

curl https://api.gonimbus.ai/v1/documents/search \
  -H "Authorization: Bearer $NIMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What notice do we give customers before a price increase?", "limit": 5}'

const response = await fetch('https://api.gonimbus.ai/v1/documents/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NIMBUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query: 'What notice do we give customers before a price increase?', limit: 5 }),
})
const results = await response.json()
for (const chunk of results.data) console.log(chunk.document, chunk.score, chunk.text)

response = requests.post(
    "https://api.gonimbus.ai/v1/documents/search",
    headers={"Authorization": f"Bearer {os.environ['NIMBUS_API_KEY']}"},
    json={"query": "What notice do we give customers before a price increase?", "limit": 5},
)
for chunk in response.json()["data"]:
    print(chunk["document"], chunk["score"], chunk["text"])

:::

{
  "object": "document_search_result",
  "query": "What notice do we give customers before a price increase?",
  "mode": "hybrid",
  "data": [
    {
      "object": "document_chunk",
      "document": "policies/pricing/customer-notice.md",
      "vault": "company",
      "text": "Customers on annual contracts receive at least 60 days' written notice of any price increase…",
      "score": 0.82
    },
    {
      "object": "document_chunk",
      "document": "sales/playbooks/renewals.md",
      "vault": "company",
      "text": "When a renewal includes a price change, confirm the notice date with finance before…",
      "score": 0.67
    }
  ]
}

Field	Type	Description
`object`	string	Always `document_search_result`.
`query`	string	The query you sent.
`mode`	string	The mode the search actually ran in: `hybrid` or `semantic`. It can differ from the mode you asked for.
`data`	array	The matching passages.
`data[].object`	string	Always `document_chunk`.
`data[].document`	string or null	The document's path in the wiki, when known.
`data[].vault`	string	The wiki vault the document is in.
`data[].text`	string	The matching passage.
`data[].score`	number or null	How well the passage matched, when the search provides a score. Compare scores within one response, not across searches.

The response isn't a list object: there are no further pages. To get more passages, raise limit, up to 20.

Choosing a mode

Mode	Best for
`hybrid`	Most searches, especially ones with names, codes, or exact phrases, such as a contract number or product SKU.
`semantic`	Questions phrased differently from the documents' own wording, such as "how long before a price rise do we tell customers?"

Example scenario

A support team adds a "Search Nimbus" button to their help desk. When an agent opens a ticket, the help desk sends the ticket's subject as query and shows the top five passages, each with its document path, beside the ticket. Answers the team has already written in the Company Wiki now surface where support needs them, without anyone copying them over.

FAQ

What gets searched?

The Company Wiki and documents connected to it in the workspace you name. Anything you add to the wiki becomes searchable once it's processed.

Does search write an answer for me?

No. It returns passages as they're written in your documents. To get an answer written from your organization's knowledge, ask the agent instead.

Why did a document I just uploaded not come up?

New documents are searchable once processing finishes. Try again shortly.

Can I download the whole document?

No. The search returns passages and each document's path in the wiki, where people can open it in the app.

Why is score null?

Some matches come back without a score. Treat score as a guide when it's present, and don't rely on it being there.