Search knowledge
Retrieve the most relevant passages from your knowledge bases to use in your own application.
POST /v1/knowledge/search returns the passages from your knowledge bases that best match a question. Use it to add retrieval over your own documents to another application.
Scope: knowledge:read.
List the knowledge bases a key can search
curl "$AGENTWORKS_API_URL/v1/knowledge/folders" \
-H "Authorization: Bearer $AGENTWORKS_API_KEY"
{
"status": "success",
"result": [
{ "id": "…", "name": "Product manuals", "description": null, "documentCount": 3 }
]
}
Search
curl -X POST "$AGENTWORKS_API_URL/v1/knowledge/search" \
-H "Authorization: Bearer $AGENTWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "What is the warranty period?", "topK": 5}'
| Field | |
|---|---|
query | Required. The question or search text. |
knowledgeBaseIds | Optional. Limit the search to these knowledge bases. Default: every knowledge base the key can read. |
topK | Optional, 1 to 50. How many passages to return. |
minScore | Optional, 0 to 1. Leave out passages below this similarity. |
Response
{
"status": "success",
"result": [
{
"id": "…",
"text": "The warranty period is 24 months from delivery…",
"similarity": 0.87,
"subsource": "…",
"subname": "warranty-terms.pdf",
"url": null,
"index": 0
}
]
}
subname is the file the passage comes from; url is filled when the source has a web address.
Good to know
- A key searches what its owner can see. Knowledge that is not shared with that person is not searched.
- If no knowledge base is accessible, the result is an empty list, not an error.
- Requests from a browser are refused. Call this endpoint from your server.