Query
curl --request POST \
--url https://api.contextual.ai/v1/agents/{agent_id}/query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"messages": [
{
"content": "<string>",
"custom_tags": [
"<string>"
]
}
],
"stream": false,
"conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"llm_model_id": "<string>",
"documents_filters": {
"operator": "AND"
},
"override_configuration": {
"system_prompt": "<string>",
"filter_prompt": "<string>",
"model": "<string>",
"max_new_tokens": 123,
"top_p": 123,
"temperature": 123,
"top_k_retrieved_chunks": 123,
"top_k_reranked_chunks": 123,
"enable_filter": true,
"filter_model": "<string>",
"enable_rerank": true,
"reranker": "<string>",
"lexical_alpha": 123,
"semantic_alpha": 123,
"rerank_instructions": "<string>",
"reranker_score_filter_threshold": 123,
"use_optimized_context": true
}
}
'import requests
url = "https://api.contextual.ai/v1/agents/{agent_id}/query"
payload = {
"messages": [
{
"content": "<string>",
"custom_tags": ["<string>"]
}
],
"stream": False,
"conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"llm_model_id": "<string>",
"documents_filters": { "operator": "AND" },
"override_configuration": {
"system_prompt": "<string>",
"filter_prompt": "<string>",
"model": "<string>",
"max_new_tokens": 123,
"top_p": 123,
"temperature": 123,
"top_k_retrieved_chunks": 123,
"top_k_reranked_chunks": 123,
"enable_filter": True,
"filter_model": "<string>",
"enable_rerank": True,
"reranker": "<string>",
"lexical_alpha": 123,
"semantic_alpha": 123,
"rerank_instructions": "<string>",
"reranker_score_filter_threshold": 123,
"use_optimized_context": 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({
messages: [{content: '<string>', custom_tags: ['<string>']}],
stream: false,
conversation_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
llm_model_id: '<string>',
documents_filters: {operator: 'AND'},
override_configuration: {
system_prompt: '<string>',
filter_prompt: '<string>',
model: '<string>',
max_new_tokens: 123,
top_p: 123,
temperature: 123,
top_k_retrieved_chunks: 123,
top_k_reranked_chunks: 123,
enable_filter: true,
filter_model: '<string>',
enable_rerank: true,
reranker: '<string>',
lexical_alpha: 123,
semantic_alpha: 123,
rerank_instructions: '<string>',
reranker_score_filter_threshold: 123,
use_optimized_context: true
}
})
};
fetch('https://api.contextual.ai/v1/agents/{agent_id}/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.contextual.ai/v1/agents/{agent_id}/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([
'messages' => [
[
'content' => '<string>',
'custom_tags' => [
'<string>'
]
]
],
'stream' => false,
'conversation_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'llm_model_id' => '<string>',
'documents_filters' => [
'operator' => 'AND'
],
'override_configuration' => [
'system_prompt' => '<string>',
'filter_prompt' => '<string>',
'model' => '<string>',
'max_new_tokens' => 123,
'top_p' => 123,
'temperature' => 123,
'top_k_retrieved_chunks' => 123,
'top_k_reranked_chunks' => 123,
'enable_filter' => true,
'filter_model' => '<string>',
'enable_rerank' => true,
'reranker' => '<string>',
'lexical_alpha' => 123,
'semantic_alpha' => 123,
'rerank_instructions' => '<string>',
'reranker_score_filter_threshold' => 123,
'use_optimized_context' => 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.contextual.ai/v1/agents/{agent_id}/query"
payload := strings.NewReader("{\n \"messages\": [\n {\n \"content\": \"<string>\",\n \"custom_tags\": [\n \"<string>\"\n ]\n }\n ],\n \"stream\": false,\n \"conversation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"llm_model_id\": \"<string>\",\n \"documents_filters\": {\n \"operator\": \"AND\"\n },\n \"override_configuration\": {\n \"system_prompt\": \"<string>\",\n \"filter_prompt\": \"<string>\",\n \"model\": \"<string>\",\n \"max_new_tokens\": 123,\n \"top_p\": 123,\n \"temperature\": 123,\n \"top_k_retrieved_chunks\": 123,\n \"top_k_reranked_chunks\": 123,\n \"enable_filter\": true,\n \"filter_model\": \"<string>\",\n \"enable_rerank\": true,\n \"reranker\": \"<string>\",\n \"lexical_alpha\": 123,\n \"semantic_alpha\": 123,\n \"rerank_instructions\": \"<string>\",\n \"reranker_score_filter_threshold\": 123,\n \"use_optimized_context\": true\n }\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.contextual.ai/v1/agents/{agent_id}/query")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"messages\": [\n {\n \"content\": \"<string>\",\n \"custom_tags\": [\n \"<string>\"\n ]\n }\n ],\n \"stream\": false,\n \"conversation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"llm_model_id\": \"<string>\",\n \"documents_filters\": {\n \"operator\": \"AND\"\n },\n \"override_configuration\": {\n \"system_prompt\": \"<string>\",\n \"filter_prompt\": \"<string>\",\n \"model\": \"<string>\",\n \"max_new_tokens\": 123,\n \"top_p\": 123,\n \"temperature\": 123,\n \"top_k_retrieved_chunks\": 123,\n \"top_k_reranked_chunks\": 123,\n \"enable_filter\": true,\n \"filter_model\": \"<string>\",\n \"enable_rerank\": true,\n \"reranker\": \"<string>\",\n \"lexical_alpha\": 123,\n \"semantic_alpha\": 123,\n \"rerank_instructions\": \"<string>\",\n \"reranker_score_filter_threshold\": 123,\n \"use_optimized_context\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.contextual.ai/v1/agents/{agent_id}/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 \"messages\": [\n {\n \"content\": \"<string>\",\n \"custom_tags\": [\n \"<string>\"\n ]\n }\n ],\n \"stream\": false,\n \"conversation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"llm_model_id\": \"<string>\",\n \"documents_filters\": {\n \"operator\": \"AND\"\n },\n \"override_configuration\": {\n \"system_prompt\": \"<string>\",\n \"filter_prompt\": \"<string>\",\n \"model\": \"<string>\",\n \"max_new_tokens\": 123,\n \"top_p\": 123,\n \"temperature\": 123,\n \"top_k_retrieved_chunks\": 123,\n \"top_k_reranked_chunks\": 123,\n \"enable_filter\": true,\n \"filter_model\": \"<string>\",\n \"enable_rerank\": true,\n \"reranker\": \"<string>\",\n \"lexical_alpha\": 123,\n \"semantic_alpha\": 123,\n \"rerank_instructions\": \"<string>\",\n \"reranker_score_filter_threshold\": 123,\n \"use_optimized_context\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"retrieval_contents": [
{
"type": "<string>",
"content_id": "<string>",
"doc_id": "<string>",
"doc_name": "<string>",
"custom_metadata": {},
"custom_metadata_config": {},
"number": 1,
"datastore_id": "<string>",
"page": 123,
"content_text": "<string>",
"url": "<string>",
"ctxl_metadata": {
"document_title": "<string>",
"section_title": "<string>",
"is_figure": true,
"file_name": "<string>",
"chunk_size": 123,
"file_format": "<string>",
"page": 123,
"chunk_id": "<string>",
"date_created": "<string>",
"section_id": "<string>"
},
"score": 123
}
],
"message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"message": {
"content": "<string>",
"custom_tags": [
"<string>"
]
},
"attributions": [
{
"start_idx": 123,
"end_idx": 123,
"content_ids": [
"<string>"
]
}
],
"groundedness_scores": [
{
"start_idx": 123,
"end_idx": 123,
"score": 123
}
]
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}/agents/{id}/query
Query
Start a conversation with an Agent and receive its generated response, along with relevant retrieved data and attributions.
POST
/
agents
/
{agent_id}
/
query
Query
curl --request POST \
--url https://api.contextual.ai/v1/agents/{agent_id}/query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"messages": [
{
"content": "<string>",
"custom_tags": [
"<string>"
]
}
],
"stream": false,
"conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"llm_model_id": "<string>",
"documents_filters": {
"operator": "AND"
},
"override_configuration": {
"system_prompt": "<string>",
"filter_prompt": "<string>",
"model": "<string>",
"max_new_tokens": 123,
"top_p": 123,
"temperature": 123,
"top_k_retrieved_chunks": 123,
"top_k_reranked_chunks": 123,
"enable_filter": true,
"filter_model": "<string>",
"enable_rerank": true,
"reranker": "<string>",
"lexical_alpha": 123,
"semantic_alpha": 123,
"rerank_instructions": "<string>",
"reranker_score_filter_threshold": 123,
"use_optimized_context": true
}
}
'import requests
url = "https://api.contextual.ai/v1/agents/{agent_id}/query"
payload = {
"messages": [
{
"content": "<string>",
"custom_tags": ["<string>"]
}
],
"stream": False,
"conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"llm_model_id": "<string>",
"documents_filters": { "operator": "AND" },
"override_configuration": {
"system_prompt": "<string>",
"filter_prompt": "<string>",
"model": "<string>",
"max_new_tokens": 123,
"top_p": 123,
"temperature": 123,
"top_k_retrieved_chunks": 123,
"top_k_reranked_chunks": 123,
"enable_filter": True,
"filter_model": "<string>",
"enable_rerank": True,
"reranker": "<string>",
"lexical_alpha": 123,
"semantic_alpha": 123,
"rerank_instructions": "<string>",
"reranker_score_filter_threshold": 123,
"use_optimized_context": 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({
messages: [{content: '<string>', custom_tags: ['<string>']}],
stream: false,
conversation_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
llm_model_id: '<string>',
documents_filters: {operator: 'AND'},
override_configuration: {
system_prompt: '<string>',
filter_prompt: '<string>',
model: '<string>',
max_new_tokens: 123,
top_p: 123,
temperature: 123,
top_k_retrieved_chunks: 123,
top_k_reranked_chunks: 123,
enable_filter: true,
filter_model: '<string>',
enable_rerank: true,
reranker: '<string>',
lexical_alpha: 123,
semantic_alpha: 123,
rerank_instructions: '<string>',
reranker_score_filter_threshold: 123,
use_optimized_context: true
}
})
};
fetch('https://api.contextual.ai/v1/agents/{agent_id}/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.contextual.ai/v1/agents/{agent_id}/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([
'messages' => [
[
'content' => '<string>',
'custom_tags' => [
'<string>'
]
]
],
'stream' => false,
'conversation_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'llm_model_id' => '<string>',
'documents_filters' => [
'operator' => 'AND'
],
'override_configuration' => [
'system_prompt' => '<string>',
'filter_prompt' => '<string>',
'model' => '<string>',
'max_new_tokens' => 123,
'top_p' => 123,
'temperature' => 123,
'top_k_retrieved_chunks' => 123,
'top_k_reranked_chunks' => 123,
'enable_filter' => true,
'filter_model' => '<string>',
'enable_rerank' => true,
'reranker' => '<string>',
'lexical_alpha' => 123,
'semantic_alpha' => 123,
'rerank_instructions' => '<string>',
'reranker_score_filter_threshold' => 123,
'use_optimized_context' => 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.contextual.ai/v1/agents/{agent_id}/query"
payload := strings.NewReader("{\n \"messages\": [\n {\n \"content\": \"<string>\",\n \"custom_tags\": [\n \"<string>\"\n ]\n }\n ],\n \"stream\": false,\n \"conversation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"llm_model_id\": \"<string>\",\n \"documents_filters\": {\n \"operator\": \"AND\"\n },\n \"override_configuration\": {\n \"system_prompt\": \"<string>\",\n \"filter_prompt\": \"<string>\",\n \"model\": \"<string>\",\n \"max_new_tokens\": 123,\n \"top_p\": 123,\n \"temperature\": 123,\n \"top_k_retrieved_chunks\": 123,\n \"top_k_reranked_chunks\": 123,\n \"enable_filter\": true,\n \"filter_model\": \"<string>\",\n \"enable_rerank\": true,\n \"reranker\": \"<string>\",\n \"lexical_alpha\": 123,\n \"semantic_alpha\": 123,\n \"rerank_instructions\": \"<string>\",\n \"reranker_score_filter_threshold\": 123,\n \"use_optimized_context\": true\n }\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.contextual.ai/v1/agents/{agent_id}/query")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"messages\": [\n {\n \"content\": \"<string>\",\n \"custom_tags\": [\n \"<string>\"\n ]\n }\n ],\n \"stream\": false,\n \"conversation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"llm_model_id\": \"<string>\",\n \"documents_filters\": {\n \"operator\": \"AND\"\n },\n \"override_configuration\": {\n \"system_prompt\": \"<string>\",\n \"filter_prompt\": \"<string>\",\n \"model\": \"<string>\",\n \"max_new_tokens\": 123,\n \"top_p\": 123,\n \"temperature\": 123,\n \"top_k_retrieved_chunks\": 123,\n \"top_k_reranked_chunks\": 123,\n \"enable_filter\": true,\n \"filter_model\": \"<string>\",\n \"enable_rerank\": true,\n \"reranker\": \"<string>\",\n \"lexical_alpha\": 123,\n \"semantic_alpha\": 123,\n \"rerank_instructions\": \"<string>\",\n \"reranker_score_filter_threshold\": 123,\n \"use_optimized_context\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.contextual.ai/v1/agents/{agent_id}/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 \"messages\": [\n {\n \"content\": \"<string>\",\n \"custom_tags\": [\n \"<string>\"\n ]\n }\n ],\n \"stream\": false,\n \"conversation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"llm_model_id\": \"<string>\",\n \"documents_filters\": {\n \"operator\": \"AND\"\n },\n \"override_configuration\": {\n \"system_prompt\": \"<string>\",\n \"filter_prompt\": \"<string>\",\n \"model\": \"<string>\",\n \"max_new_tokens\": 123,\n \"top_p\": 123,\n \"temperature\": 123,\n \"top_k_retrieved_chunks\": 123,\n \"top_k_reranked_chunks\": 123,\n \"enable_filter\": true,\n \"filter_model\": \"<string>\",\n \"enable_rerank\": true,\n \"reranker\": \"<string>\",\n \"lexical_alpha\": 123,\n \"semantic_alpha\": 123,\n \"rerank_instructions\": \"<string>\",\n \"reranker_score_filter_threshold\": 123,\n \"use_optimized_context\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"retrieval_contents": [
{
"type": "<string>",
"content_id": "<string>",
"doc_id": "<string>",
"doc_name": "<string>",
"custom_metadata": {},
"custom_metadata_config": {},
"number": 1,
"datastore_id": "<string>",
"page": 123,
"content_text": "<string>",
"url": "<string>",
"ctxl_metadata": {
"document_title": "<string>",
"section_title": "<string>",
"is_figure": true,
"file_name": "<string>",
"chunk_size": 123,
"file_format": "<string>",
"page": 123,
"chunk_id": "<string>",
"date_created": "<string>",
"section_id": "<string>"
},
"score": 123
}
],
"message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"message": {
"content": "<string>",
"custom_tags": [
"<string>"
]
},
"attributions": [
{
"start_idx": 123,
"end_idx": 123,
"content_ids": [
"<string>"
]
}
],
"groundedness_scores": [
{
"start_idx": 123,
"end_idx": 123,
"score": 123
}
]
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Agent ID of the agent to query
Query Parameters
Set to true to fetch retrieval content and metadata, and then skip generation of the response.
Set to true to include the text of the retrieved contents in the response. If false, only metadata about the retrieved contents will be included, not content text. This parameter is ignored if retrievals_only is true, in which case content_text will always be returned. Content text and other metadata can also be fetched separately using the /agents/{agent_id}/query/{message_id}/retrieval/info endpoint.
Body
application/json
Request body for a POST /agents/{agent_id}/query request
Messages sent so far in the conversation, ending in the latest user message. Add multiple objects to provide conversation history. Last message in the list must be a user-sent message (i.e. role equals "user").
Show child attributes
Show child attributes
Set to true to receive a streamed response
An optional alternative to providing message history in the messages field. If provided, all messages in the messages list prior to the latest user-sent query will be ignored.
Model ID of the specific fine-tuned or aligned LLM model to use. Defaults to base model if not specified.
Custom output structure format.
Show child attributes
Show child attributes
Defines a custom metadata filter. The expected input is a dict which can have different operators, fields and values. For example:
{"field": "title", "operator": "startswith", "value": "hr-"}
Use lowercase for value when not using equals operator. For document_id and date_created the query is built using direct query without nesting.
- BaseMetadataFilter
- CompositeMetadataFilter
Show child attributes
Show child attributes
Example:
{ "operator": "AND" }
This will modify select configuration parameters for the agent during the response generation.
Show child attributes
Show child attributes
Response
Successful Response
Response body for POST /query
A unique identifier for the conversation. Can be passed to future /query calls to continue a conversation with the same message history.
Relevant content retrieved to answer the query
Show child attributes
Show child attributes
A unique identifier for this specific message
Response to the query request
Show child attributes
Show child attributes
Attributions for the response
Show child attributes
Show child attributes
Groundedness scores for the response
Show child attributes
Show child attributes
Was this page helpful?
⌘I