Version: 0.1.9
QVeris exposes three core actions via REST API:
| Protocol action | API endpoint | Description |
|---|---|---|
| Discover | POST /search | Find capabilities with natural language (free) |
| Inspect | POST /tools/by-ids | Get capability details by ID |
| Call | POST /tools/execute | Invoke a capability (1–100 credits) |
All API requests require authentication via Bearer in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Get your API KEY from https://qveris.ai
https://qveris.ai/api/v1
All endpoints described in this document are relative to this base URL.
Search for capabilities based on natural language queries. This is the Discover action and is free.
POST /search
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer token for authentication |
| Content-Type | Yes | Must be application/json |
{
"query": "string",
"limit": 10,
"session_id": "string"
}
| Field | Type | Required | Description | Default | Range |
|---|---|---|---|---|---|
| query | string | Yes | Natural language search query | - | - |
| session_id | string | No | Same id corresponds to the same user session | - | - |
| limit | integer | No | Maximum number of results to return | 20 | 1-100 |
Status Code: 200 OK
{
"search_id": "string",
"total": 3,
"results": [
{
"tool_id": "openweathermap.weather.execute.v1",
"name": "Current Weather",
"description": "Get current weather data for any location",
"provider_name": "OpenWeatherMap",
"provider_description": "Global weather data provider",
"region": "global",
"params": [
{
"name": "city",
"type": "string",
"required": true,
"description": "City name"
},
{
"name": "units",
"type": "string",
"required": false,
"description": "Temperature units (metric/imperial)",
"enum": ["metric", "imperial", "standard"]
}
],
"examples": {
"sample_parameters": {
"city": "London",
"units": "metric"
}
},
"stats": {
"avg_execution_time_ms": 21.74,
"success_rate": 0.909
}
}
],
"elapsed_time_ms": 245.6
}
| Field | Type | Required | Description |
|---|---|---|---|
| query | string | No | Original search query |
| search_id | string | Yes | Id for this search. Used in following tool executions. |
| user_id | string | No | Original search user id |
| total | integer | Yes | Total number of results |
| Field | Type | Required | Description |
|---|---|---|---|
| tool_id | string | Yes | Unique identifier for the tool |
| name | string | Yes | Display name of the tool |
| description | string | Yes | Detailed description of tool functionality |
| provider_name | string | No | Name of the tool provider |
| provider_description | string | No | Description of the provider |
| region | string | No | Region of the tool. "global" for global tools, "|" separated whitelist (e.g. "US|CA") or blacklist (e.g. "-CN|RU") of country codes for regional tools |
| params | array | No | Array of parameter definitions |
| examples | object | No | Usage examples |
| stats | object | No | Historical execution performance statistics |
Get detailed descriptions of capabilities based on tool_id. This is the Inspect action.
POST /tools/by-ids
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer token for authentication |
| Content-Type | Yes | Must be application/json |
{
"tool_ids": ["string1", "string2", "..."],
"search_id": "string",
"session_id": "string"
}
| Field | Type | Required | Description | Default | Range |
|---|---|---|---|---|---|
| tool_ids | list of strings | Yes | Ids of tools to query | - | - |
| session_id | string | No | Same id corresponds to the same user session | - | - |
| search_id | string | No | Id for the search that returned the tool(s). | - | - |
Status Code: 200 OK
Same schema as the response of /search
Invoke a capability with specified parameters. This is the Call action and costs 1–100 credits per call, priced by data and task value.
POST /tools/execute?tool_id={tool_id}
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer token for authentication |
| Content-Type | Yes | Must be application/json |
| Parameter | Type | Required | Description |
|---|---|---|---|
| tool_id | string | Yes | Unique identifier of the tool to execute |
{
"search_id": "string",
"session_id": "string",
"parameters": {
"city": "London",
"units": "metric"
},
"max_response_size": 20480
}
| Field | Type | Required | Description |
|---|---|---|---|
| search_id | string | Yes | Id for the search that returned this tool. |
| session_id | string | No | Same id corresponds to the same user session. |
| parameters | object | Yes | Key-value pairs of tool parameters. Value can be object. |
| max_response_size | integer | No | If the tool generates data longer than max_response_size bytes, truncate to avoid big LLM token cost. -1 means no limit. Default is 20480 (20K). See details below. |
Status Code: 200 OK
{
"execution_id": "string",
"result": {
"data": {
"temperature": 15.5,
"humidity": 72,
"description": "partly cloudy",
"wind_speed": 12.5
}
},
"success": true,
"error_message": null,
"elapsed_time_ms": 210.72,
"cost": 5.0
}
| Field | Type | Required | Description |
|---|---|---|---|
| execution_id | string | Yes | Unique identifier for this execution |
| result | object | Yes | Tool execution result |
| success | boolean | Yes | Whether the execution was successful |
| error_message | string | No | Error message if execution failed |
| elapsed_time_ms | number | No | Execution time in milliseconds |
| cost | number | No | cost deducted from account |
If the call to the third-party service fails due to reasons such as insufficient balance, quota exceeded, or other issues, success will be false, and error_message will contain detailed information about the failure.
If the tool generates data longer than max_response_size bytes, result will have no data field but the fields below.
{
"result": {
"message": "Result content is too long (3210 bytes). You can reference the truncated content (200 bytes) and download the full content from the url provided.",
"full_content_file_url": "http://qveris-tool-results-cache-bj.oss-cn-beijing.aliyuncs.com/tool_result_cache%2F20260120%2Fpubmed_refined.search_articles.v1%2F2409f329c07949a295b5ab0b704883ca.json?OSSAccessKeyId=LTAI5tM3qNRZSgSrg1iSTALm&Expires=1768920673&Signature=ThkQxoa9ryYHn%2F6XbVloiegS5ss%3D",
"truncated_content": "{\"query\": \"evolution\", \"sort\": \"relevance\", \"total_results\": 890994, \"returned\": 10, \"articles\": [{\"pmid\": \"34099656\", \"title\": \"Towards an engineering theory of evolution.\", \"journal\": \"Nature commun",
"content_schema": {
"type": "object",
"properties": {
"query": {
"type": "string"
},
"sort": {
"type": "string"
},
"total_results": {
"type": "number"
},
"returned": {
"type": "number"
},
"articles": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pmid": {
"type": "string"
},
"title": {
"type": "string"
},
"journal": {
"type": "string"
}
}
}
}
}
}
}
}
| Field | Type | Required | Description |
|---|---|---|---|
| truncated_content | string | No | The initial max_response_size bytes of tool response. |
| full_content_file_url | string | No | The url to the file that contains the full content. Valid for 120min. |
| message | string | No | Message to LLM about the truncation. |
| content_schema | object | No | The JSON schema of the full content. |
Each tool parameter follows this schema:
{
"name": "string",
"type": "string|number|boolean|array|object",
"required": true,
"description": "string",
"enum": ["option1", "option2"]
}
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Parameter name |
| type | string | Yes | Data type (string, number, boolean, array, object) |
| required | boolean | Yes | Whether parameter is required |
| description | string | Yes | Parameter description |
| enum | array | No | Valid values (if applicable) |
{
"avg_execution_time_ms": 8564.43,
"success_rate": 0.748
}
| Field | Type | Required | Description |
|---|---|---|---|
| avg_execution_time_ms | number | No | Historical average execution time of the tool |
| success_rate | number | No | Historical success rate of the tool |
For LLM/agent tool use scenario, below are example code snippets to encapsulate QVeris AI REST API calls into tools that can be invoked by large language models:
export async function searchTools(
query: string,
sessionId: string,
limit: number = 20
): Promise<SearchResponse> {
const response = await api.post<SearchResponse>('/search', {
query,
limit,
session_id: sessionId,
})
return response.data
}
export async function executeTool(
toolId: string,
searchId: string,
sessionId: string,
parameters: object
): Promise<ToolExecutionResponse> {
const response = await api.post<ToolExecutionResponse>(
`/tools/execute?tool_id=${toolId}`,
{
search_id: searchId,
session_id: sessionId,
parameters,
}
)
return response.data
}
export const qverisApi = {
searchTools,
executeTool,
}
// Execute tool function
async function executeTool(name: string, args: Record<string, unknown>) {
console.log(`[Tool] Executing ${name} with:`, args)
if (name === 'search_tools') {
const result = await qverisApi.searchTools(
args.query as string,
args.session_id as string,
20
)
return result
} else if (name === 'execute_tool') {
let parsedParams: Record<string, unknown>
try {
parsedParams = JSON.parse(args.params_to_tool as string) as
Record<string, unknown>
} catch (parseError) {
throw new Error(
`Invalid JSON in params_to_tool: ${
parseError instanceof Error
? parseError.message
: 'Unknown parse error'
}`
)
}
const result = await qverisApi.executeTool(
args.tool_id as string,
args.search_id as string,
args.session_id as string,
parsedParams
)
return result
}
throw new Error(`Unknown tool: ${name}`)
}
Below are example declarations for the encapsulated search and execute tools. Just add them to chat completion tool list.
{
type: 'function',
function: {
name: 'search_tools',
description:
'Search for available tools. Returns relevant tools that can help accomplish tasks.',
parameters: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'The search query describing the general capability of the tool. Not specific params you want to pass to the tool later.',
},
session_id: {
type: 'string',
description: 'The uuid of the user session. Should be changed only if new session.'
},
},
required: ['query'],
},
},
},
{
type: 'function',
function: {
name: 'execute_tool',
description:
'Execute a specific remote tool with provided parameters. The tool_id must come from a previous search_tools call; The params_to_tool is where the params can be passed.',
parameters: {
type: 'object',
properties: {
tool_id: {
type: 'string',
description: 'The ID of the remote tool to execute (from search results)',
},
search_id: {
type: 'string',
description: 'The search_id in the response of the search_tools call that returned the information of this remote tool',
},
session_id: {
type: 'string',
description: 'The uuid of the user session. Should be changed only if new session.'
},
params_to_tool: {
type: 'string',
description: 'An JSON stringified dictionary of parameters to pass to the remote tool, where keys are param names and values can be of any type, used to pass multiple arguments to the tool. For example: { "param1": "value1", "param2": 42, "param3": { "nestedKey": "nestedValue" } }',
},
max_response_size: {
type: 'integer',
description: 'If tool generates data longer than max_response_size (in bytes), do not return the full data to avoid big LLM token cost. Default value is 20480.',
},
},
required: ['tool_id', 'search_id', 'params_to_tool'],
},
},
}
You can then use below system prompt and start testing! Have fun exploring!
{
role: 'system',
content: 'You are a helpful assistant that can dynamically discover and call capabilities to help the user. First think about what kind of capabilities might be useful to accomplish the user\'s task. Then use the search_tools tool with a query describing the capability, not the specific parameters you will pass later. Then call suitable capabilities using the execute_tool tool, passing parameters through params_to_tool. If a capability has success_rate and avg_execution_time (in seconds), consider them when selecting which to call. You can reference the examples given for each capability. You can make multiple tool calls in a single response.',
}