QVeris REST API 文档

版本：2026-07-23.2

公开 REST API 暴露核心 Agent 路径：

协议动作	Endpoint	成本行为
Discover	`POST /search`	免费；返回排序后的能力和可选成本信号
Inspect	`POST /tools/by-ids`	免费；返回完整 schema、示例、质量信号和成本信号
Call	`POST /tools/execute`	可能按所选能力的 `billing_rule` 消耗积分
调用历史	`GET /auth/usage/history/v2`	最终请求状态和扣费结果
积分账本	`GET /auth/credits/ledger`	最终积分余额变动

请将示例中的 srch_...、exec_...、led_... 替换为你自己 API 响应中返回的 ID。

Base URL#

https://qveris.ai/api/v1

身份认证#

在 Authorization 请求头中发送 API key：

Authorization: Bearer YOUR_API_KEY

成本与 session 合同#

Discover 和 Inspect 免费。它们可能返回 expected_cost、旧字段 cost 或 billing_rule，让客户端在花费积分前估算 Call 成本。

默认/full Call 响应可能返回 billing、cost 等紧凑预结算字段。投影响应（summary 和 fields:*）会刻意省略计费内部详情，以保持结构精简。最终结算由调用历史和积分账本报告；客服、对账和用户账单历史应以这些端点为准。

session_id 可选。建议每个用户任务或会话使用一个稳定值，用于追踪、分析和计费上下文。它不是缓存合同，也不承诺缓存复用或 session_cache_hit。

Search -> Execute 集成契约#

请把 Discover 和 Inspect 视为 Call 的唯一可信来源。Call 请求应从用户或智能体选中的那条能力结果构造。

推荐契约：

为一次用户任务或会话生成稳定的 session_id。
用能力级查询调用 POST /search。
保存返回的 search_id。
从 results 中选择一个 tool_id。
使用同一条结果里的 params、one_of_required 和 examples.sample_parameters 构造 parameters。
调用 POST /tools/execute，传入 tool_id、parameters、search_id、session_id；如果是智能体客户端，也传入 model。
保存 execution_id，用于审计和客服排查。

不要只根据工具名称猜参数。不要复用其他工具、其他 provider 或旧缓存 schema 的参数。如果客户端缓存工具元数据，请使用较短 TTL，或在新搜索返回该工具时刷新 schema。

examples.sample_parameters 只是起步示例，不是完整合同。执行前应使用当前 params schema 校验最终 parameters。

对于 LLM/智能体集成，建议在 Call 元数据中传入 model，例如 "model": "gpt-4.1" 或 "model": "deepseek-v4-pro"。这有助于把工具选择、参数生成质量和具体模型关联起来。

计费透明化合同#

QVeris 将调用前估价、执行结果、预结算账单和最终账本结算分开表达。

阶段	读取位置	重要字段	使用方式
调用前估价	Discover / Inspect	`expected_cost`、`billing_rule`	执行能力前向用户展示计价规则。
执行结果	Call	`success`、`error_message`	解释 provider/result 是否可用。不要只用 `success` 判断最终是否扣费。
Provider/result 结果	调用审计	`execution_outcome`、`reason_code`、`billable_success`	不扩展 Call 响应也能查看结构化 provider 和结果分类。
预结算账单	默认/full Call 和调用审计	`billing`、`pre_settlement_bill`、`requested_amount_credits`	展示最终结算、折扣或不扣费规则应用前的请求金额。
最终请求状态	调用审计	`charge_outcome`、`reason_code`、`settlement_result`、`actual_amount_credits`	判断请求最终是否扣费以及原因。
最终余额变动	Credits 账本	`amount_credits`、`balance_before`、`balance_after`、`execution_id`	用于账户余额对账和客服排查。

推荐对账流程：

使用 Discover 或 Inspect 展示 billing_rule / expected_cost。
调用能力并保存 execution_id 和旧字段 cost；默认/full 客户端也可保存紧凑的 billing。
查询 /auth/usage/history/v2?execution_id=...，读取 charge_outcome、reason_code、actual_amount_credits 和 credits_ledger_entry_id。
查询 /auth/credits/ledger 或关联账本行，验证最终带符号的余额变动。

客户端建议：

REST 客户端应保留 Call 响应中的 execution_id 和 cost。结构化结果和最终计费详情应从调用审计读取。
CLI、MCP 和 SDK 客户端应保持投影 Call 响应精简，只在需要时获取审计详情。
自动化逻辑优先使用审计中的 charge_outcome、reason_code 等稳定机器字段；面向用户的展示可使用 billing_summary 和 error_message。
cost 为兼容旧客户端保留。新的计费 UI 应以调用审计和 Credits 账本作为最终结算依据。

