Query
curl --request POST \
--url https://api.example.com/query \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"stream": true,
"response_mode": "<string>",
"query_depth": "<string>",
"model": "<string>",
"session_id": "<string>",
"maintain_context": true,
"include_summary": true,
"web_search_enabled": true,
"conversation_upload_ids": [
"<string>"
]
}
'import requests
url = "https://api.example.com/query"
payload = {
"query": "<string>",
"stream": True,
"response_mode": "<string>",
"query_depth": "<string>",
"model": "<string>",
"session_id": "<string>",
"maintain_context": True,
"include_summary": True,
"web_search_enabled": True,
"conversation_upload_ids": ["<string>"]
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
stream: true,
response_mode: '<string>',
query_depth: '<string>',
model: '<string>',
session_id: '<string>',
maintain_context: true,
include_summary: true,
web_search_enabled: true,
conversation_upload_ids: ['<string>']
})
};
fetch('https://api.example.com/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.example.com/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' => '<string>',
'stream' => true,
'response_mode' => '<string>',
'query_depth' => '<string>',
'model' => '<string>',
'session_id' => '<string>',
'maintain_context' => true,
'include_summary' => true,
'web_search_enabled' => true,
'conversation_upload_ids' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"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.example.com/query"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"stream\": true,\n \"response_mode\": \"<string>\",\n \"query_depth\": \"<string>\",\n \"model\": \"<string>\",\n \"session_id\": \"<string>\",\n \"maintain_context\": true,\n \"include_summary\": true,\n \"web_search_enabled\": true,\n \"conversation_upload_ids\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
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.example.com/query")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"stream\": true,\n \"response_mode\": \"<string>\",\n \"query_depth\": \"<string>\",\n \"model\": \"<string>\",\n \"session_id\": \"<string>\",\n \"maintain_context\": true,\n \"include_summary\": true,\n \"web_search_enabled\": true,\n \"conversation_upload_ids\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/query")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"stream\": true,\n \"response_mode\": \"<string>\",\n \"query_depth\": \"<string>\",\n \"model\": \"<string>\",\n \"session_id\": \"<string>\",\n \"maintain_context\": true,\n \"include_summary\": true,\n \"web_search_enabled\": true,\n \"conversation_upload_ids\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"summary": "ACME Corp reported $50M revenue in Q4 2025, representing a 23% increase year-over-year. CEO Jane Smith attributed the growth to the enterprise segment.",
"session_id": "sess_abc123",
"total_facts": 12,
"total_chunks": 5,
"metadata": {
"entities": ["ACME Corp", "Jane Smith"],
"model": "gpt-4o-mini",
"search_time": "1.2s"
}
}
Endpoints
Query
Query the knowledge base with natural language
POST
/
query
Query
curl --request POST \
--url https://api.example.com/query \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"stream": true,
"response_mode": "<string>",
"query_depth": "<string>",
"model": "<string>",
"session_id": "<string>",
"maintain_context": true,
"include_summary": true,
"web_search_enabled": true,
"conversation_upload_ids": [
"<string>"
]
}
'import requests
url = "https://api.example.com/query"
payload = {
"query": "<string>",
"stream": True,
"response_mode": "<string>",
"query_depth": "<string>",
"model": "<string>",
"session_id": "<string>",
"maintain_context": True,
"include_summary": True,
"web_search_enabled": True,
"conversation_upload_ids": ["<string>"]
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
stream: true,
response_mode: '<string>',
query_depth: '<string>',
model: '<string>',
session_id: '<string>',
maintain_context: true,
include_summary: true,
web_search_enabled: true,
conversation_upload_ids: ['<string>']
})
};
fetch('https://api.example.com/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.example.com/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' => '<string>',
'stream' => true,
'response_mode' => '<string>',
'query_depth' => '<string>',
'model' => '<string>',
'session_id' => '<string>',
'maintain_context' => true,
'include_summary' => true,
'web_search_enabled' => true,
'conversation_upload_ids' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"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.example.com/query"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"stream\": true,\n \"response_mode\": \"<string>\",\n \"query_depth\": \"<string>\",\n \"model\": \"<string>\",\n \"session_id\": \"<string>\",\n \"maintain_context\": true,\n \"include_summary\": true,\n \"web_search_enabled\": true,\n \"conversation_upload_ids\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
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.example.com/query")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"stream\": true,\n \"response_mode\": \"<string>\",\n \"query_depth\": \"<string>\",\n \"model\": \"<string>\",\n \"session_id\": \"<string>\",\n \"maintain_context\": true,\n \"include_summary\": true,\n \"web_search_enabled\": true,\n \"conversation_upload_ids\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/query")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"stream\": true,\n \"response_mode\": \"<string>\",\n \"query_depth\": \"<string>\",\n \"model\": \"<string>\",\n \"session_id\": \"<string>\",\n \"maintain_context\": true,\n \"include_summary\": true,\n \"web_search_enabled\": true,\n \"conversation_upload_ids\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"summary": "ACME Corp reported $50M revenue in Q4 2025, representing a 23% increase year-over-year. CEO Jane Smith attributed the growth to the enterprise segment.",
"session_id": "sess_abc123",
"total_facts": 12,
"total_chunks": 5,
"metadata": {
"entities": ["ACME Corp", "Jane Smith"],
"model": "gpt-4o-mini",
"search_time": "1.2s"
}
}
Query the Vrin knowledge base. Returns an AI-generated answer backed by knowledge graph facts and vector search results.
string
required
Bearer token. Example:
Bearer vrin_live_abc123string
required
Natural-language question to answer.
boolean
default:"false"
If
true, the response is delivered as Server-Sent Events (SSE). Each event contains a JSON object with type and data fields.string
default:"chat"
Answer depth:
"chat" (concise), "thinking" (reasoning chains), "research" (exhaustive multi-hop).string
Override retrieval depth:
"basic", "thinking", "research".string
LLM model override (e.g.
"gpt-4o").string
Conversation session ID to continue.
boolean
default:"false"
If
true, maintain conversation context. A session_id will be returned in the response.boolean
default:"true"
If
true, include AI-generated summary. Set to false for raw fact retrieval only.boolean
default:"false"
Enable web search augmentation.
string[]
Upload IDs to include as additional context.
Non-streaming response
{
"success": true,
"summary": "ACME Corp reported $50M revenue in Q4 2025, representing a 23% increase year-over-year. CEO Jane Smith attributed the growth to the enterprise segment.",
"session_id": "sess_abc123",
"total_facts": 12,
"total_chunks": 5,
"metadata": {
"entities": ["ACME Corp", "Jane Smith"],
"model": "gpt-4o-mini",
"search_time": "1.2s"
}
}
Streaming response (SSE)
Whenstream: true, the response is text/event-stream:
data: {"type": "metadata", "data": {"session_id": "sess_abc123", "total_facts": 12, "entities": ["ACME Corp"]}}
data: {"type": "content", "data": {"delta": "ACME Corp "}}
data: {"type": "content", "data": {"delta": "reported $50M "}}
data: {"type": "sources", "data": {"sources": [{"title": "ACME Q4 Earnings", "chunk_id": "c_123"}]}}
data: {"type": "done", "data": {}}
SSE event types
| Type | Data fields | Description |
|---|---|---|
metadata | session_id, total_facts, total_chunks, entities, model | Retrieval metadata, sent first |
content | delta | Text token |
reasoning | chains or steps | Reasoning chain steps |
sources | sources | Source document references |
done | error?, insufficient_coverage? | Stream complete |
error | message | Fatal error |
Insufficient coverage
When the knowledge base has no relevant facts, the response includesinsufficient_coverage: true and skips LLM generation.
{
"success": true,
"summary": "",
"insufficient_coverage": true,
"total_facts": 0,
"total_chunks": 0
}
⌘I