Search
Operations tagged Search in the public API.
About Search
POST /search runs the retrieval a chatbot uses to answer — vector search over trained knowledge (fused with keyword search where that is enabled), then reranking when the reranker is on — and returns the best-matching chunks with their scores, without generating an answer. Use it to check what a chatbot will find for a question, or to build your own search. GET /search/similar/{datasetId} searches inside one dataset.
Scope. Search covers the knowledge of every chatbot the API key reaches, or one collection with collection_id. Only trained chunks are found: a dataset still training is not searchable yet. Hits carry ids and scores; include_content: true adds each chunk's text.
Scores. Read score_kind before score: reranker is a calibrated 0–1 probability and cosine an absolute similarity, while fused and sparse only rank hits against each other.
IDs you will meet.
chunk_id— the chunk, asGET /knowledge/{id}/chunkslists it.dataset_id— the knowledge dataset the chunk belongs to.
IDs on this page
- Knowledge collection id
<COLLECTION_ID> - Integer.
Get it from
- POST /v1/knowledge/collections returns it as
id - GET /v1/knowledge/collections returns it as
data[].id - POST /v1/knowledge/collections/auto_create returns it as
id - GET /v1/knowledge/{id} returns it as
collection_id - Webhook knowledge.collection.created carries it as
data.object.id - Adding knowledge or a crawl with only
chatbot_idfiles it in the chatbot's default collection, created on first use: read its id ascollection_idon any of the chatbot's datasets.
- POST /v1/knowledge/collections returns it as
- Knowledge dataset id
<DATASET_ID> - Integer.
Get it from
- POST /v1/knowledge returns it as
id - GET /v1/knowledge returns it as
data[].id - GET /v1/chatbots/{id}/knowledge returns it as
data[].id - GET /v1/knowledge/collections/{id}/datasets returns it as
data[].id - POST /v1/knowledge/import/cloud returns it as
data[].id - GET /v1/files/{id} returns it as
knowledge_dataset_id - POST /v1/search returns it as
data[].dataset_id - Webhook knowledge.dataset.created carries it as
data.object.id - A crawler creates one dataset per page it collects; list them with
GET /chatbots/{id}/knowledge.
- POST /v1/knowledge returns it as
Search knowledge
Finds the chunks that best match
query across the trained knowledge of every chatbot the API key reaches — or one collection, with collection_id — using the retrieval a chatbot answers with. No answer is generated: you get up to limit hits (10 by default) with their score, and their text with include_content: true. Read each hit's score_kind before comparing scores.
A dataset still training is not found yet. total_results is the number of hits returned, not a total across all knowledge.- Required scope
- search:read
- Webhook events
- None
- Rate limits
Before you call
Integer.collection_id(body)Knowledge collection idPlaceholder in the samples:
<COLLECTION_ID>Get it from
- POST /v1/knowledge/collections returns it as
id - GET /v1/knowledge/collections returns it as
data[].id - POST /v1/knowledge/collections/auto_create returns it as
id - GET /v1/knowledge/{id} returns it as
collection_id - Webhook knowledge.collection.created carries it as
data.object.id - Adding knowledge or a crawl with only
chatbot_idfiles it in the chatbot's default collection, created on first use: read its id ascollection_idon any of the chatbot's datasets.
- POST /v1/knowledge/collections returns it as
Request body
querystringRequiredWhat to search for, in natural language: 3 to 500 characters.Min length:
3Max length:500limitintegernullableOptionalMaximum hits to return, 1 to 50. Defaults to 10.Minimum:
1Maximum:50collection_idintegernullableOptionalSearch only this knowledge collection of your account (another account's is 422VALIDATION_FAILED). Omit it to search the trained knowledge of every chatbot the API key reaches.include_contentbooleannullableOptionalReturn each hit's text aschunk_text. Defaults tofalse: hits then carry only ids and scores.
Responses
- 200Search hits, each
{chunk_id, dataset_id, chunk_index, score, score_kind}pluschunk_textwheninclude_contentis true.score_kindisreranker(calibrated 0..1 probability),cosine(absolute similarity),fused(rank fusion, no absolute meaning) orsparse(keyword-only, no absolute meaning). Vector-store point ids and tenant payload fields are never returned.objectstringRequiredAlways
search_resultsquerystringRequiredThe query that was searched.dataarray of SearchHitResourceRequiredThe hits.total_resultsintegerRequiredHow many hitsdataholds.
- 400A tenant selector header named a tenant other than the API key's own (
ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digitX-Account-Idother than the key owner's id or, whileworkspaces.context_enabledis on, anX-Workspace-Idother than the key's workspace (ws_prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numericX-Account-Id, is ignored; a key cannot switch tenants, so send neither.Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
- 401Missing or invalid API key.
Error codesUNAUTHENTICATED
- 403The API key is missing a required scope.
Error codesACCOUNT_SUSPENDEDINSUFFICIENT_SCOPE
- 422Validation failed. See
error.details.Error codesVALIDATION_FAILED
- 429Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
- 500Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR
Request
curl
curl -X POST 'https://api.agentency.com/v1/search' \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json"
-d '{
"query": "query",
"limit": "limit",
"collection_id": 1,
"include_content": "include_content"
}'Response
Example 200 response
json
{
"object": "search_results",
"query": "How do refunds work?",
"data": [
{
"chunk_id": 1,
"dataset_id": 1,
"chunk_index": 0,
"score": 0.8731,
"score_kind": "cosine",
"chunk_text": "Refunds are issued to the original payment method within 5 business days."
}
],
"total_results": 1
}Search inside one dataset
Finds the chunks of one knowledge dataset closest to
query — by default the dataset's own name — with the same retrieval as POST /search. Use it to see which passages of a source answer a question, or to check that a dataset trained the way you expect. Hits never carry chunk_text: read the passages with GET /knowledge/{id}/chunks. A dataset still training returns no hits yet.- Required scope
- search:read
- Idempotency
- Read-only
- Rate limits
Before you call
Integer.datasetId(path)Knowledge dataset idPlaceholder in the samples:
<DATASET_ID>Get it from
- POST /v1/knowledge returns it as
id - GET /v1/knowledge returns it as
data[].id - GET /v1/chatbots/{id}/knowledge returns it as
data[].id - GET /v1/knowledge/collections/{id}/datasets returns it as
data[].id - POST /v1/knowledge/import/cloud returns it as
data[].id - GET /v1/files/{id} returns it as
knowledge_dataset_id - POST /v1/search returns it as
data[].dataset_id - Webhook knowledge.dataset.created carries it as
data.object.id - A crawler creates one dataset per page it collects; list them with
GET /chatbots/{id}/knowledge.
- POST /v1/knowledge returns it as
Path parameters
datasetIdintegerRequiredThe knowledge dataset id.
Query parameters
querystringnullableOptionalText to compare against, at most 500 characters. Defaults to the dataset's name.Max length:
500limitintegernullableOptionalMaximum hits to return, 1 to 50. Defaults to 10.Minimum:
1Maximum:50
Responses
- 200Hits from the given dataset, each
{chunk_id, dataset_id, chunk_index, score, score_kind};score_kindisreranker,cosine,fusedorsparse. Vector-store point ids and tenant payload fields are never returned.objectstringRequiredAlways
search_resultsquerystringRequiredThe text that was compared: yourquery, or the dataset's name.dataarray of SearchHitResourceRequiredThe hits, all from the requested dataset.total_resultsintegerRequiredHow many hitsdataholds.
- 400A tenant selector header named a tenant other than the API key's own (
ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digitX-Account-Idother than the key owner's id or, whileworkspaces.context_enabledis on, anX-Workspace-Idother than the key's workspace (ws_prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numericX-Account-Id, is ignored; a key cannot switch tenants, so send neither.Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
- 401Missing or invalid API key.
Error codesUNAUTHENTICATED
- 403The API key is missing a required scope.
Error codesACCOUNT_SUSPENDEDINSUFFICIENT_SCOPE
- 404The resource does not exist on this account.
Error codesNOT_FOUND
- 422Validation failed. See
error.details.Error codesVALIDATION_FAILED
- 429Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
- 500Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR
Request
curl
curl -X GET 'https://api.agentency.com/v1/search/similar/<DATASET_ID>' \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json"Response
Example 200 response
json
{
"object": "search_results",
"query": "Refund policy",
"data": [
{
"chunk_id": 1,
"dataset_id": 1,
"chunk_index": 0,
"score": 0.8731,
"score_kind": "cosine"
}
],
"total_results": 1
}