限流#

已认证请求按账号共享额度，同一账号下的所有 API Key 计入同一限流桶。网站匿名流量按客户端 IP 限流。

动作	默认额度
Discover (`POST /search`)	120 次/分钟
Inspect (`POST /tools/by-ids`)	120 次/分钟
Call (`POST /tools/execute`)	200 次/分钟

限流响应包含：

Header	说明
`X-RateLimit-Limit`	当前窗口最大请求数
`X-RateLimit-Remaining`	当前窗口剩余请求数
`X-RateLimit-Reset`	当前窗口重置的 Unix 秒级时间戳
`Retry-After`	建议重试等待秒数；`429` 一定返回

1. 发现能力#

POST /search

请求#

为保证后续步骤可以稳定复现，本示例直接使用工具 ID 查询。实际进行动态发现时，请输入自然语言能力描述，再从返回结果中选择工具。

{
  "query": "openweathermap.weather.execute.v1",
  "limit": 10,
  "session_id": "sess_7Q9m"
}

字段	类型	必填	说明
`query`	string	是	自然语言能力查询；需要确定性查找时也可传入完整工具 ID
`limit`	integer	否	最大结果数；默认 `20`，范围 `1-100`
`session_id`	string	否	当前用户任务的追踪和计费上下文 ID
`view`	string	否	响应投影：`routing` 返回精简路由卡（`tool_id`、`capability`、`cost_class`、`reliability`、`as_of_support`）；`full` 或缺省返回与既有版本一致的完整结构
`lang`	string	否	响应语言，`zh` 或 `en`；缺省按 `Accept-Language` 协商

成功响应#

{
  "query": "openweathermap.weather.execute.v1",
  "search_id": "srch_01HZX9QK7J3M9T",
  "total": 1,
  "results": [
    {
      "tool_id": "openweathermap.weather.execute.v1",
      "name": "当前天气",
      "description": "获取某城市的当前天气数据。",
      "provider_name": "OpenWeatherMap",
      "params": [
        {
          "name": "q",
          "type": "string",
          "required": true,
          "description": "天气服务接受的地点查询。"
        }
      ],
      "expected_cost": "每次成功请求 5 积分",
      "billing_rule": {
        "unit": "request",
        "amount_credits": 5
      },
      "stats": {
        "avg_execution_time_ms": 210.7,
        "success_rate": 0.982
      }
    }
  ],
  "elapsed_time_ms": 245.6,
  "remaining_credits": 995
}

响应字段#

字段	类型	说明
`query`	string	原始搜索查询（如果可用）。
`search_id`	string	Discover 返回的搜索 id。后续 Inspect 或 Call 可复用该 id。
`total`	integer	返回的能力结果数量。
`results`	array	排序后的能力结果。
`elapsed_time_ms`	number	搜索耗时，单位毫秒。
`remaining_credits`	number/null	可用时返回账户剩余积分。
`error_message`	string/null	业务失败时的错误说明。

能力结果字段#

字段	类型	说明
`tool_id`	string	Inspect 和 Call 使用的唯一能力 id。
`name`	string	面向用户的能力名称。
`description`	string	能力说明。
`provider_name`	string	能力提供方名称。
`params`	array	参数定义；每一项可包含 `name`、`type`、`required`、`description`、`enum`。
`examples`	object	可用时返回示例参数。
`expected_cost`	string	可用时返回面向用户的调用前成本提示。
`billing_rule`	object	可用时返回结构化成本提示。
`stats.avg_execution_time_ms`	number	历史平均执行耗时，单位毫秒。
`stats.success_rate`	number	历史成功率，范围 `0` 到 `1`。

错误响应#

API key 无效：

{
  "query": "openweathermap.weather.execute.v1",
  "search_id": "srch_failed",
  "total": 0,
  "results": []
}

积分不足：

{
  "query": "openweathermap.weather.execute.v1",
  "search_id": "srch_failed",
  "total": 0,
  "results": [],
  "error_message": "Insufficient credits",
  "remaining_credits": 0
}

触发限流：

{
  "status": "failure",
  "status_code": 429,
  "message": "Rate limit exceeded. Please try again later."
}

2. 按 id 检查能力#

POST /tools/by-ids

Inspect 返回与 Discover 相同的能力结果结构，通常包含更完整的参数和示例。

请求#

{
  "tool_ids": ["openweathermap.weather.execute.v1"],
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m"
}

