Test a knowledge-base document query
curl --request POST \
--url https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "What is the refund window for enterprise plans?",
"limit": 5,
"synthesize": true
}
'import requests
url = "https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query"
payload = {
"query": "What is the refund window for enterprise plans?",
"limit": 5,
"synthesize": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'What is the refund window for enterprise plans?',
limit: 5,
synthesize: true
})
};
fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'What is the refund window for enterprise plans?',
'limit' => 5,
'synthesize' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query"
payload := strings.NewReader("{\n \"query\": \"What is the refund window for enterprise plans?\",\n \"limit\": 5,\n \"synthesize\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"What is the refund window for enterprise plans?\",\n \"limit\": 5,\n \"synthesize\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"What is the refund window for enterprise plans?\",\n \"limit\": 5,\n \"synthesize\": true\n}"
response = http.request(request)
puts response.read_body{
"data": {
"agent_id": "<string>",
"document_id": "<string>",
"doc_version_at_query": 123,
"query": "<string>",
"chunks": [
{}
],
"synthesized_answer": "<string>",
"kb_collection_missing": true,
"query_embedding_dim": 123,
"rag_pii_redaction_applied": true
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}Agents
Test a knowledge-base document query
Run a real similarity search scoped to a single knowledge-base document and return the top-matching chunks plus the synthesized answer the agent would generate — a sandbox for verifying retrieval quality before shipping. Bumps each matched chunk’s retrieval count so operators can watch retrieval frequency stabilise. Requires an operator role (owner, admin, or developer) because it calls the LLM provider and is billable.
POST
/
api
/
v1
/
agents
/
{agentId}
/
knowledge-base
/
{docId}
/
test-query
Test a knowledge-base document query
curl --request POST \
--url https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "What is the refund window for enterprise plans?",
"limit": 5,
"synthesize": true
}
'import requests
url = "https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query"
payload = {
"query": "What is the refund window for enterprise plans?",
"limit": 5,
"synthesize": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'What is the refund window for enterprise plans?',
limit: 5,
synthesize: true
})
};
fetch('https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'What is the refund window for enterprise plans?',
'limit' => 5,
'synthesize' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query"
payload := strings.NewReader("{\n \"query\": \"What is the refund window for enterprise plans?\",\n \"limit\": 5,\n \"synthesize\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"What is the refund window for enterprise plans?\",\n \"limit\": 5,\n \"synthesize\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orbit.devotel.io/api/v1/agents/{agentId}/knowledge-base/{docId}/test-query")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"What is the refund window for enterprise plans?\",\n \"limit\": 5,\n \"synthesize\": true\n}"
response = http.request(request)
puts response.read_body{
"data": {
"agent_id": "<string>",
"document_id": "<string>",
"doc_version_at_query": 123,
"query": "<string>",
"chunks": [
{}
],
"synthesized_answer": "<string>",
"kb_collection_missing": true,
"query_embedding_dim": 123,
"rag_pii_redaction_applied": true
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}Authorizations
BearerApiKey
Dashboard JWT token from Clerk
Body
application/json
The natural-language query to run against the document.
Required string length:
1 - 2000Top-K chunks to return.
Required range:
1 <= x <= 20Minimum similarity score for a chunk to be included.
Required range:
0 <= x <= 1Whether to also synthesize an answer from the retrieved chunks.
⌘I