QVeris REST API 文档

版本：2026-05-12

公开 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.cn/api/v1

身份认证

在 Authorization 请求头中发送 API key：

Authorization: Bearer YOUR_API_KEY

成本与 session 合同

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

Call 可能返回 billing、cost 等预结算字段。最终结算由调用历史和积分账本报告；客服、对账和用户账单历史应以这些端点为准。

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

Search -> Execute 集成契约

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

推荐契约：

1. 为一次用户任务或会话生成稳定的 session_id。
2. 用能力级查询调用 POST /search。
3. 保存返回的 search_id。
4. 从 results 中选择一个 tool_id。
5. 使用同一条结果里的 params、one_of_required 和 examples.sample_parameters 构造 parameters。
6. 调用 POST /tools/execute，传入 tool_id、parameters、search_id、session_id；如果是智能体客户端，也传入 model。
7. 保存 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、execution_outcome	解释 provider/result 是否可用。不要只用 success 判断最终是否扣费。
预结算账单	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	用于账户余额对账和客服排查。

推荐对账流程：

1. 使用 Discover 或 Inspect 展示 billing_rule / expected_cost。
2. 调用能力并保存 execution_id、billing、execution_outcome 和旧字段 cost。
3. 查询 /auth/usage/history/v2?execution_id=...，读取 charge_outcome、reason_code、actual_amount_credits 和 credits_ledger_entry_id。
4. 查询 /auth/credits/ledger 或关联账本行，验证最终带符号的余额变动。

客户端建议：

• REST 客户端应保留 Call 响应中的 execution_id、billing、execution_outcome 和 cost。
• CLI、MCP 和 SDK 客户端应展示同一组机器可读字段，不要翻译成不相关的本地状态名。
• 自动化逻辑优先使用 charge_outcome、reason_code 等稳定机器字段；面向用户的展示可使用 billing_summary 和 error_message。
• cost 为兼容旧客户端保留。新的计费 UI 应以调用审计和 Credits 账本作为最终结算依据。

限流

携带 Bearer token 时按 API key 限流，否则按客户端 IP 限流。

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

限流响应包含：

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

1. 发现能力

POST /search

请求

{
  "query": "天气预报 API",
  "limit": 10,
  "session_id": "sess_7Q9m"
}

字段	类型	必填	说明
query	string	是	自然语言能力查询
limit	integer	否	最大结果数；默认 20，范围 1-100
session_id	string	否	当前用户任务的追踪和计费上下文 ID

成功响应

{
  "query": "天气预报 API",
  "search_id": "srch_01HZX9QK7J3M9T",
  "total": 1,
  "results": [
    {
      "tool_id": "openweathermap.weather.execute.v1",
      "name": "当前天气",
      "description": "获取某城市的当前天气数据。",
      "provider_name": "OpenWeatherMap",
      "params": [
        {
          "name": "city",
          "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": "天气预报 API",
  "search_id": "srch_failed",
  "total": 0,
  "results": []
}

积分不足：

{
  "query": "天气预报 API",
  "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

成功响应

{
  "search_id": "srch_01HZX9QK7J3M9T",
  "total": 1,
  "results": [
    {
      "tool_id": "openweathermap.weather.execute.v1",
      "name": "当前天气",
      "description": "获取某城市的当前天气数据。",
      "provider_name": "OpenWeatherMap",
      "params": [
        {
          "name": "city",
          "type": "string",
          "required": true,
          "description": "城市名称"
        },
        {
          "name": "units",
          "type": "string",
          "required": false,
          "description": "温度单位",
          "enum": ["metric", "imperial", "standard"]
        }
      ],
      "examples": {
        "sample_parameters": {
          "city": "北京",
          "units": "metric"
        }
      },
      "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": {
    "city": "北京",
    "units": "metric"
  },
  "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 表示不截断

只从选中的工具构造 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
  },
  "execution_outcome": {
    "outcome": "success",
    "reason_code": "result.valid",
    "provider_success": true,
    "billable_success": true,
    "result_valid": true,
    "user_message": "The provider returned a valid result."
  },
  "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	可用时返回紧凑的预结算账单。
execution_outcome	object	可用时返回结构化结果和计费结果上下文。包含 outcome、reason_code、provider_success、billable_success、result_valid 等稳定字段。
cost	number	可用时返回旧版/预结算成本信号。
remaining_credits	number/null	可用时返回账户剩余积分。

示例：空结果，不扣费

部分 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
  },
  "execution_outcome": {
    "outcome": "empty_result",
    "reason_code": "result.empty",
    "provider_success": true,
    "billable_success": false,
    "result_valid": false,
    "user_message": "The provider returned no usable result data; this call was not charged."
  },
  "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 错误。	execution_outcome.reason_code 是否以 provider. 开头？	视情况重试、选择其他 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://...",
    "truncated_content": "{\"query\":\"evolution\",\"total_results\":890994",
    "content_schema": {
      "type": "object"
    }
  }
}

字段	说明
truncated_content	工具响应的前几个字节
full_content_file_url	完整内容的临时 URL
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

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

OpenAPI

公开 OpenAPI 文档位于本仓库的 docs/openapi/qveris-public-api.openapi.json，包含 Discover、Inspect 和 Call 路径的请求体、响应 schema 与示例。