字段	类型	必填	说明
`tool_ids`	string[]	是	Discover 返回的能力 id
`search_id`	string	否	返回该能力的 search id
`session_id`	string	否	当前用户任务的追踪和计费上下文 ID
`view`	string	否	响应投影：`lean` 精简每个能力的元数据以节省模型上下文；`full` 或缺省返回完整结构

成功响应#

{
  "search_id": "srch_01HZX9QK7J3M9T",
  "total": 1,
  "results": [
    {
      "tool_id": "openweathermap.weather.execute.v1",
      "name": "当前天气",
      "description": "获取某城市的当前天气数据。",
      "provider_name": "OpenWeatherMap",
      "params": [
        {
          "name": "q",
          "type": "string",
          "required": true,
          "description": "天气服务接受的地点查询。"
        }
      ],
      "examples": {
        "sample_parameters": {
          "q": "北京"
        }
      },
      "expected_cost": "每次成功请求 5 积分",
      "billing_rule": {
        "unit": "request",
        "amount_credits": 5
      },
      "stats": {
        "avg_execution_time_ms": 210.7,
        "success_rate": 0.982
      }
    }
  ],
  "remaining_credits": 995
}

响应字段#

字段	类型	说明
`search_id`	string	可用时返回与本次检查关联的 search id。
`total`	integer	返回的能力结果数量。
`results`	array	能力结果；每一项使用与 Discover 相同的能力结果字段。
`elapsed_time_ms`	number	可用时返回 Inspect 耗时，单位毫秒。
`remaining_credits`	number/null	可用时返回账户剩余积分。
`error_message`	string/null	业务失败时的错误说明。

错误响应#

超时：

{
  "error": "Request timeout",
  "remaining_credits": 995
}

代理异常：

{
  "error": "Tools by-ids failed: upstream service unavailable",
  "remaining_credits": 995
}

3. 调用能力#

POST /tools/execute?tool_id={tool_id}

tool_id 可以放在 query 参数或 JSON body 中。推荐使用 query 参数，便于日志追踪。

请求#

{
  "search_id": "srch_01HZX9QK7J3M9T",
  "session_id": "sess_7Q9m",
  "model": "gpt-4o",
  "parameters": {
    "q": "北京"
  },
  "max_response_size": 20480
}

字段	类型	必填	说明
`tool_id`	string	整体必填	要执行的工具唯一标识符；可作为 query 参数或 JSON body 字段提供。
`search_id`	string	推荐	返回所选工具的 search id
`session_id`	string	否	追踪和计费上下文 ID；省略时服务可能使用 execution id
`model`	string	智能体推荐	选择工具或生成参数的模型，例如 `gpt-4.1`、`deepseek-v4-pro` 或 `claude-sonnet-4`
`parameters`	object	是	Inspect 返回的能力专属参数
`max_response_size`	integer	否	长响应截断阈值；默认 `20480`，`-1` 表示不截断
`respond_with`	string	否	服务端结果投影：`full`（默认，与既有版本一致）、`fields:<JSONPath,...>`（以 `result.data` 为根的逗号分隔 JSONPath 表达式，至少一个非空表达式）或 `summary`（返回 schema、大小/行数统计与完整内容的 `full_content_file_url`）

工具参数或投影无效时返回 HTTP 422，并通过 details 给出字段级错误；鉴权失败返回统一 API 错误对象，不再伪装成成功 Call 或空 Search 结果。

只从选中的工具构造 parameters：

使用选中结果的 params 字段作为必填 schema。
遵守 required 和 enum 字段。
对于 CAP 能力，遵守 one_of_required；每个分组表示该组字段至少传一个。
examples.sample_parameters 只作为结构和典型值参考。
如果参数错误看起来属于另一个 provider 或另一个工具，请重新 search 或 inspect 当前 tool_id；这通常意味着客户端混用了两个工具的 schema。

成功响应#

{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {
      "temperature": 15.5,
      "description": "局部多云"
    }
  },
  "success": true,
  "error_message": null,
  "execution_time": 0.211,
  "elapsed_time_ms": 211,
  "billing": {
    "summary": "每次成功请求 5 积分",
    "list_amount_credits": 5
  },
  "cost": 5,
  "remaining_credits": 990
}

响应字段#

字段	类型	说明
`execution_id`	string	本次执行的唯一 id。请将示例中的 `exec_...` 替换为你自己响应返回的 id。
`result`	object	工具执行结果；长响应可能使用下方的截断结构。
`success`	boolean	工具执行是否成功。不要只根据此字段判断最终是否扣费。
`error_message`	string/null	`success=false` 时的错误说明。
`execution_time`	number	执行耗时，单位秒；这是 execute 响应的兼容字段。
`elapsed_time_ms`	number	可用时返回执行耗时，单位毫秒。
`billing`	object	可用时返回紧凑的预结算账单。
`cost`	number	可用时返回旧版/预结算成本信号。
`remaining_credits`	number/null	可用时返回账户剩余积分。

