curl --request POST \
--url https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "How to send SMS?",
"k": 5,
"reRankK": 10,
"useSharedHistory": false,
"sessionId": "session-12345"
}
'import requests
url = "https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context"
payload = {
"message": "How to send SMS?",
"k": 5,
"reRankK": 10,
"useSharedHistory": False,
"sessionId": "session-12345"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)using RestSharp;
var options = new RestClientOptions("https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "<api-key>");
request.AddJsonBody("{\n \"message\": \"How to send SMS?\",\n \"k\": 5,\n \"reRankK\": 10,\n \"useSharedHistory\": false,\n \"sessionId\": \"session-12345\"\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
HttpResponse<String> response = Unirest.post("https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"How to send SMS?\",\n \"k\": 5,\n \"reRankK\": 10,\n \"useSharedHistory\": false,\n \"sessionId\": \"session-12345\"\n}")
.asString();<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context",
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([
'message' => 'How to send SMS?',
'k' => 5,
'reRankK' => 10,
'useSharedHistory' => false,
'sessionId' => 'session-12345'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
message: 'How to send SMS?',
k: 5,
reRankK: 10,
useSharedHistory: false,
sessionId: 'session-12345'
})
};
fetch('https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"contexts": [
{
"node": {
"id": "node-123-abc",
"text": "To send SMS messages, you need to use the SMS API endpoint. Make a POST request to /sms/2/text/advanced with your authentication credentials and message payload.",
"metadata": {
"source": "sms-api-guide.pdf",
"page": 5,
"chapter": "Sending Messages"
},
"startCharIdx": 0,
"endCharIdx": 150
},
"score": 0.92
},
{
"node": {
"id": "node-456-def",
"text": "Authentication is required for all API calls. You can authenticate using an API key in the Authorization header with the format 'App YOUR_API_KEY'.",
"metadata": {
"source": "authentication-guide.pdf",
"page": 2
},
"startCharIdx": 200,
"endCharIdx": 350
},
"score": 0.85
}
]
}{
"errorCode": "E400",
"description": "Request cannot be processed.",
"action": "Check the syntax, violations and adjust the request.",
"violations": [
{
"property": "property.path",
"violation": "Violation message."
}
],
"resources": []
}{
"errorCode": "E401",
"description": "The request lacks valid authentication credentials for the requested resource.",
"action": "Check the resources and adjust authentication credentials.",
"violations": [],
"resources": [
{
"name": "API Authentication",
"url": "https://www.phonovation.com/docs/essentials/api-authentication"
}
]
}{
"errorCode": "E403",
"description": "Insufficient permissions to access the requested resource.",
"action": "Repeat the request with new or different credentials.",
"violations": [],
"resources": [
{
"name": "API Scopes",
"url": "https://www.phonovation.com/docs/essentials/api-essentials/api-authorization#api-scopes"
}
]
}{
"errorCode": "40401",
"description": "Assistant not found.",
"action": "Check the description for error details.",
"violations": [],
"resources": []
}{
"errorCode": "E429",
"description": "Too many requests sent.",
"action": "Check request rate limit specified in the API endpoint documentation resource.",
"violations": [],
"resources": [
{
"name": "Throttling handling errors",
"url": "https://www.phonovation.com/docs/essentials/integration-best-practices#throttling-handling-errors"
}
]
}{
"errorCode": "E500",
"description": "Something went wrong.",
"action": "Contact the support.",
"violations": [],
"resources": []
}Retrieve Context from AI Assistant
Retrieves the most relevant context chunks from an AI assistant’s knowledge base for a given message.
This endpoint performs a semantic search over the assistant’s indexed documents and returns the most relevant text segments (top k chunks). You can specify how many chunks to return and optionally enable re-ranking for more accurate results.
The “use shared history” feature allowing an AI assistant to utilize the agent’s conversation history, is only available if used together with Phonovation AI agents.
Required scope: Enable one of: ai:read.
curl --request POST \
--url https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "How to send SMS?",
"k": 5,
"reRankK": 10,
"useSharedHistory": false,
"sessionId": "session-12345"
}
'import requests
url = "https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context"
payload = {
"message": "How to send SMS?",
"k": 5,
"reRankK": 10,
"useSharedHistory": False,
"sessionId": "session-12345"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)using RestSharp;
var options = new RestClientOptions("https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "<api-key>");
request.AddJsonBody("{\n \"message\": \"How to send SMS?\",\n \"k\": 5,\n \"reRankK\": 10,\n \"useSharedHistory\": false,\n \"sessionId\": \"session-12345\"\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
HttpResponse<String> response = Unirest.post("https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"How to send SMS?\",\n \"k\": 5,\n \"reRankK\": 10,\n \"useSharedHistory\": false,\n \"sessionId\": \"session-12345\"\n}")
.asString();<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context",
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([
'message' => 'How to send SMS?',
'k' => 5,
'reRankK' => 10,
'useSharedHistory' => false,
'sessionId' => 'session-12345'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
message: 'How to send SMS?',
k: 5,
reRankK: 10,
useSharedHistory: false,
sessionId: 'session-12345'
})
};
fetch('https://api.messaging.phonovation.com/ai/1/aiassistants/{assistantId}/retrieve-context', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"contexts": [
{
"node": {
"id": "node-123-abc",
"text": "To send SMS messages, you need to use the SMS API endpoint. Make a POST request to /sms/2/text/advanced with your authentication credentials and message payload.",
"metadata": {
"source": "sms-api-guide.pdf",
"page": 5,
"chapter": "Sending Messages"
},
"startCharIdx": 0,
"endCharIdx": 150
},
"score": 0.92
},
{
"node": {
"id": "node-456-def",
"text": "Authentication is required for all API calls. You can authenticate using an API key in the Authorization header with the format 'App YOUR_API_KEY'.",
"metadata": {
"source": "authentication-guide.pdf",
"page": 2
},
"startCharIdx": 200,
"endCharIdx": 350
},
"score": 0.85
}
]
}{
"errorCode": "E400",
"description": "Request cannot be processed.",
"action": "Check the syntax, violations and adjust the request.",
"violations": [
{
"property": "property.path",
"violation": "Violation message."
}
],
"resources": []
}{
"errorCode": "E401",
"description": "The request lacks valid authentication credentials for the requested resource.",
"action": "Check the resources and adjust authentication credentials.",
"violations": [],
"resources": [
{
"name": "API Authentication",
"url": "https://www.phonovation.com/docs/essentials/api-authentication"
}
]
}{
"errorCode": "E403",
"description": "Insufficient permissions to access the requested resource.",
"action": "Repeat the request with new or different credentials.",
"violations": [],
"resources": [
{
"name": "API Scopes",
"url": "https://www.phonovation.com/docs/essentials/api-essentials/api-authorization#api-scopes"
}
]
}{
"errorCode": "40401",
"description": "Assistant not found.",
"action": "Check the description for error details.",
"violations": [],
"resources": []
}{
"errorCode": "E429",
"description": "Too many requests sent.",
"action": "Check request rate limit specified in the API endpoint documentation resource.",
"violations": [],
"resources": [
{
"name": "Throttling handling errors",
"url": "https://www.phonovation.com/docs/essentials/integration-best-practices#throttling-handling-errors"
}
]
}{
"errorCode": "E500",
"description": "Something went wrong.",
"action": "Contact the support.",
"violations": [],
"resources": []
}Authorizations
This is the most secure authorization type and the one with the most flexibility.
API keys can be generated by calling the dedicated API method. Furthermore, API keys can have a limited scope and cover only some API methods. Lastly, they can be revoked at any time. This range of possibilities makes API keys well suited for separating the API access rights across multiple applications or use cases. Finally, the loss of an API key is easily manageable.
You can manage your API keys from GUI, or programmatically with dedicated API.
API key Authorization header example:
Authorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9
Path Parameters
Unique identifier of the AI assistant from which to retrieve context.
Body
AI Assistant retrieve context request with optional retrieval parameters.
User message to retrieve context for.
"How to send SMS?"
Number of context chunks to return. Overrides the assistant's default K value. Use this to get more or fewer context chunks.
5
Enables re-ranking for improved precision. When set, retrieves max(k, reRankK) chunks initially, then uses a cross-encoder to return the top K most relevant results.
10
Flag to indicate whether to use shared conversation history.
Session ID to maintain context across multiple queries.
"session-12345"
Response
Context retrieved successfully
List of retrieved context nodes.
Show child attributes
Show child attributes