Search a collection

Retrieve the passages that best match a query, with scores, to show or to feed into your own model.

POST /v1/{knowledge_id}/search returns the sections (chunks) of the collection's documents that best match a query. No language model writes an answer — use it when you want the passages themselves: to show them, to rank documents, or to give to a model of your own.

Request

Field	Type	Default	Meaning
`query`	string	—	What to search for. Required unless `object_ids` is given.
`num_chunks`	integer	`3`	How many sections to return, 1–100.
`object_ids`	string[]	all documents	Only search these documents. An empty list returns no results.
`mode`	string	`hybrid`	`hybrid` combines keyword and meaning-based matching; `non_hybrid` uses meaning only.

Unknown fields are rejected with 422, so a misspelt option fails loudly instead of being ignored.

Python

import os
import requests

API_ROOT = "https://futuresmart.ai/document-intelligence/api"
COLLECTION_ID = os.environ["DOCUMENT_INTELLIGENCE_COLLECTION_ID"]

r = requests.post(
    f"{API_ROOT}/v1/{COLLECTION_ID}/search",
    headers={"x-api-key": os.environ["DOCUMENT_INTELLIGENCE_API_KEY"]},
    json={"query": "late payment fee", "num_chunks": 3},
    timeout=60,
)
r.raise_for_status()
for chunk in r.json()["chunks"]:
    print(f"{chunk['relevance_score']:.2f}  {chunk['file_name']}: {chunk['chunk_text'][:80]!r}")

JavaScript

const API_ROOT = "https://futuresmart.ai/document-intelligence/api";
const COLLECTION_ID = process.env.DOCUMENT_INTELLIGENCE_COLLECTION_ID;

const res = await fetch(`${API_ROOT}/v1/${COLLECTION_ID}/search`, {
  method: "POST",
  headers: {
    "x-api-key": process.env.DOCUMENT_INTELLIGENCE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "late payment fee", num_chunks: 3 }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
for (const chunk of (await res.json()).chunks) {
  console.log(chunk.relevance_score.toFixed(2), chunk.file_name, chunk.chunk_text.slice(0, 80));
}

Shell

curl -sS -X POST "https://futuresmart.ai/document-intelligence/api/v1/$DOCUMENT_INTELLIGENCE_COLLECTION_ID/search" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "late payment fee", "num_chunks": 3}'

Response

JSON

{
  "chunks": [
    {
      "id": "9b4c93f6-0e72-5903-bc5a-b5103a75928f",
      "object_id": "b59a5c27-80d5-4d24-818f-3fa50f987670",
      "knowledge_id": "d60416be-8e29-458f-adf9-3a4839059855",
      "file_name": "terms.txt",
      "chunk_text": "File Name: terms.txt\n\nExtracted Text: … Late payments incur a 1.5% monthly fee. …",
      "relevance_score": 1.0,
      "search_method": "hybrid_knowledge_base"
    }
  ]
}

chunk_text is the indexed text of the section, prefixed with the file name and any extra context the service added when indexing.
relevance_score ranks results within one response. Compare scores inside a response, not across queries.
object_id identifies the document; use it to fetch the document's extracted fields or to restrict a later search with object_ids.

Search or chat?

Use search when	Use chat when
You want the passages, not prose	You want a written answer
You run your own model or ranking	You want sources picked and cited for you
You need predictable, fast responses	You need follow-up questions with memory

Search a collection

#Request

#Response

#Search or chat?

Request

Response

Search or chat?