使用 respond_with: "summary" 时，顶层响应会刻意限定为执行标识/状态、可用时的耗时、cost、remaining_credits 和 result。result 仅包含 respond_with、content_schema、summary、full_content_file_url 和 message，不包含原始 billing、execution_outcome、参数、实验元数据、状态码或样例行。签名 full_content_file_url 直接指向对象存储，必须按原样使用。

示例：空结果，不扣费#

部分 provider 会返回合法响应，但没有可用结果。这种情况下 success 可以是 false，错误信息应提示用户当前参数没有结果，最终调用审计通常应归类为 failed_not_charged。

{
  "execution_id": "exec_01HZX9EMPTY",
  "result": {
    "data": {}
  },
  "success": false,
  "error_message": "The provider returned no results for the current parameters. Try different parameters.",
  "execution_time": 0.184,
  "elapsed_time_ms": 184,
  "billing": {
    "summary": "不扣费：提供商未返回可用结果",
    "list_amount_credits": 0
  },
  "cost": 0,
  "remaining_credits": 990
}

错误响应#

缺少 tool_id：

{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {}
  },
  "success": false,
  "error_message": "Missing required parameter: tool_id. Provide it as query (?tool_id=xxx) or in JSON body.",
  "execution_time": 0.01
}

积分不足：

{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {}
  },
  "success": false,
  "error_message": "Insufficient credits",
  "execution_time": 0.01,
  "remaining_credits": 0
}

上游工具失败：

{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {}
  },
  "success": false,
  "error_message": "Execute API error: HTTP 502",
  "execution_time": 0.211,
  "remaining_credits": 990
}

错误排查表#

错误类别	典型现象	需要检查	推荐处理
`tool_id` 格式错误	请求在进入 provider 前被拒绝。	是否完整复制了 Discover 或 Inspect 返回的 `tool_id`？	使用 API 返回的原始 `tool_id`，不要缩写、归一化或猜测。
`tool_id` 不存在	服务无法解析所选能力。	工具是否来自旧缓存、已下线或在当前区域不可用？	重新 Discover，并执行当前返回的工具。
参数错误	缺少必填字段、枚举值错误、类型错误、日期范围错误或代码格式错误。	请求体是否符合所选工具当前 `params`？	基于所选结果或 Inspect 响应重新生成 `parameters`。
schema 错配	参数看起来属于另一个 provider 或另一个工具。	智能体是否选择了一个 `tool_id`，却填了另一条 search 结果的参数？	把 `search_id`、选中结果和参数 schema 放在同一个上下文对象中传递。
权限或区域错误	provider 执行前出现 auth、OAuth 或区域限制。	账号是否授权？客户端是否使用正确区域的 API base URL？	让用户完成 OAuth、切换区域，或选择另一个返回的工具。
第三方接口错误	参数已接受，但上游返回 HTTP/provider 错误。	查看 `error_message`；需要结构化 `reason_code` 时查询调用审计。	视情况重试、选择其他 provider，或带 `execution_id` 联系支持。

联系支持时，请提供 execution_id、search_id、session_id、tool_id；如果是智能体客户端，也提供 model。这些字段可以帮助区分问题来自搜索排序、工具选择、参数生成、本地校验，还是第三方 provider。

长响应#

当 payload 超过 max_response_size 时，result 可能不包含 data，而是返回截断字段。

{
  "result": {
    "message": "Result content is too long. Use truncated_content or download full_content_file_url.",
    "full_content_file_url": "https://oss.qveris.ai/tool_result_cache/result.json?Expires=1700007200&Signature=example",
    "truncated_content": "{\"query\":\"evolution\",\"total_results\":890994",
    "content_schema": {
      "type": "object"
    }
  }
}

字段	说明
`truncated_content`	工具响应的前几个字节
`full_content_file_url`	用于从 QVeris 对象存储直接下载完整内容的临时 HTTPS 签名 URL。请原样使用，不要改写，也不要假设它与 API 同域；链接会过期。
`message`	适合给 LLM 读取的截断说明
`content_schema`	完整内容的 JSON schema（如果可用）

4. 调用审计 — 最终请求状态#

调用审计用于回答：“这次请求是否成功？”、“失败请求是否扣费？”、“哪一次执行需要客服复核？”。Agent、CLI、MCP 客户端应优先使用精确过滤或 summary=true，不要把全量历史直接输出给 LLM。

端点#

GET /auth/usage/history/v2

请求头#

