Search & query

View as Markdown Open in ChatGPT Open in Claude

Retrieval endpoints for knowledge bases. These require only a member key (any workspace member with a valid key) — see Authentication. All return the { "data": ... } envelope. These endpoints are also in the interactive explorer .

Search across all knowledge bases

POST/knowledge-bases/searchMember key

Semantic search over every knowledge base in the workspace (or a subset).

Body

Field	Type	Default	Notes
`query`	string (1–2048)	—	Required.
`scope.knowledgeBaseIds`	UUID[]	—	Omit to search all.
`options.topK`	integer 1–50	10	Max results.
`options.minSimilarity`	number 0–1	0.5	Cosine cutoff.
`options.includeContent`	boolean	true
`options.includeMetadata`	boolean	true


curl -X POST https://tmmate.ai/api/v1/knowledge-bases/search \
  -H "Authorization: Bearer $TEAMMATE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "query": "how long do refunds take?", "options": { "topK": 5 } }'


{
  "data": {
    "query": "how long do refunds take?",
    "results": [
      { "chunkId": "…UUID", "knowledgeBaseId": "b2f1…UUID", "knowledgeBaseTitle": "Refund policy",
        "contentId": "…UUID", "content": "Refunds are processed within 5 business days.", "similarity": 0.82, "metadata": {} }
    ],
    "usage": { "embeddingTokens": 8, "model": "openai/text-embedding-3-small" }
  }
}

usage.embeddingTokens is an estimate.

Search inside one knowledge base

POST/knowledge-bases/{knowledgeBaseId}/searchMember key

Same body as above (the scope field is ignored — scope is the URL). Returns the same shape, scoped to that knowledge base. 404 if it doesn’t exist in your workspace.

Ask a question (RAG)

POST/knowledge-bases/{knowledgeBaseId}/queryMember key

Searches the knowledge base and synthesizes an answer with citations.

Body

Field	Type	Default
`question`	string (1–2048)	— (required)
`options.topK`	integer 1–20	6
`options.minSimilarity`	number 0–1	0.5
`options.maxAnswerTokens`	integer > 0	500
`options.model`	partial ModelConfig	server default (`openai/gpt-4o-mini`)


curl -X POST https://tmmate.ai/api/v1/knowledge-bases/b2f1…UUID/query \
  -H "Authorization: Bearer $TEAMMATE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "question": "How long do refunds take?" }'


{
  "data": {
    "answer": "Refunds are processed within 5 business days. [1]",
    "citations": [
      { "id": 1, "chunkId": "…UUID", "knowledgeBaseId": "b2f1…UUID", "content": "Refunds are processed within 5 business days.", "similarity": 0.82, "metadata": null }
    ],
    "usage": { "embeddingTokens": 8, "promptTokens": 412, "completionTokens": 18, "totalTokens": 438 }
  }
}

If nothing matches, you get a 200 with a “no relevant information” answer and empty citations. Answer synthesis uses OpenRouter on the server; if it isn’t configured, the endpoint returns 400.

Ingestion status

GET/knowledge-bases/{knowledgeBaseId}/statusMember key


{ "data": { "knowledgeBaseId": "b2f1…UUID", "counts": { "ready": 12, "queued": 0, "failed": 0, "total": 12 }, "isReady": true } }

Embedding is synchronous, so queued is always 0; isReady is true when total > 0 and every content row embedded.

Inspect embeddings

GET/knowledge-bases/{knowledgeBaseId}/embeddingsMember key

Query	Type	Default
`limit`	integer 1–500	100
`offset`	integer ≥ 0	0
`includeVector`	boolean	false


{
  "data": {
    "knowledgeBaseId": "b2f1…UUID",
    "embeddings": [ { "id": "…UUID", "contentId": "…UUID", "content": "…", "metadata": null, "createdAt": "2026-05-21T10:00:00.000Z" } ],
    "pagination": { "total": 12, "limit": 100, "offset": 0 }
  }
}

Set includeVector=true to include the 1536-dimension vector array on each row.