|
<< Click to Display Table of Contents >> Raynet One Data Hub > 2025.4 > Administration and User Guide > Advanced Topics > Data API Fetching Data via AI |
The AI-powered data fetching endpoint allows you to retrieve data from the database by sending natural language requests to the AI service. This feature eliminates the need for complex SQL queries and enables intuitive data access through conversational prompts. AI will return data in small batches with information on how to get next batch of data or last batch of data.
Before using this endpoint, ensure that:
•You have created an API key with AI endpoint fetching permission enabled (see Authentication and Authorization).
•Your user account has at least Data Administrator privileges.
•The AI service is properly configured in your Raynet One Data Hub installation.
HTTP Method: POST
URL: http://<hostname>:<port>/v1/ResultDatabase/fetchViaAi
Header Name |
Required |
Description |
|---|---|---|
ApiKey |
Yes |
The API key with AI endpoint fetching permission enabled. |
The request body must be in JSON format and contain a messages array with your natural language request.
Content-Type: application/json
Example Request Body:
{
"messages": [
{
"role": "user",
"text": "Show me all devices running Windows 11"
}
]
}
The endpoint returns a JSON response with the following structure:
•role: Always "AI" for responses from the AI service.
•text: A simple response answer that summarises the reply in natural language.
•function: The function type, typically "Answer".
•fetchedData: The actual query results for the current page as escaped JSON data.
•pagination: (May be omitted if all results can appear on one page)
ocurrent_page: Current page number.
orequested_page_size: Number of records per page (25)
oactual_records_returned: Number of records that had been returnt (depending on the amount of data, this amount may be lower than 25)
ototal_records: Total number of result data rows for this query
ototal_pages: Total number of pages available
opaging: General information and instructions how to use the pagination functionality of this endpoint in escaped JSON format
▪instruction: A short explanation how to use the pagination with this endpoint, always reading “Request the following queries to fetch the page of your choice:"
▪first_page: Includes the original user query and the paging addition “- page 1” to fetch the first page
▪previous_page: Includes the original user query and the paging addition “- page Y” to fetch the previous page (may be omitted if no previous page exists)
▪next_page: Includes the original user query and the paging addition “- page X” to fetch the next page (may be omitted if no next page exists)
▪last_page: Includes the original user query and the paging addition “- page Z” to fetch the last page
Thus an example JSON would look like this:
{
"role": "AI",
"text": "Found 52 devices running Windows 11 (showing page 1 of 3)",
"function": "Answer",
"fetchedData": "[{\"DeviceId\":\"12345\",\"DeviceName\":\"WKS001\"}, {\"DeviceId\":\"12346\",\"DeviceName\":\"WKS002\"}, (...)"
"pagination":
{\"current_page\":3,\"requested_page_size\":25,\"actual_records_returned\":25,\"total_records\":52,\"total_pages\":3,\"paging\":{\"instruction\":\"Request the following queries to fetch the page of your choice:\",\"first_page\":\"Show me all devices running Windows 11 - page 1\",\"next_page\":\"Show me all devices running Windows 11 - page 2\",\"last_page\":\"Show me all devices running Windows 11 - page 3\"} }
}
The following examples demonstrate how to fetch device information using natural language requests with pagination.
Request:
POST http://localhost:8080/v1/ResultDatabase/fetchViaAi
ApiKey: your-api-key-here
Content-Type: application/json
{
"messages": [
{
"role": "user",
"text": "List devices with their operating system"
}
]
}
This request returns the first page (25 records) of matching results.
Request:
POST http://localhost:8080/v1/ResultDatabase/fetchViaAi
ApiKey: your-api-key-here
Content-Type: application/json
{
"messages": [
{
"role": "user",
"text": "List devices with their operating system - page 2"
}
]
}
This request returns the second page (records 26-50) of the same query.
•Be specific: Provide clear and specific requests to receive accurate results.
•Use pagination: Check the totalPages field in the response to determine if additional pages are available. Iterate through pages using the page parameter.
•Parse the response: The data field contains escaped JSON that must be parsed before use. The text field provides a human-readable summary.
•Handle pagination metadata: Use the totalRecords, page, pageSize, and totalPages fields to implement efficient pagination in your application.
•Handle errors: Implement proper error handling for cases where the AI cannot interpret the request or data is unavailable.
•The endpoint requires an API key with AI endpoint fetching permission enabled.
•Results are paginated with a fixed page size of 25 records per page.
•To retrieve all results, you must make multiple requests iterating through pages.
•The AI service must be properly configured and accessible.
•Authentication and Authorization