Call a capability

POST /tools/execute

Execute a selected capability. Call may consume credits according to the capability billing_rule; the response can include a pre-settlement billing statement, while final settlement is available through usage audit and credits ledger endpoints.

REST API overview · OpenAPI JSON · OpenAPI YAML

Contract

Stability	Authentication	Cost	Operation ID
Published	Bearer API key	Depends on the selected capability billing rule	`execute_api_v1_tools_execute_post`

Parameters

Name	Location	Required	Type	Description
`tool_id`	query	No	`string \| null`	Tool ID (optional if provided in request body)
`X-QVeris-Cache-Mode`	header	No	`string \| null`	—
`Idempotency-Key`	header	No	`string \| null`	Caller-generated key used to reconcile uncertain execution outcomes

Request body

Schema: PublicExecuteToolRequest

Name	Required	Type	Description
`tool_id`	No	`string`	Capability id. Optional when supplied as the `tool_id` query parameter.
`search_id`	No	`string`	Search id that returned the selected capability.
`session_id`	No	`string`	Optional tracking and pricing-context identifier. If omitted, the service may use the execution id.
`sub_user_id`	No	`string`	Optional sub-user identity used consistently for provider OAuth and execution.
`model`	No	`string`	Model that selected the capability or generated its parameters.
`parameters`	Yes	`object`	Capability-specific parameters validated by the selected tool schema.
`max_response_size`	No	`object`	Automatic inline-delivery limit, measured as the UTF-8 byte length of serialized `result.data`. The default is 20480 when omitted; use -1 for unlimited inline delivery. An explicit `respond_with: full` takes precedence over any finite value. Summary mode may preserve lossless data or a complete overflow fallback.
`respond_with`	No	`string`	Result delivery mode. When omitted, the compatibility mode uses `max_response_size` (default 20480) and may return a truncated preview plus `full_content_file_url`. Explicit `full` forces the complete `result.data` inline and takes precedence over a finite `max_response_size`; if the platform hard safety limit is exceeded, the call fails with `error_code: response_too_large` instead of silently degrading. `fields:<JSONPath,...>` returns only the selected fields — JSONPath expressions are rooted at `result.data`, comma-separated, and at least one non-empty expression is required. `summary` normally returns statistics with optional schema and download URL. It preserves lossless `data` or a `truncated_content` plus `full_content_file_url` fallback when available. Check success and field availability; the mode alone does not guarantee statistics or a URL.

Runnable examples

bash

curl --request POST \
  --url "https://qveris.ai/api/v1/tools/execute" \
  --header "Authorization: Bearer $QVERIS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m",
  "model": "deepseek-v4-pro",
  "parameters": {
    "q": "London"
  },
  "max_response_size": 20480
}'

typescript

const response = await fetch("https://qveris.ai/api/v1/tools/execute", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.QVERIS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m",
  "model": "deepseek-v4-pro",
  "parameters": {
    "q": "London"
  },
  "max_response_size": 20480
}),
})

if (!response.ok) throw new Error(`QVeris request failed: ${response.status}`)
console.log(await response.json())

python

import json
import os
import requests

response = requests.request(
    "POST",
    "https://qveris.ai/api/v1/tools/execute",
    headers={"Authorization": f"Bearer {os.environ['QVERIS_API_KEY']}"},
    json=json.loads(r'''{
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m",
  "model": "deepseek-v4-pro",
  "parameters": {
    "q": "London"
  },
  "max_response_size": 20480
}'''),
    timeout=30,
)
response.raise_for_status()
print(response.json())

Responses

Status	Meaning	Schema
`200`	Successful Response	`PublicExecuteToolResponse`
`401`	Unauthorized	`PublicApiError`
`402`	Insufficient credits	`PublicExecuteToolResponse`
`409`	Idempotency key already exists, conflicts, or cannot be honored by the selected settlement path	`unknown`
`413`	Explicit full response exceeds the platform safety limit	`PublicExecuteToolResponse`
`422`	Validation Error	`PublicExecuteToolResponse`
`429`	Too Many Requests	`PublicApiError`
`502`	Upstream result delivery violated the public contract	`PublicExecuteToolResponse`

Successful response example

json

{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {
      "temperature": 15.5,
      "description": "partly cloudy"
    }
  },
  "success": true,
  "error_message": null,
  "execution_time": 0.211,
  "billing": {
    "summary": "5 credits per successful request",
    "list_amount_credits": 5
  },
  "cost": 5,
  "remaining_credits": 990
}

Exact contract

Stable JSON: OpenAPI JSON
Stable YAML: OpenAPI YAML
Versioned JSON: OpenAPI v1 JSON
Versioned YAML: OpenAPI v1 YAML

POST Discover capabilities · POST Inspect capabilities · POST Probe a capability

Call a capability

POST /tools/execute

