Skip to content

docs: sync API docs from website #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
linfangw merged 2 commits into from
May 20, 2026
Merged

docs: sync API docs from website #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3800828
docs: sync API docs from website
May 19, 2026
b77f4fd
docs: update generated OpenAPI artifacts
linfangw May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions docs/cn/zh-CN/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -485,8 +485,8 @@ curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?execution_id=exec_01HZX9R2R4S2E
"id": "evt_01HZX9R31GH2R",
"event_type": "tool_execute",
"source_system": "qveris_website",
"source_ref_type": "tool_execute",
"source_ref_id": "exec_01HZX9R2R4S2E",
"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",
Expand Down Expand Up @@ -697,9 +697,11 @@ curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?entry_type=consume_tool_execute&p
"entry_type": "consume_tool_execute",
"amount_credits": -5,
"source_system": "qveris_website",
"source_ref_type": "tool_execute",
"source_ref_id": "exec_01HZX9R2R4S2E",
"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
},
Expand Down Expand Up @@ -742,7 +744,9 @@ curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?summary=true&scope=account_histor
"id": "led_01HZX9R39K6QZ",
"entry_type": "consume_tool_execute",
"amount_credits": -5,
"source_ref_id": "exec_01HZX9R2R4S2E",
"source_ref_type": "execute_history",
"source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
"execution_id": "exec_01HZX9R2R4S2E",
"created_at": "2026-05-16T08:30:13Z"
}
],
Expand Down Expand Up @@ -792,7 +796,8 @@ curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?summary=true&scope=account_histor
| `entry_type` | 不可变账本事件类型。 |
| `amount_credits` | 带符号的余额变动。负数表示消耗，正数表示发放。 |
| `source_system` | 创建账本行的系统。 |
| `source_ref_type` / `source_ref_id` | 关联目标，通常是 execution id、search id、payment id 或 model call id。 |
| `source_ref_type` / `source_ref_id` | 后端审计用来源行引用。 |
| `execution_id` | `/tools/execute` 返回的 Call 执行 id；用户对账时使用这个字段。可用时会出现在 Call 账本行。 |
| `pre_settlement_bill` | 最终结算前的计费快照。 |
| `settlement_result` | 最终结算结果。 |
| `balance_before` / `balance_after` | 可用时返回本次变动前后的余额快照。 |
Expand Down
17 changes: 11 additions & 6 deletions docs/en-US/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -485,8 +485,8 @@ curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?execution_id=exec_01HZX9R2R4S2E
"id": "evt_01HZX9R31GH2R",
"event_type": "tool_execute",
"source_system": "qveris_website",
"source_ref_type": "tool_execute",
"source_ref_id": "exec_01HZX9R2R4S2E",
"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",
Expand Down Expand Up @@ -697,9 +697,11 @@ curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?entry_type=consume_tool_execute&p
"entry_type": "consume_tool_execute",
"amount_credits": -5,
"source_system": "qveris_website",
"source_ref_type": "tool_execute",
"source_ref_id": "exec_01HZX9R2R4S2E",
"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 credits per successful request",
"list_amount_credits": 5
},
Expand Down Expand Up @@ -742,7 +744,9 @@ curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?summary=true&scope=account_histor
"id": "led_01HZX9R39K6QZ",
"entry_type": "consume_tool_execute",
"amount_credits": -5,
"source_ref_id": "exec_01HZX9R2R4S2E",
"source_ref_type": "execute_history",
"source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
"execution_id": "exec_01HZX9R2R4S2E",
"created_at": "2026-05-16T08:30:13Z"
}
],
Expand Down Expand Up @@ -792,7 +796,8 @@ Important `data.items[]` fields:
| `entry_type` | Immutable ledger event type. |
| `amount_credits` | Signed balance movement. Negative values consume credits; positive values grant credits. |
| `source_system` | System that created the ledger row. |
| `source_ref_type` / `source_ref_id` | Correlation target, usually an execution id, search id, payment id, or model call id. |
| `source_ref_type` / `source_ref_id` | Source row reference for backend audit. |
| `execution_id` | Call execution id returned by `/tools/execute`; use this for user reconciliation. Present for Call ledger rows when available. |
| `pre_settlement_bill` | Billing snapshot before final settlement. |
| `settlement_result` | Final settlement result. |
| `balance_before` / `balance_after` | Balance snapshots around this movement when available. |
Expand Down
62 changes: 43 additions & 19 deletions docs/openapi/qveris-public-api.openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 3105
"line": 3150
},
"x-qveris-response-model": "APIResponse[SettlementHistoryResponse]"
}
Expand Down Expand Up @@ -170,7 +170,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 1095
"line": 1140
},
"x-qveris-response-model": "APIResponse[dict]"
}
Expand Down Expand Up @@ -404,9 +404,11 @@
"entry_type": "consume_tool_execute",
"amount_credits": -5,
"source_system": "qveris_website",
"source_ref_type": "tool_execute",
"source_ref_id": "exec_01HZX9R2R4S2E",
"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 credits per successful request",
"list_amount_credits": 5
},
Expand Down Expand Up @@ -467,7 +469,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 3203
"line": 3248
},
"x-qveris-response-model": "APIResponse[CreditsLedgerResponse]"
}
Expand Down Expand Up @@ -553,7 +555,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 3516
"line": 3563
},
"x-qveris-response-model": "APIResponse[CreditsLedgerReadinessResponse]"
}
Expand Down Expand Up @@ -649,7 +651,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 3379
"line": 3424
}
}
},
Expand Down Expand Up @@ -707,7 +709,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 3464
"line": 3511
},
"x-qveris-response-model": "APIResponse[CreditsLedgerItem]"
}
Expand Down Expand Up @@ -829,7 +831,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 2868
"line": 2913
},
"x-qveris-response-model": "APIResponse[UsageCreditsSpentResponse]"
}
Expand Down Expand Up @@ -1222,8 +1224,8 @@
"id": "evt_01HZX9R31GH2R",
"event_type": "tool_execute",
"source_system": "qveris_website",
"source_ref_type": "tool_execute",
"source_ref_id": "exec_01HZX9R2R4S2E",
"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",
Expand Down Expand Up @@ -1285,7 +1287,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 2576
"line": 2621
},
"x-qveris-response-model": "APIResponse[UsageEventsResponse]"
}
Expand Down Expand Up @@ -1560,7 +1562,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 2938
"line": 2983
}
}
},
Expand Down Expand Up @@ -1875,7 +1877,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 2757
"line": 2802
},
"x-qveris-response-model": "APIResponse[UsageEventSummaryResponse]"
}
Expand Down Expand Up @@ -1935,7 +1937,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 3063
"line": 3108
},
"x-qveris-response-model": "APIResponse[UsageEventItem]"
}
Expand Down Expand Up @@ -1973,7 +1975,7 @@
],
"x-qveris-source": {
"file": "backend/routers/auth.py",
"line": 3655
"line": 3702
},
"x-qveris-response-model": "APIResponse[TokenVerificationResponse]"
}
Expand Down Expand Up @@ -2095,7 +2097,7 @@
],
"x-qveris-source": {
"file": "backend/routers/search.py",
"line": 2245
"line": 2260
}
}
},
Expand Down Expand Up @@ -2130,7 +2132,7 @@
],
"x-qveris-source": {
"file": "backend/routers/search.py",
"line": 2174
"line": 2189
}
}
},
Expand Down Expand Up @@ -2464,7 +2466,7 @@
],
"x-qveris-source": {
"file": "backend/routers/search.py",
"line": 2302
"line": 2348
},
"requestBody": {
"required": true,
Expand Down Expand Up @@ -3221,6 +3223,17 @@
],
"title": "Source Ref Id"
},
"execution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Execution Id"
},
"pre_settlement_bill": {
"anyOf": [
{
Expand Down Expand Up @@ -3667,6 +3680,17 @@
],
"title": "Source Ref Id"
},
"execution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Execution Id"
},
"description": {
"anyOf": [
{
Expand Down
17 changes: 11 additions & 6 deletions docs/zh-CN/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -485,8 +485,8 @@ curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?execution_id=exec_01HZX9R2R4S2E
"id": "evt_01HZX9R31GH2R",
"event_type": "tool_execute",
"source_system": "qveris_website",
"source_ref_type": "tool_execute",
"source_ref_id": "exec_01HZX9R2R4S2E",
"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",
Expand Down Expand Up @@ -697,9 +697,11 @@ curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?entry_type=consume_tool_execute&p
"entry_type": "consume_tool_execute",
"amount_credits": -5,
"source_system": "qveris_website",
"source_ref_type": "tool_execute",
"source_ref_id": "exec_01HZX9R2R4S2E",
"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
},
Expand Down Expand Up @@ -742,7 +744,9 @@ curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?summary=true&scope=account_histor
"id": "led_01HZX9R39K6QZ",
"entry_type": "consume_tool_execute",
"amount_credits": -5,
"source_ref_id": "exec_01HZX9R2R4S2E",
"source_ref_type": "execute_history",
"source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
"execution_id": "exec_01HZX9R2R4S2E",
"created_at": "2026-05-16T08:30:13Z"
}
],
Expand Down Expand Up @@ -792,7 +796,8 @@ curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?summary=true&scope=account_histor
| `entry_type` | 不可变账本事件类型。 |
| `amount_credits` | 带符号的余额变动。负数表示消耗，正数表示发放。 |
| `source_system` | 创建账本行的系统。 |
| `source_ref_type` / `source_ref_id` | 关联目标，通常是 execution id、search id、payment id 或 model call id。 |
| `source_ref_type` / `source_ref_id` | 后端审计用来源行引用。 |
| `execution_id` | `/tools/execute` 返回的 Call 执行 id；用户对账时使用这个字段。可用时会出现在 Call 账本行。 |
| `pre_settlement_bill` | 最终结算前的计费快照。 |
| `settlement_result` | 最终结算结果。 |
| `balance_before` / `balance_after` | 可用时返回本次变动前后的余额快照。 |
Expand Down
4 changes: 4 additions & 0 deletions packages/mcp/src/generated/openapi.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -547,6 +547,8 @@ export interface components {
source_ref_type?: string | null;
/** Source Ref Id */
source_ref_id?: string | null;
/** Execution Id */
execution_id?: string | null;
/** Pre Settlement Bill */
pre_settlement_bill?: {
[key: string]: unknown;
Expand Down Expand Up @@ -702,6 +704,8 @@ export interface components {
source_ref_type?: string | null;
/** Source Ref Id */
source_ref_id?: string | null;
/** Execution Id */
execution_id?: string | null;
/** Description */
description?: string | null;
/** Display Target */
Expand Down
2 changes: 2 additions & 0 deletions packages/python-sdk/qveris/generated/openapi_models.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ class CreditsLedgerItem(BaseModel):
source_system: str = Field(..., title='Source System')
source_ref_type: Optional[str] = Field(None, title='Source Ref Type')
source_ref_id: Optional[str] = Field(None, title='Source Ref Id')
execution_id: Optional[str] = Field(None, title='Execution Id')
pre_settlement_bill: Optional[Dict[str, Any]] = Field(
None, title='Pre Settlement Bill'
)
Expand Down Expand Up @@ -79,6 +80,7 @@ class SettlementHistoryItem(BaseModel):
source_system: str = Field(..., title='Source System')
source_ref_type: Optional[str] = Field(None, title='Source Ref Type')
source_ref_id: Optional[str] = Field(None, title='Source Ref Id')
execution_id: Optional[str] = Field(None, title='Execution Id')
description: Optional[str] = Field(None, title='Description')
display_target: Optional[str] = Field(None, title='Display Target')
billing_summary: Optional[str] = Field(None, title='Billing Summary')
Expand Down
Loading