---
title: "Call a capability"
method: POST
path: "/tools/execute"
tags: ["Tool Execution"]
---

# Call a capability

`POST /tools/execute`

## Request

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

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.

## Query parameters

- `tool_id` string, nullable: Tool ID (optional if provided in request body)

## Headers

- `X-QVeris-Cache-Mode` string, nullable: 缓存策略：default（默认）或 bypass（跳过provider缓存）
- `Idempotency-Key` string, nullable: Caller-generated key used to reconcile uncertain execution outcomes

## Request body

- PublicExecuteToolRequest
  - `tool_id` string: Capability id. Optional when supplied as the `tool_id` query parameter.
  - `search_id` string: Search id that returned the selected capability.
  - `session_id` string: Optional tracking and pricing-context identifier. If omitted, the service may use the execution id.
  - `sub_user_id` string: Optional sub-user identity used consistently for provider OAuth and execution.
  - `model` string: Model that selected the capability or generated its parameters.
  - `parameters` object, required: Capability-specific parameters validated by the selected tool schema.
  - `max_response_size` union: 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.
    - unknown
    - integer
  - `respond_with` 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.

## Response `200`

Successful Response

- PublicExecuteToolResponse
  - `execution_id` string, required
  - `result` union, required: Capability result. Projected responses use the documented object shape; default/full responses may contain any JSON value.
    - PublicExecuteResult
      - `data` unknown
      - `message` string
      - `truncated_content` string: UTF-8-safe preview used by automatic, oversized fields, or summary fallback delivery; never present on a successful explicit full response.
      - `full_content_file_url` string, uri: Temporary signed URL used by automatic overflow, fields overflow, or summary delivery; never substitutes for data on a successful explicit full response.
      - `content_schema` object
      - `respond_with` string: Echo of the requested projection mode when `respond_with` was set (e.g. `summary`).
      - `summary` object: Size and shape statistics returned by the `summary` projection.
        - `size_bytes` integer
        - `row_count` integer
        - `fields` string[]
    - unknown[]
      - unknown
    - string
    - number
    - boolean
  - `success` boolean, required
  - `error_code` string: Stable machine-readable failure code, including `response_too_large` when explicit full exceeds the platform hard safety limit.
  - `error_message` string, nullable
  - `execution_time` number
  - `elapsed_time_ms` number
  - `billing` PublicCompactBillingStatement
    - `summary` string
    - `list_amount_credits` number
    - `final_amount_credits` number
    - `recorded_amount_credits` number
    - `settlement_state` string
    - `settlement_status` string
    - `execution_intent_id` string, nullable
    - `charge_event_id` string, nullable
  - `cost` number
  - `remaining_credits` number, nullable
  - `details` ValidationError[]: Field-level validation failures. Present when a request parameter or projection such as `respond_with` is invalid.
    - `loc` union[], required
      - union
        - string
        - integer
    - `msg` string, required
    - `type` string, required
    - `input` unknown
    - `ctx` object

## Other responses

- `401`: Unauthorized
- `402`: Insufficient credits
- `409`: Idempotency key already exists or conflicts with immutable input
- `413`: Explicit full response exceeds the platform safety limit
- `422`: Validation Error
- `429`: Too Many Requests
- `502`: Upstream result delivery violated the public contract

---

[API](https://skmtc.dev/qveris/apis/qveris-public-rest-api.md) · [All operations](https://skmtc.dev/qveris/apis/qveris-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/qveris/apis/qveris-public-rest-api/revisions/7b78aeef092a?raw)