REST API overview · OpenAPI JSON · OpenAPI YAML

Contract

Stability	Authentication	Cost	Operation ID
Published	Bearer API key	Depends on the selected capability billing rule	`execute_api_v1_tools_execute_post`

Parameters

Name	Location	Required	Type	Description
`tool_id`	query	No	`string \| null`	Tool ID (optional if provided in request body)
`X-QVeris-Cache-Mode`	header	No	`string \| null`	—
`Idempotency-Key`	header	No	`string \| null`	Caller-generated key used to reconcile uncertain execution outcomes

Request body

Schema: PublicExecuteToolRequest

Name	Required	Type	Description
`tool_id`	No	`string`	Capability id. Optional when supplied as the `tool_id` query parameter.
`search_id`	No	`string`	Search id that returned the selected capability.
`session_id`	No	`string`	Optional tracking and pricing-context identifier. If omitted, the service may use the execution id.
`sub_user_id`	No	`string`	Optional sub-user identity used consistently for provider OAuth and execution.
`model`	No	`string`	Model that selected the capability or generated its parameters.
`parameters`	Yes	`object`	Capability-specific parameters validated by the selected tool schema.
`max_response_size`	No	`object`	Automatic inline-delivery limit, measured as the UTF-8 byte length of serialized `result.data`. The default is 20480 when omitted; use -1 for unlimited inline delivery. An explicit `respond_with: full` takes precedence over any finite value. Summary mode may preserve lossless data or a complete overflow fallback.
`respond_with`	No	`string`	Result delivery mode. When omitted, the compatibility mode uses `max_response_size` (default 20480) and may return a truncated preview plus `full_content_file_url`. Explicit `full` forces the complete `result.data` inline and takes precedence over a finite `max_response_size`; if the platform hard safety limit is exceeded, the call fails with `error_code: response_too_large` instead of silently degrading. `fields:<JSONPath,...>` returns only the selected fields — JSONPath expressions are rooted at `result.data`, comma-separated, and at least one non-empty expression is required. `summary` normally returns statistics with optional schema and download URL. It preserves lossless `data` or a `truncated_content` plus `full_content_file_url` fallback when available. Check success and field availability; the mode alone does not guarantee statistics or a URL.

Runnable examples

bash

curl --request POST \
  --url "https://qveris.ai/api/v1/tools/execute" \
  --header "Authorization: Bearer $QVERIS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m",
  "model": "deepseek-v4-pro",
  "parameters": {
    "q": "London"
  },
  "max_response_size": 20480
}'

typescript

const response = await fetch("https://qveris.ai/api/v1/tools/execute", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.QVERIS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m",
  "model": "deepseek-v4-pro",
  "parameters": {
    "q": "London"
  },
  "max_response_size": 20480
}),
})

if (!response.ok) throw new Error(`QVeris request failed: ${response.status}`)
console.log(await response.json())

python

import json
import os
import requests

response = requests.request(
    "POST",
    "https://qveris.ai/api/v1/tools/execute",
    headers={"Authorization": f"Bearer {os.environ['QVERIS_API_KEY']}"},
    json=json.loads(r'''{
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m",
  "model": "deepseek-v4-pro",
  "parameters": {
    "q": "London"
  },
  "max_response_size": 20480
}'''),
    timeout=30,
)
response.raise_for_status()
print(response.json())

Responses

Status	Meaning	Schema
`200`	Successful Response	`PublicExecuteToolResponse`
`401`	Unauthorized	`PublicApiError`
`402`	Insufficient credits	`PublicExecuteToolResponse`
`409`	Idempotency key already exists, conflicts, or cannot be honored by the selected settlement path	`unknown`
`413`	Explicit full response exceeds the platform safety limit	`PublicExecuteToolResponse`
`422`	Validation Error	`PublicExecuteToolResponse`
`429`	Too Many Requests	`PublicApiError`
`502`	Upstream result delivery violated the public contract	`PublicExecuteToolResponse`

Successful response example

json

{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {
      "temperature": 15.5,
      "description": "partly cloudy"
    }
  },
  "success": true,
  "error_message": null,
  "execution_time": 0.211,
  "billing": {
    "summary": "5 credits per successful request",
    "list_amount_credits": 5
  },
  "cost": 5,
  "remaining_credits": 990
}

Exact contract

Stable JSON: OpenAPI JSON
Stable YAML: OpenAPI YAML
Versioned JSON: OpenAPI v1 JSON
Versioned YAML: OpenAPI v1 YAML

POST Discover capabilities · POST Inspect capabilities · POST Probe a capability

Call a capability

Contract

Parameters

Request body

Runnable examples

Responses

Successful response example

Exact contract

Related operations

Call a capability

Contract

Parameters

Request body

Runnable examples

Responses

Successful response example

Exact contract

Related operations