Qveris API Documentation v0.1.7

Last Updated: November 2025

Authentication

All API requests require authentication via a Bearer token in the Authorization header. Contact Qveris to obtain your API token.

Authorization Header

Authorization: Bearer YOUR_API_TOKEN

Base URL

All endpoints described in this document are relative to the following base URL:

https://qveris.ai/api/v1

API Endpoints

1. Search Tools

Search for tools based on natural language queries.

Endpoint

POST /search

Request Headers

Request Body

{
  "query": "string",
  "limit": 10,
  "session_id": "string"
}

Request Parameters

Response (200 OK)

{
  "query": "weather forecast API",
  "search_id": "string",
  "total": 3,
  "results": [
    {
      "tool_id": "openweathermap_current_weather",
      "name": "Current Weather",
      "description": "Get current weather data for any location",
      "provider_name": "OpenWeatherMap",
      "provider_description": "Global weather data provider",
      "region": "global",
      "avg_latency_ms": 100,
      "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": {
    "search_time_ms": 245.6
  }
}

Response Fields

Tool Information Fields

2. Execute Tool

Execute a tool with specified parameters.

Endpoint

POST /tools/execute?tool_id={tool_id}

Request Headers

URL Parameters

Request Body

{
  "search_id": "string",
  "session_id": "string",
  "parameters": {
    "city": "London",
    "units": "metric"
  },
  "max_data_size": 20480
}

Request Parameters

Response (200 OK)

{
  "execution_id": "string",
  "tool_id": "openweathermap_current_weather",
  "parameters": {
    "city": "London",
    "units": "metric"
  },
  "result": {
    "data": {
      "temperature": 15.5,
      "humidity": 72,
      "description": "partly cloudy",
      "wind_speed": 12.5
    }
  },
  "success": true,
  "error_message": null,
  "execution_time": 0.847,
  "created_at": "2025-01-15T10:30:45Z"
}

Response Fields

Result Fields for Long Tool Response

If the tool generates data longer than max_data_size bytes, the result object will not contain a data field, but will instead contain the fields below:

{
  "result": {
    "message": "Result content is too long (199483 bytes). You can reference the truncated content (100 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%2F20251201%2Fbinance.klines.retrieve.v1%2F485c19a324b24c319c6f4de6cc0eae30.json?OSSAccessKeyId=LTAI5tM3qNRZSgSrg1iSTALm&Expires=1764568180&Signature=ze1DXz6RnMOjMVz2wf%2BODxjJ%2Fc8%3D",
    "truncated_content": "[[1678233600000, \"22198.56000000\", \"22287.00000000\", \"21580.00000000\", \"21705.44000000\", \"301460.572\""
  }
}

Data Models

Tool Parameter Schema

Each tool parameter follows this schema:

{
  "name": "string",
  "type": "string|number|boolean|array|object",
  "required": true,
  "description": "string",
  "enum": ["option1", "option2"]
}

Search Statistics Schema

{
  "search_time_ms": 245.6
}

LLM / Agent Use Examples

The following TypeScript examples show how to encapsulate Qveris REST API calls into tools that can be invoked by large language models.

Client Functions

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 searchEngineApi = {
  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 searchEngineApi.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 searchEngineApi.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}`);
}

Tool Declarations for Chat Completion

Below are example tool declarations for search_tools and execute_tool. Add them to your 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:
            "A JSON stringified dictionary of parameters to pass to the remote tool, where keys are param names and values can be of any type. For example: { \"param1\": \"value1\", \"param2\": 42, \"param3\": { \"nestedKey\": \"nestedValue\" } }"
        },
        max_data_size: {
          type: "integer",
          description:
            "If tool generates data longer than max_data_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"]
    }
  }
}

System Prompt Example

{
  role: "system",
  content:
    "You are a helpful assistant that can dynamically search and execute tools to help the user. First think about what kind of tools might be useful to accomplish the user's task. Then use the search_tools tool with query describing the capability of the tool, not what params you want to pass to the tool later. Then call a suitable searched tool using the execute_tool tool, passing parameters to the searched tool through params_to_tool. You could reference the examples given if any for each tool. You may call make multiple tool calls in a single response."
}