请求头	必填	说明
`Authorization`	是	Bearer API key

查询参数#

参数	类型	必填	说明	默认值 / 范围
`start_date`	string	否	审计窗口开始时间。支持 `YYYY-MM-DD` 或 ISO-8601 datetime。	-
`end_date`	string	否	审计窗口结束时间。`YYYY-MM-DD` 会扩展到当天结束。	-
`event_type`	string	否	精确事件类型：`search`、`search_by_ids`、`tool_execute`、`capabilities_query`、`model_call`。	-
`kind`	string	否	高层分组。`discover` 对应 `search` + `search_by_ids`；`call` 对应 `tool_execute` + `capabilities_query`；`model` 对应 `model_call`。	-
`success`	boolean	否	使用事件记录的成功标记。	-
`billable_success`	boolean	否	计费侧成功标记；某些 provider/outcome 边界场景可能与 `success` 不同。	-
`outcome`	string	否	`execution_outcome.outcome` 的标准化结果过滤。	-
`reason_code`	string	否	标准化执行原因，例如 provider 或参数校验原因。	-
`has_execution_outcome`	boolean	否	`true` 只返回有结构化 execution outcome 的事件；`false` 只返回没有该结构的事件。	-
`charge_outcome`	string	否	最终扣费分类：`charged`、`included`、`failed_not_charged`、`failed_charged_review`。	-
`anomaly`	string	否	审计异常过滤：`failed_charged_review`、`missing_ledger_link`、`missing_billing_snapshot`。	-
`search_id`	string	否	聚焦到某次 Discover 相关事件。	-
`execution_id`	string	否	聚焦到某次 Call 执行；最适合回答“这次调用是否扣费”。	-
`min_credits`	number	否	最小有效结算/请求积分。必须 `>= 0`。	-
`max_credits`	number	否	最大有效结算/请求积分。必须 `>= 0`。	-
`page`	integer	否	页码。	默认 `1`，最小 `1`
`page_size`	integer	否	未传 `limit` 时的每页数量。	默认 `50`，范围 `1-50000`
`summary`	boolean	否	返回服务端聚合和高信号样本。若没有传日期，summary 默认最近 24 小时。	默认 `false`
`bucket`	string	否	summary 时间粒度。	`hour`、`day`、`week`；超过 3 天自动用 `day`，否则用 `hour`
`limit`	integer	否	覆盖返回样本数量，并限制在适合上下文的上限内。Agent/CLI/MCP 场景推荐使用。	`1-50`；summary 默认样本 `10`

`charge_outcome` 取值#

值	含义
`charged`	有效成功标记为 true，且最终/有效积分金额大于 0。
`included`	有效成功标记为 true，且最终/有效积分金额为 0，例如免费额度或策略豁免。
`failed_not_charged`	有效成功标记为 false，且最终/有效积分金额为 0。
`failed_charged_review`	有效成功标记为 false，但最终/有效积分金额大于 0；应作为客服/复核场景处理。

常见 `reason_code`#

reason_code 足够稳定，可用于自动化、过滤和客服排查。面向用户的文案可能调整；机器客户端应优先依赖 code。

Reason code	典型扣费结果	面向用户的含义
`result.valid`	`charged` 或 `included`	provider 返回了可用数据。
`result.partial_success`	`charged`、`included` 或 `failed_not_charged`	provider 返回了部分数据；需要结合结果和账单判断。
`result.empty`	`failed_not_charged`	provider 有响应，但没有可用结果数据。
`provider.error`	`failed_not_charged`	provider 返回错误。
`provider.http_error`	`failed_not_charged`	provider 返回非成功 HTTP 响应。
`provider.rate_limited`	`failed_not_charged`	上游 provider 对请求限流。
`provider.auth_or_permission`	`failed_not_charged`	上游 provider 拒绝认证或权限。
`transport.timeout`	`failed_not_charged`	QVeris 在超时前没有收到 provider 响应。
`transport.no_response`	`failed_not_charged`	QVeris 未能获取 provider 响应。
`transport.execution_failed`	`failed_not_charged`	执行链路在拿到可计费 provider 结果前失败。
`validation_error`	`failed_not_charged`	请求参数无效或不完整。
`tool_unavailable`	`failed_not_charged`	所选能力不可用。
`region_restricted`	`failed_not_charged`	所选能力在当前区域不可用。
`oauth_signin_required`	`failed_not_charged`	能力执行前需要先完成 OAuth 登录。

示例：按 execution_id 查询一次执行#

curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?execution_id=exec_01HZX9R2R4S2E" \
  -H "Authorization: Bearer $QVERIS_API_KEY"

