Query

curl https://api.conare.ai/namespaces/docs/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how do refunds work?",
    "top_k": 5,
    "filter": { "team": "support" }
  }'

const results = await docs.query("how do refunds work?", {
  topK: 5,
  filter: { team: "support" },
});

{
  "results": [
    {
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.34,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "took_ms": 34
}

​

Request

• query (string, required): What to search for, in plain language. Up to 8,000 characters.
• top_k (integer, default 10): Results to return, 1-100.
• filter (object): A metadata filter.
• rerank (boolean, default true): Rerank the best matches. false is faster.
• rerank_depth (integer, default 20): How many of the top passages to rerank, 1-100.
• retrievers (array, default ["vector", "keyword"]): The retrievers to combine.
• user (string): Only this user’s documents.
• user_prefix (string): Only the documents of the users that start with it, such as tenant-7:. It ends with :.

​

Response

• results: Best first, one per document.
  • id, metadata: The document’s.
  • text: The document’s best matching passage, up to about 2,000 bytes. Get the document for its full text.
  • score: Higher is better. Reranked and unreranked scores aren’t comparable, and neither compares across queries.
  • reranked: Whether the reranker scored this result. Results past rerank_depth aren’t reranked, and come after those that are.
  • user: The document’s user. Left out if it has none.
• took_ms: Time spent searching, in milliseconds.

​

Retrievers

​

Users

curl https://api.conare.ai/namespaces/docs/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund requests", "user_prefix": "tenant-7:"}'

const results = await docs.query("refund requests", { userPrefix: "tenant-7:" });

• user_prefix: "tenant-7:" matches tenant-7:u_42 and tenant-7:team-a:u_7, but not tenant-7.
• user, user_prefix and filter combine: a result matches all of them.

​

Search every namespace

curl https://api.conare.ai/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "prefix": "acme-"}'

{
  "results": [
    {
      "namespace": "acme-docs",
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.34,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "namespaces": ["acme-docs", "acme-tickets"],
  "skipped_namespaces": [],
  "took_ms": 43
}

• Each result names its namespace. A passage repeated in two namespaces appears once.
• namespaces lists the namespaces searched, and skipped_namespaces those past the first 100.
• A Some namespaces key searches only its own namespaces.
• rerank_depth defaults to 100.
• The SDK has no method for this route yet.

​

Degraded results

​

Behavior

• Querying an empty or missing namespace returns 404 namespace_not_found.
• A repeated query reuses its embedding for up to 10 minutes, so measure latency with distinct queries.