Skip to main content
POST
/
api
/
v1
/
knowledge-bases
/
query
Query knowledge base
curl --request POST \
  --url https://app.dumplingai.com/api/v1/knowledge-bases/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "knowledgeBaseId": "kb_123",
  "query": "onboarding process"
}
'
{}

​
Description

This endpoint allows users to query a knowledge base using vector similarity search. It returns chunks of text from the knowledge base that are most similar to the provided query.
Note: Creating new knowledge bases is no longer available, but this endpoint continues to work for querying existing knowledge bases. Knowledge bases will be fully retired in December 2025 due to low usage.

​
Endpoint

POST https://app.dumplingai.com/api/v1/knowledge-bases/query

​
Headers

  • Content-Type: application/json
  • Authorization: Bearer <API_KEY> (required for API access)

​
Request Body

{
  "knowledgeBaseId": "string", // Required. The ID of the knowledge base to query.
  "query": "string", // Required. The search query.
  "resultCount": "number" // Optional. Number of results to return. Default is 5.
}

​
Responses

​
Success (200)

Returns an array of similar chunks from the knowledge base. 
[
  {
    "id": "string",
    "content": "string",
    "resource_name": "string",
    "similarity": "number"
  }
]
  • X-RateLimit-Limit: The rate limit for the user.
  • X-RateLimit-Remaining: The remaining number of requests for the user.

​
Bad Request (400)

Returned if required fields are missing or if the query is too long. 
{
  "error": "Error message describing the issue"
}

​
Unauthorized (401)

Returned if the API key is invalid or missing. 
{
  "error": "Invalid or missing Authorization header"
}

​
Internal Server Error (500)

Returned if there’s an error during the query process. 
{
  "error": "Failed to query knowledge base"
}

​
Example Request

curl -X POST https://app.dumplingai.com/api/v1/knowledge-bases/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "knowledgeBaseId": "kb123456",
    "query": "What are our company holiday policies?",
    "resultCount": 5
  }'

​
Notes

  • This endpoint uses 10 credits per request.
  • The query is limited to 4000 characters.
  • The resultCount parameter determines the number of similar chunks returned. The default is 5. Minimum is 1. Maximum is 25.
  • The similarity search uses vector embeddings to find the most relevant chunks of text.
  • Usage is recorded for each query, including the knowledge base ID and the number of credits used.

​
Rate Limiting

Rate limit headers (X-RateLimit-Limit and X-RateLimit-Remaining) are included in the response to indicate the user’s current rate limit status.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Run a semantic search against a knowledge base.

​
knowledgeBaseId
string
required

Knowledge base identifier to search.

​
query
string
required

Natural language query, limited to 4000 characters.

Maximum string length: 4000
​
resultCount
integer
default:5

Maximum number of matching chunks to return.

Required range: 1 <= x <= 20

Response

Knowledge base query results returned.

Flexible JSON structure; fields differ per endpoint.