{
  "status": "success",
  "message": "Usage events retrieved successfully",
  "status_code": 0,
  "data": {
    "items": [
      {
        "id": "evt_01HZX9R31GH2R",
        "event_type": "tool_execute",
        "source_system": "qveris_website",
        "source_ref_type": "execute_history",
        "source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
        "session_id": "sess_7Q9m",
        "search_id": "srch_01HZX9QK7J3M9T",
        "execution_id": "exec_01HZX9R2R4S2E",
        "tool_id": "openweathermap.weather.execute.v1",
        "success": true,
        "charge_outcome": "charged",
        "reason_code": "result.valid",
        "duration_ms": 211,
        "billing_snapshot_status": "upstream_provided",
        "billing_rule_snapshot": {
          "unit": "request",
          "amount_credits": 5
        },
        "pre_settlement_bill": {
          "summary": "每次成功请求 5 积分",
          "list_amount_credits": 5
        },
        "settlement_result": {
          "settled_amount_credits": 5
        },
        "pre_settlement_amount_credits": 5,
        "settled_amount_credits": 5,
        "actual_amount_credits": 5,
        "credits_ledger_entry_id": "led_01HZX9R39K6QZ",
        "display_target": "openweathermap.weather.execute.v1",
        "billing_summary": "每次成功请求 5 积分",
        "created_at": "2026-05-16T08:30:12Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 50,
    "summary": null
  }
}

示例：适合 Agent 上下文的聚合摘要#

curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?summary=true&bucket=day&kind=call&limit=5&start_date=2026-05-01&end_date=2026-05-16" \
  -H "Authorization: Bearer $QVERIS_API_KEY"

{
  "status": "success",
  "message": "Usage events retrieved successfully",
  "status_code": 0,
  "data": {
    "items": [
      {
        "id": "evt_01HZX9R31GH2R",
        "event_type": "tool_execute",
        "execution_id": "exec_01HZX9R2R4S2E",
        "tool_id": "openweathermap.weather.execute.v1",
        "success": true,
        "charge_outcome": "charged",
        "settled_amount_credits": 5,
        "created_at": "2026-05-16T08:30:12Z"
      }
    ],
    "total": 42,
    "page": 1,
    "page_size": 5,
    "summary": {
      "start_date": "2026-05-01T00:00:00Z",
      "end_date": "2026-05-16T23:59:59.999999Z",
      "bucket": "day",
      "total_count": 42,
      "success_count": 40,
      "failure_count": 2,
      "charge_outcome_counts": {
        "charged": 35,
        "included": 5,
        "failed_not_charged": 2,
        "failed_charged_review": 0
      },
      "pre_settlement_credits": 210,
      "settled_credits": 175,
      "max_charge_items": [],
      "buckets": [
        {
          "bucket_start": "2026-05-16T00:00:00Z",
          "total_count": 8,
          "success_count": 8,
          "failure_count": 0,
          "charged_count": 7,
          "included_count": 1,
          "failed_not_charged_count": 0,
          "failed_charged_review_count": 0,
          "pre_settlement_credits": 40,
          "settled_credits": 35
        }
      ]
    }
  }
}

响应字段#

顶层响应使用标准 APIResponse 包装。

字段	类型	说明
`status`	string	`success` 或 `failure`。
`message`	string	服务端可读消息。
`status_code`	integer	应用状态码。成功为 `0`；校验失败为负数。
`data.items`	array	按时间倒序返回的 usage events。
`data.total`	integer	匹配过滤条件的总数。
`data.page`	integer	当前页码。
`data.page_size`	integer	实际返回样本数。若传 `limit`，它会覆盖 `page_size` 并被限制到 `50`。
`data.summary`	object/null	`summary=true` 时返回聚合摘要，否则为 `null`。

重要 data.items[] 字段：

字段	说明
`event_type`	标准事件类型。`search` = Discover，`search_by_ids` = Inspect，`tool_execute` / `capabilities_query` = Call，`model_call` = 模型调用。
`search_id` / `execution_id`	Discover 或 Call 流程的关联 id。
`success`	使用事件记录的成功标记。
`charge_outcome`	面向用户的最终扣费分类。不要只根据 `success` 猜测是否扣费。
`error_message`	可用时返回错误详情。
`duration_ms`	请求耗时，单位毫秒。
`request_payload` / `response_payload_summary`	审计用请求/响应摘要。Agent 客户端默认不应直接输出这些字段。
`execution_outcome` 及 outcome 字段	可用时返回结构化 provider/result outcome。
`billing_rule_snapshot`	请求当时捕获的计费规则。
`pre_settlement_bill`	最终账本结算前的预结算账单。
`settlement_result`	可用时返回最终结算结果。
`requested_amount_credits` / `actual_amount_credits`	请求金额与最终/有效金额。
`credits_ledger_entry_id`	该 usage event 对应的最终账本行 id。
`display_target` / `billing_summary`	适合 UI 展示的目标和计费摘要。

错误响应#

日期或 bucket 无效：

{
  "status": "failure",
  "message": "Invalid start_date format. Use YYYY-MM-DD or ISO-8601 datetime",
  "status_code": -7,
  "data": null
}

积分区间无效：

{
  "status": "failure",
  "message": "min_credits cannot be greater than max_credits",
  "status_code": -7,
  "data": null
}

5. Credits 账本 — 最终余额变动#

Credits 账本用于解释最终账户余额。调用审计描述“请求发生了什么”；账本描述“余额如何不可变地变动”。一次已扣费的 Call 通常应该同时存在 charge_outcome=charged 的 usage event 和关联的账本行。

端点#

GET /auth/credits/ledger

请求头#

请求头	必填	说明
`Authorization`	是	Bearer API key

查询参数#

参数	类型	必填	说明	默认值 / 范围
`start_date`	string	否	账本窗口开始时间。支持 `YYYY-MM-DD` 或 ISO-8601 datetime。	-
`end_date`	string	否	账本窗口结束时间。`YYYY-MM-DD` 会扩展到当天结束。	-
`entry_type`	string	否	精确账本事件类型，例如 `consume_tool_execute`。	-
`scope`	string	否	预设事件类型组。`account_history` 包含 `grant_payment_recharge`、`consume_tool_search`、`consume_tool_execute`、`consume_model_call`。	-
`direction`	string	否	余额方向。`consume` 返回负数消耗；`grant` 返回正数发放；`any` 返回两者。	默认 `any`；允许 `consume`、`grant`、`any`
`min_credits`	number	否	最小绝对积分金额。例如 `min_credits=5` 同时匹配 `-5` 和 `+5`。必须 `>= 0`。	-
`max_credits`	number	否	最大绝对积分金额。必须 `>= 0`。	-
`page`	integer	否	页码。	默认 `1`，最小 `1`
`page_size`	integer	否	未传 `limit` 时的每页数量。	默认 `50`，范围 `1-500`
`summary`	boolean	否	返回聚合余额变动摘要。若没有传日期，summary 默认最近 24 小时。	默认 `false`
`bucket`	string	否	summary 时间粒度。	`hour`、`day`、`week`；超过 3 天自动用 `day`，否则用 `hour`
`limit`	integer	否	覆盖返回样本数量和 summary 最大金额样本，适合 Agent/CLI/MCP 使用。	`1-50`；summary 默认样本 `10`

常见 `entry_type`#

值	含义
`grant_payment_recharge`	充值/支付发放积分。
`grant_welcome_bonus`	新用户或活动赠送积分。
`grant_invitation_reward`	邀请/推荐奖励积分。
`consume_tool_search`	Discover 消耗积分；仅在部署策略对搜索计费时出现。
`consume_tool_execute`	能力 Call 消耗积分。
`consume_model_call`	模型调用消耗积分。
`consume_payment_refund`	退款相关的积分变动。

示例：查询最近的 Call 扣费#

curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?entry_type=consume_tool_execute&page=1&page_size=10" \
  -H "Authorization: Bearer $QVERIS_API_KEY"

{
  "status": "success",
  "message": "Credits ledger retrieved successfully",
  "status_code": 0,
  "data": {
    "items": [
      {
        "id": "led_01HZX9R39K6QZ",
        "entry_type": "consume_tool_execute",
        "amount_credits": -5,
        "source_system": "qveris_website",
        "source_ref_type": "execute_history",
        "source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
        "execution_id": "exec_01HZX9R2R4S2E",
        "pre_settlement_bill": {
          "execution_id": "exec_01HZX9R2R4S2E",
          "summary": "每次成功请求 5 积分",
          "list_amount_credits": 5
        },
        "settlement_result": {
          "settled_amount_credits": 5
        },
        "balance_before": {
          "total_available_credits": 995
        },
        "balance_after": {
          "total_available_credits": 990
        },
        "description": "Tool execution charge",
        "created_at": "2026-05-16T08:30:13Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10,
    "summary": null
  }
}

示例：聚合余额变动#

curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?summary=true&scope=account_history&direction=any&bucket=day&limit=5&start_date=2026-05-01&end_date=2026-05-16" \
  -H "Authorization: Bearer $QVERIS_API_KEY"

{
  "status": "success",
  "message": "Credits ledger retrieved successfully",
  "status_code": 0,
  "data": {
    "items": [
      {
        "id": "led_01HZX9R39K6QZ",
        "entry_type": "consume_tool_execute",
        "amount_credits": -5,
        "source_ref_type": "execute_history",
        "source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
        "execution_id": "exec_01HZX9R2R4S2E",
        "created_at": "2026-05-16T08:30:13Z"
      }
    ],
    "total": 18,
    "page": 1,
    "page_size": 5,
    "summary": {
      "start_date": "2026-05-01T00:00:00",
      "end_date": "2026-05-16T23:59:59.999999",
      "bucket": "day",
      "total_entries": 18,
      "consume_count": 14,
      "grant_count": 4,
      "consumed_credits": 175,
      "granted_credits": 1000,
      "net_amount_credits": 825,
      "max_amount_items": [],
      "buckets": [
        {
          "bucket_start": "2026-05-16T00:00:00",
          "entry_count": 3,
          "consume_count": 3,
          "grant_count": 0,
          "consumed_credits": 15,
          "granted_credits": 0,
          "net_amount_credits": -15
        }
      ]
    }
  }
}

响应字段#

字段	类型	说明
`data.items`	array	按时间倒序返回的账本行。
`data.total`	integer	匹配过滤条件的总数。
`data.page` / `data.page_size`	integer	当前页码和实际返回样本数。
`data.summary`	object/null	`summary=true` 时返回聚合余额摘要，否则为 `null`。

重要 data.items[] 字段：

字段	说明
`entry_type`	不可变账本事件类型。
`amount_credits`	带符号的余额变动。负数表示消耗，正数表示发放。
`source_system`	创建账本行的系统。
`source_ref_type` / `source_ref_id`	后端审计用来源行引用。
`execution_id`	`/tools/execute` 返回的 Call 执行 id；用户对账时使用这个字段。可用时会出现在 Call 账本行。
`pre_settlement_bill`	最终结算前的计费快照。
`settlement_result`	最终结算结果。
`balance_before` / `balance_after`	可用时返回本次变动前后的余额快照。
`ledger_metadata`	用于审计/调试的附加元数据。
`description`	人类可读的账本说明。
`created_at`	创建时间。

Summary 字段：

字段	说明
`total_entries`	匹配账本行总数。
`consume_count` / `grant_count`	负数消耗和正数发放的条目数量。
`consumed_credits` / `granted_credits`	消耗和发放的绝对值总量。
`net_amount_credits`	带符号净额；发放为正，消耗为负。
`max_amount_items`	绝对金额最大的高信号样本，受 `limit` 限制。
`buckets`	按时间粒度聚合的时间序列，适合图表或 Agent 摘要。

错误响应#

direction 无效：

{
  "status": "failure",
  "message": "Invalid direction. Use consume, grant, or any",
  "status_code": -7,
  "data": null
}

积分区间无效：

{
  "status": "failure",
  "message": "min_credits must be greater than or equal to 0",
  "status_code": -7,
  "data": null
}

端到端 smoke checklist#

创建新的 session_id。
执行 Discover 并保存 search_id。
Inspect 所选 tool_id，确认必填 params 和调用前成本字段。
使用有效 parameters 调用，并保存 execution_id。
用 execution_id 查询调用历史。
查询积分账本，确认最终余额变动与调用历史结果一致。

OpenAPI#

QVeris 公开 OpenAPI 文档包含 Discover、Inspect 和 Call 路径的请求体、响应结构与示例。稳定的投影与旧服务兼容样例见投影 fixtures。

QVeris REST API 文档

Base URL#

身份认证#

成本与 session 合同#

Search -> Execute 集成契约#

计费透明化合同#

限流#

1. 发现能力#

请求#

成功响应#

响应字段#

能力结果字段#

错误响应#

2. 按 id 检查能力#

请求#

成功响应#

响应字段#

错误响应#

3. 调用能力#

请求#

成功响应#

响应字段#

示例：空结果，不扣费#

错误响应#

错误排查表#

长响应#

4. 调用审计 — 最终请求状态#

端点#

请求头#

查询参数#

charge_outcome 取值#

常见 reason_code#

示例：按 execution_id 查询一次执行#

示例：适合 Agent 上下文的聚合摘要#

响应字段#

错误响应#

5. Credits 账本 — 最终余额变动#

端点#

请求头#

查询参数#

常见 entry_type#

示例：查询最近的 Call 扣费#

示例：聚合余额变动#

响应字段#

错误响应#

端到端 smoke checklist#

OpenAPI#

`charge_outcome` 取值#

常见 `reason_code`#

常见 `entry_type`#