Tool Execution

Call a capability

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.

post/tools/execute

Request

  • Base URL: https://qveris.ai/api/v1
  • URL: https://qveris.ai/api/v1/tools/execute
  • Auth: HTTP bearer

Query parameters

tool_idstring nullable

Tool ID (optional if provided in request body)

Headers

X-QVeris-Cache-Modestring nullable

缓存策略：default（默认）或 bypass（跳过provider缓存）

Idempotency-Keystring nullable

Caller-generated key used to reconcile uncertain execution outcomes

Request body

tool_idstring

Capability id. Optional when supplied as the tool_id query parameter.

search_idstring

Search id that returned the selected capability.

session_idstring

Optional tracking and pricing-context identifier. If omitted, the service may use the execution id.

sub_user_idstring

Optional sub-user identity used consistently for provider OAuth and execution.

modelstring

Model that selected the capability or generated its parameters.

parametersobject required

Capability-specific parameters validated by the selected tool schema.

respond_withstring

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.

Response

Successful Response

execution_idstring required
successboolean required
error_codestring

Stable machine-readable failure code, including response_too_large when explicit full exceeds the platform hard safety limit.

error_messagestring nullable
execution_timenumber
elapsed_time_msnumber
costnumber
remaining_creditsnumber nullable

Changes

No recorded changes to this operation across all 1 revision of this API.