openapi: 3.1.0
info:
  title: QVeris Public REST API
  version: 2026-07-30.1
  summary: External REST API for enterprise integration.
  description: OpenAPI 3.1 schema for the formally released public `/api/v1` REST
    API surface. It covers search, provider discovery, tool metadata
    lookup/execution, credits, and account audit endpoints. Unreleased API
    families are intentionally excluded from this customer-facing schema.
paths:
  /auth/account/settlement-history:
    get:
      tags:
        - Account
      summary: Get Account Settlement History
      description: |-
        获取账号中心结算历史轻量 feed。

        This first implementation serves the immutable ledger summary path used
        after readiness confirms the ledger is complete for the requested range.
      operationId: get_account_settlement_history_api_v1_auth_account_settlement_history_get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 开始日期 (YYYY-MM-DD)
            title: Start Date
          description: 开始日期 (YYYY-MM-DD)
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 结束日期 (YYYY-MM-DD)
            title: End Date
          description: 结束日期 (YYYY-MM-DD)
        - name: scope
          in: query
          required: false
          schema:
            type: string
            description: 账本范围
            default: account_history
            title: Scope
          description: 账本范围
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 下一页游标
            title: Cursor
          description: 下一页游标
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            description: 每页数量
            default: 100
            title: Page Size
          description: 每页数量
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_SettlementHistoryResponse_"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /auth/credits:
    get:
      tags:
        - Account
      summary: Get Current User Credits
      description: 查询当前用户的积分信息，包括各类积分明细和剩余总积分。支持 API Key 和 JWT 认证。
      operationId: get_current_user_credits_api_v1_auth_credits_get
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_dict_"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "401":
          description: Missing, malformed, expired, or unrecognized credential
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      security:
        - HTTPBearer: []
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /auth/credits/ledger:
    get:
      tags:
        - Account
      summary: Query credits ledger
      description: Query immutable final credit balance movements. Usage audit
        explains request outcomes; the credits ledger explains signed balance
        changes. Negative `amount_credits` values consume credits and positive
        values grant credits.
      operationId: get_credits_ledger_api_v1_auth_credits_ledger_get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 开始日期 (YYYY-MM-DD)
            title: Start Date
          description: 开始日期 (YYYY-MM-DD)
          example: 2026-05-01
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 结束日期 (YYYY-MM-DD)
            title: End Date
          description: 结束日期 (YYYY-MM-DD)
          example: 2026-05-16
        - name: entry_type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 账本事件类型
            title: Entry Type
          description: 账本事件类型
          example: consume_tool_execute
        - name: scope
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 预定义账本范围，例如 account_history
            title: Scope
          description: 预定义账本范围，例如 account_history
          example: account_history
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: 页码
            default: 1
            title: Page
          description: 页码
          example: 1
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            description: 每页数量
            default: 50
            title: Page Size
          description: 每页数量
          example: 50
        - name: min_credits
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: "null"
            title: Min Credits
          example: 1
        - name: max_credits
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: "null"
            title: Max Credits
          example: 25
        - name: direction
          in: query
          required: false
          schema:
            type: string
            default: any
            title: Direction
          example: consume
        - name: bucket
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: Bucket
          example: day
        - name: summary
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Summary
          example: true
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: "null"
            title: Limit
          example: 5
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_CreditsLedgerResponse_"
              example:
                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 credits per successful request
                        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: 50
                  summary: null
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "400":
          description: Invalid ledger query
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_dict_"
              example:
                status: failure
                message: Invalid direction. Use consume, grant, or any
                status_code: -7
                data: null
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /auth/credits/ledger-readiness:
    get:
      tags:
        - Account
      summary: Get Credits Ledger Readiness
      description: Check whether this user's account history can safely switch to
        credits_ledger.
      operationId: get_credits_ledger_readiness_api_v1_auth_credits_ledger_readiness_get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 开始日期 (YYYY-MM-DD)
            title: Start Date
          description: 开始日期 (YYYY-MM-DD)
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 结束日期 (YYYY-MM-DD)
            title: End Date
          description: 结束日期 (YYYY-MM-DD)
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_CreditsLedgerReadinessResponse_"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /auth/credits/ledger/export:
    get:
      tags:
        - Account
      summary: Export Credits Ledger
      description: 导出用户 credits ledger 账本，供账号中心和运营审计使用。
      operationId: export_credits_ledger_api_v1_auth_credits_ledger_export_get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 开始日期 (YYYY-MM-DD)
            title: Start Date
          description: 开始日期 (YYYY-MM-DD)
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 结束日期 (YYYY-MM-DD)
            title: End Date
          description: 结束日期 (YYYY-MM-DD)
        - name: scope
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 账本导出范围
            default: account_history
            title: Scope
          description: 账本导出范围
      responses:
        "200":
          description: CSV export.
          content:
            text/csv:
              schema:
                type: string
                format: binary
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /auth/credits/ledger/{entry_id}:
    get:
      tags:
        - Account
      summary: Get Credits Ledger Entry
      description: 获取单条 credits ledger detail，用于账单详情展开和审计追溯。
      operationId: get_credits_ledger_entry_api_v1_auth_credits_ledger__entry_id__get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: entry_id
          in: path
          required: true
          schema:
            type: string
            title: Entry Id
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_CreditsLedgerItem_"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /auth/usage/credits-spent:
    get:
      tags:
        - Account
      summary: Get Usage Credits Spent
      description: >-
        Return the total credits spent by the current user in the given date
        range.


        Uses a single server-side SUM query — no pagination limit — so results
        are

        accurate even for high-volume users with thousands of events in the
        window.
      operationId: get_usage_credits_spent_api_v1_auth_usage_credits_spent_get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 开始日期 (YYYY-MM-DD)
            title: Start Date
          description: 开始日期 (YYYY-MM-DD)
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 结束日期 (YYYY-MM-DD)
            title: End Date
          description: 结束日期 (YYYY-MM-DD)
        - name: kind
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 事件分组过滤
            title: Kind
          description: 事件分组过滤
        - name: charge_outcome
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 收费结果过滤
            title: Charge Outcome
          description: 收费结果过滤
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_UsageCreditsSpentResponse_"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /auth/usage/history/v2:
    get:
      tags:
        - Account
      summary: Query usage audit history
      description: Query canonical usage events to confirm request success, failure,
        and final charge outcome. Agent, CLI, and MCP clients should prefer
        precise filters such as `execution_id` or `summary=true` with a bounded
        `limit` instead of dumping full history.
      operationId: get_usage_history_v2_api_v1_auth_usage_history_v2_get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 开始日期 (YYYY-MM-DD)
            title: Start Date
          description: 开始日期 (YYYY-MM-DD)
          example: 2026-05-01
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 结束日期 (YYYY-MM-DD)
            title: End Date
          description: 结束日期 (YYYY-MM-DD)
          example: 2026-05-16
        - name: event_type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 事件类型过滤
            title: Event Type
          description: 事件类型过滤
          example: tool_execute
        - name: kind
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 事件分组过滤
            title: Kind
          description: 事件分组过滤
          example: call
        - name: success
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: "null"
            description: 是否成功
            title: Success
          description: 是否成功
          example: true
        - name: billable_success
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: "null"
            description: 是否可计费
            title: Billable Success
          description: 是否可计费
          example: true
        - name: outcome
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 执行 outcome 过滤
            title: Outcome
          description: 执行 outcome 过滤
          example: completed
        - name: reason_code
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 执行 reason_code 过滤
            title: Reason Code
          description: 执行 reason_code 过滤
          example: provider_success
        - name: has_execution_outcome
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: "null"
            description: 是否存在 execution_outcome
            title: Has Execution Outcome
          description: 是否存在 execution_outcome
          example: true
        - name: charge_outcome
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 收费结果过滤
            title: Charge Outcome
          description: 收费结果过滤
          example: charged
        - name: anomaly
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 异常类型过滤
            title: Anomaly
          description: 异常类型过滤
          example: missing_ledger_link
        - name: search_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: search_id 聚焦过滤
            title: Search Id
          description: search_id 聚焦过滤
          example: srch_01HZX9QK7J3M9T
        - name: execution_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: execution_id 聚焦过滤
            title: Execution Id
          description: execution_id 聚焦过滤
          example: exec_01HZX9R2R4S2E
        - name: api_key_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: "null"
            description: API Key 归因过滤
            title: Api Key Id
          description: API Key 归因过滤
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: 页码
            default: 1
            title: Page
          description: 页码
          example: 1
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 50000
            minimum: 1
            description: 每页数量
            default: 50
            title: Page Size
          description: 每页数量
          example: 50
        - name: include_details
          in: query
          required: false
          schema:
            type: boolean
            description: 是否在列表中返回完整审计详情字段
            default: false
            title: Include Details
          description: 是否在列表中返回完整审计详情字段
        - name: min_credits
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: "null"
            title: Min Credits
          example: 1
        - name: max_credits
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: "null"
            title: Max Credits
          example: 25
        - name: bucket
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: Bucket
          example: day
        - name: summary
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Summary
          example: true
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: "null"
            title: Limit
          example: 5
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_UsageEventsResponse_"
              example:
                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
                      duration_ms: 211
                      billing_snapshot_status: upstream_provided
                      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 credits per successful request
                      created_at: 2026-05-16T08:30:12Z
                  total: 1
                  page: 1
                  page_size: 50
                  summary: null
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "400":
          description: Invalid audit query
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_dict_"
              example:
                status: failure
                message: Invalid start_date format. Use YYYY-MM-DD or ISO-8601 datetime
                status_code: -7
                data: null
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /auth/usage/history/v2/export:
    get:
      tags:
        - Account
      summary: Export Usage History V2
      description: 导出 request-level usage audit，供用户与支持审计使用。
      operationId: export_usage_history_v2_api_v1_auth_usage_history_v2_export_get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 开始日期 (YYYY-MM-DD)
            title: Start Date
          description: 开始日期 (YYYY-MM-DD)
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 结束日期 (YYYY-MM-DD)
            title: End Date
          description: 结束日期 (YYYY-MM-DD)
        - name: event_type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 事件类型过滤
            title: Event Type
          description: 事件类型过滤
        - name: kind
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 事件分组过滤
            title: Kind
          description: 事件分组过滤
        - name: success
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: "null"
            description: 是否成功
            title: Success
          description: 是否成功
        - name: billable_success
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: "null"
            description: 是否可计费
            title: Billable Success
          description: 是否可计费
        - name: outcome
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 执行 outcome 过滤
            title: Outcome
          description: 执行 outcome 过滤
        - name: reason_code
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 执行 reason_code 过滤
            title: Reason Code
          description: 执行 reason_code 过滤
        - name: has_execution_outcome
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: "null"
            description: 是否存在 execution_outcome
            title: Has Execution Outcome
          description: 是否存在 execution_outcome
        - name: charge_outcome
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 收费结果过滤
            title: Charge Outcome
          description: 收费结果过滤
        - name: anomaly
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 异常类型过滤
            title: Anomaly
          description: 异常类型过滤
        - name: search_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: search_id 聚焦过滤
            title: Search Id
          description: search_id 聚焦过滤
        - name: execution_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: execution_id 聚焦过滤
            title: Execution Id
          description: execution_id 聚焦过滤
        - name: api_key_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: "null"
            description: API Key 归因过滤
            title: Api Key Id
          description: API Key 归因过滤
      responses:
        "200":
          description: CSV export.
          content:
            text/csv:
              schema:
                type: string
                format: binary
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /auth/usage/history/v2/summary:
    get:
      tags:
        - Account
      summary: Get Usage History V2 Summary
      description: 获取轻量 usage events summary，用于账号页列表快速渲染。
      operationId: get_usage_history_v2_summary_api_v1_auth_usage_history_v2_summary_get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 开始日期 (YYYY-MM-DD)
            title: Start Date
          description: 开始日期 (YYYY-MM-DD)
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 结束日期 (YYYY-MM-DD)
            title: End Date
          description: 结束日期 (YYYY-MM-DD)
        - name: event_type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 事件类型过滤
            title: Event Type
          description: 事件类型过滤
        - name: kind
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 事件分组过滤
            title: Kind
          description: 事件分组过滤
        - name: success
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: "null"
            description: 是否成功
            title: Success
          description: 是否成功
        - name: billable_success
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: "null"
            description: 是否可计费
            title: Billable Success
          description: 是否可计费
        - name: outcome
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 执行 outcome 过滤
            title: Outcome
          description: 执行 outcome 过滤
        - name: reason_code
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 执行 reason_code 过滤
            title: Reason Code
          description: 执行 reason_code 过滤
        - name: has_execution_outcome
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: "null"
            description: 是否存在 execution_outcome
            title: Has Execution Outcome
          description: 是否存在 execution_outcome
        - name: charge_outcome
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 收费结果过滤
            title: Charge Outcome
          description: 收费结果过滤
        - name: anomaly
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 异常类型过滤
            title: Anomaly
          description: 异常类型过滤
        - name: search_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: search_id 聚焦过滤
            title: Search Id
          description: search_id 聚焦过滤
        - name: execution_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: execution_id 聚焦过滤
            title: Execution Id
          description: execution_id 聚焦过滤
        - name: api_key_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: "null"
            description: API Key 归因过滤
            title: Api Key Id
          description: API Key 归因过滤
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: 下一页游标
            title: Cursor
          description: 下一页游标
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            description: 每页数量
            default: 100
            title: Page Size
          description: 每页数量
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_UsageEventSummaryResponse_"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /auth/usage/history/v2/{event_id}:
    get:
      tags:
        - Account
      summary: Get Usage History V2 Entry
      description: 获取单条 usage event 详情。
      operationId: get_usage_history_v2_entry_api_v1_auth_usage_history_v2__event_id__get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Event Id
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_UsageEventItem_"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /auth/verify-token:
    post:
      tags:
        - Auth
      summary: Verify Token
      description: |-
        验证JWT token是否有效和是否过期

        Args:
            token: JWT访问令牌
            
        Returns:
            TokenVerificationResponse: 包含token验证结果的响应
      operationId: verify_token_api_v1_auth_verify_token_post
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_TokenVerificationResponse_"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      security:
        - OAuth2PasswordBearer: []
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /credits:
    get:
      tags:
        - Account
      summary: Get Current User Credits
      description: 查询当前用户的积分信息，包括各类积分明细和剩余总积分。支持 API Key 和 JWT 认证。
      operationId: get_current_user_credits_api_v1_credits_get
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIResponse_dict_"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      security:
        - OAuth2PasswordBearer: []
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /meta:
    get:
      tags:
        - Metadata
      summary: Api Metadata
      description: Return the published API contract version without authentication.
      operationId: api_metadata_api_v1_meta_get
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiMetadata"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
      security: []
  /oauth/device/authorize:
    post:
      tags:
        - Authentication
      summary: Device Authorize
      operationId: device_authorize_api_v1_oauth_device_authorize_post
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                scope:
                  type: string
                  title: Scope
                resource:
                  anyOf:
                    - type: string
                    - type: "null"
                  title: Resource
                client_id:
                  anyOf:
                    - type: string
                    - type: "null"
                  title: Client Id
              type: object
              required:
                - scope
              title: Body_device_authorize_api_v1_oauth_device_authorize_post
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthDeviceAuthorizationResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "400":
          description: OAuth request or grant error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "401":
          description: Client authentication or bearer-token error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "403":
          description: Subject token has insufficient scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "429":
          description: Device Authorization rate limit exceeded
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthRateLimitResponse"
      x-qveris-visibility: public
      x-qveris-release-stage: published
      security:
        - {}
        - OAuthClientBasic: []
  /oauth/introspect:
    post:
      tags:
        - Authentication
      summary: Introspect a QVeris resource token
      description: 'RFC 7662-compatible introspection for allowlisted confidential
        Resource Server clients. resource is mandatory and must exactly match
        both the client registration and token audience. Invalid, expired,
        revoked, or wrong-audience tokens return only {"active": false}.'
      operationId: introspect_api_v1_oauth_introspect_post
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                token:
                  type: string
                  title: Token
                resource:
                  type: string
                  title: Resource
                token_type_hint:
                  anyOf:
                    - type: string
                    - type: "null"
                  title: Token Type Hint
              type: object
              required:
                - token
                - resource
              title: Body_introspect_api_v1_oauth_introspect_post
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/OAuthIntrospectionActiveResponse"
                  - $ref: "#/components/schemas/OAuthIntrospectionInactiveResponse"
                title: Response Introspect Api V1 Oauth Introspect Post
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "400":
          description: OAuth request or grant error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "401":
          description: Client authentication or bearer-token error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "403":
          description: Subject token has insufficient scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
      security:
        - OAuthClientBasic: []
  /oauth/revoke:
    post:
      tags:
        - Authentication
      summary: Revoke
      operationId: revoke_api_v1_oauth_revoke_post
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                token:
                  type: string
                  title: Token
                token_type_hint:
                  anyOf:
                    - type: string
                    - type: "null"
                  title: Token Type Hint
                client_id:
                  anyOf:
                    - type: string
                    - type: "null"
                  title: Client Id
              type: object
              required:
                - token
              title: Body_revoke_api_v1_oauth_revoke_post
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema: {}
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "400":
          description: OAuth request or grant error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "401":
          description: Client authentication or bearer-token error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "403":
          description: Subject token has insufficient scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
      security:
        - {}
        - OAuthClientBasic: []
  /oauth/token:
    post:
      tags:
        - Authentication
      summary: Issue or exchange an OAuth token
      description: Supports Authorization Code, Refresh Token, Device Code, and RFC
        8693 Token Exchange. Token Exchange requires HTTP Basic authentication
        for a registered confidential Agent Runtime. Its subject_token,
        subject_token_type, resource, and scope fields are required together.
        Delegation tokens have a maximum 600-second lifetime and never include a
        refresh_token.
      operationId: token_api_v1_oauth_token_post
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - type: object
                  required:
                    - grant_type
                    - code
                    - redirect_uri
                    - code_verifier
                  properties:
                    grant_type:
                      type: string
                      const: authorization_code
                    code:
                      type: string
                    redirect_uri:
                      type: string
                      format: uri
                    code_verifier:
                      type: string
                      minLength: 43
                      maxLength: 128
                    client_id:
                      type: string
                - type: object
                  required:
                    - grant_type
                    - refresh_token
                  properties:
                    grant_type:
                      type: string
                      const: refresh_token
                    refresh_token:
                      type: string
                    client_id:
                      type: string
                - type: object
                  required:
                    - grant_type
                    - device_code
                  properties:
                    grant_type:
                      type: string
                      const: urn:ietf:params:oauth:grant-type:device_code
                    device_code:
                      type: string
                    client_id:
                      type: string
                - type: object
                  required:
                    - grant_type
                    - subject_token
                    - subject_token_type
                    - resource
                    - scope
                  properties:
                    grant_type:
                      type: string
                      const: urn:ietf:params:oauth:grant-type:token-exchange
                    subject_token:
                      type: string
                    subject_token_type:
                      type: string
                      const: urn:ietf:params:oauth:token-type:access_token
                    requested_token_type:
                      type: string
                      const: urn:ietf:params:oauth:token-type:access_token
                    resource:
                      type: string
                      format: uri
                    scope:
                      type: string
                    model:
                      type: string
                      maxLength: 128
                    run_id:
                      type: string
                      maxLength: 128
                    max_credits:
                      type: integer
                      minimum: 1
                    tool_ids:
                      type: array
                      items:
                        type: string
                      maxItems: 100
                    provider_ids:
                      type: array
                      items:
                        type: string
                      maxItems: 100
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/OAuthAccessTokenResponse"
                  - $ref: "#/components/schemas/OAuthTokenExchangeResponse"
                title: Response Token Api V1 Oauth Token Post
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "400":
          description: OAuth request or grant error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "401":
          description: Client authentication or bearer-token error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "403":
          description: Subject token has insufficient scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErrorResponse"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
      security:
        - {}
        - OAuthClientBasic: []
  /providers:
    get:
      tags:
        - Discovery
      summary: Get Providers
      description: Get providers from the real API with optional filtering and pagination
      operationId: get_providers_api_v1_providers_get
      security:
        - HTTPBearer: []
      parameters:
        - name: categories
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: Categories
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            default: 0
            title: Skip
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            title: Limit
        - name: query
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: Query
        - name: sort_by
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: Sort By
        - name: sort_order
          in: query
          required: false
          schema:
            type: string
            default: asc
            title: Sort Order
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema: {}
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /providers/categories:
    get:
      tags:
        - Discovery
      summary: Get Provider Categories
      description: Get provider category slugs from Quaestio category facets.
      operationId: get_provider_categories_api_v1_providers_categories_get
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema: {}
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      security:
        - HTTPBearer: []
      x-qveris-visibility: public
      x-qveris-release-stage: published
  /search:
    post:
      tags:
        - Discovery
      summary: Discover capabilities
      description: Find ranked capabilities from a natural-language query. Discover is
        free. Results may include `expected_cost` and `billing_rule` so clients
        can estimate a later Call.
      operationId: search_api_v1_search_post
      responses:
        "200":
          description: Successful Response
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicSearchResponse"
              example:
                query: openweathermap.weather.execute.v1
                search_id: srch_01HZX9QK7J3M9T
                total: 1
                results:
                  - tool_id: openweathermap.weather.execute.v1
                    name: Current Weather
                    description: Get current weather data for a city.
                    provider_name: OpenWeatherMap
                    params:
                      - name: q
                        type: string
                        required: true
                        description: Location query accepted by the weather provider.
                    expected_cost: 5 credits per successful request
                    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
        "401":
          description: Unauthorized
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiError"
              example:
                status: failure
                status_code: 401
                message: Invalid API key
        "402":
          description: Insufficient credits
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicSearchResponse"
              example:
                query: openweathermap.weather.execute.v1
                search_id: srch_failed
                total: 0
                results: []
                error_message: Insufficient credits
                remaining_credits: 0
        "429":
          description: Too Many Requests
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiError"
              example:
                status: failure
                status_code: 429
                message: Rate limit exceeded. Please try again later.
      security:
        - HTTPBearer: []
      x-qveris-visibility: public
      x-qveris-release-stage: published
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublicSearchRequest"
            example:
              query: openweathermap.weather.execute.v1
              limit: 10
              session_id: sess_7Q9m
  /tools/by-ids:
    post:
      tags:
        - Tool Execution
      summary: Inspect capabilities by id
      description: Fetch full capability metadata for one or more tool ids. Inspect is
        free and returns the same capability shape as Discover, including
        parameter schema, examples, quality signals, and cost estimates.
      operationId: get_tools_by_ids_api_v1_tools_by_ids_post
      responses:
        "200":
          description: Successful Response
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicInspectResponse"
              example:
                search_id: srch_01HZX9QK7J3M9T
                total: 1
                results:
                  - tool_id: openweathermap.weather.execute.v1
                    name: Current Weather
                    description: Get current weather data for a city.
                    provider_name: OpenWeatherMap
                    params:
                      - name: q
                        type: string
                        required: true
                        description: Location query accepted by the weather provider.
                    examples:
                      sample_parameters:
                        q: London
                    expected_cost: 5 credits per successful request
                    billing_rule:
                      unit: request
                      amount_credits: 5
                    stats:
                      avg_execution_time_ms: 210.7
                      success_rate: 0.982
                remaining_credits: 995
        "401":
          description: Unauthorized
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiError"
              example:
                status: failure
                status_code: 401
                message: Invalid API key
        "429":
          description: Too Many Requests
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              example:
                status: failure
                status_code: 429
                message: Rate limit exceeded. Please try again later.
        "504":
          description: Upstream timeout
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiError"
              example:
                error: Request timeout
                remaining_credits: 995
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      security:
        - HTTPBearer: []
      x-qveris-visibility: public
      x-qveris-release-stage: published
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublicToolsByIdsRequest"
            example:
              tool_ids:
                - openweathermap.weather.execute.v1
              search_id: srch_01HZX9QK7J3M9T
              session_id: sess_7Q9m
  /tools/execute:
    post:
      tags:
        - Tool Execution
      summary: Call a capability
      description: 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.
      operationId: execute_api_v1_tools_execute_post
      security:
        - HTTPBearer: []
      parameters:
        - name: tool_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            description: Tool ID (optional if provided in request body)
            title: Tool Id
          description: Tool ID (optional if provided in request body)
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicExecuteToolResponse"
              example:
                execution_id: exec_01HZX9R2R4S2E
                result:
                  data:
                    temperature: 15.5
                    description: partly cloudy
                success: true
                error_message: null
                execution_time: 0.211
                billing:
                  summary: 5 credits per successful request
                  list_amount_credits: 5
                cost: 5
                remaining_credits: 990
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "401":
          description: Unauthorized
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiError"
              example:
                status: failure
                status_code: 401
                message: Invalid API key
                data:
                  guidance: Copy a valid API key from Account > API Keys and try again.
                  remaining_credits: null
        "402":
          description: Insufficient credits
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicExecuteToolResponse"
              example:
                execution_id: exec_01HZX9R2R4S2E
                result:
                  data: {}
                success: false
                error_message: Insufficient credits
                execution_time: 0.01
                remaining_credits: 0
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicExecuteToolResponse"
              example:
                execution_id: exec_01HZX9R2R4S2E
                result:
                  data: {}
                success: false
                error_message: Request validation failed
                details:
                  - type: value_error
                    loc:
                      - body
                      - respond_with
                    msg: Invalid projection
                    input: "fields:"
                execution_time: 0.01
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "429":
          description: Too Many Requests
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiError"
              example:
                status: failure
                status_code: 429
                message: Rate limit exceeded. Please try again later.
      x-qveris-visibility: public
      x-qveris-release-stage: published
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublicExecuteToolRequest"
            example:
              search_id: srch_01HZX9QK7J3M9T
              session_id: sess_7Q9m
              parameters:
                q: London
              max_response_size: 20480
  /tools/probe:
    post:
      tags:
        - Tool Execution
      summary: Probe a capability without executing it
      description: Validate candidate parameters and obtain a zero-cost quote before
        Call. The M1 `schema` and `quote` checks are implemented; `coverage` and
        `sample` return an explicit unknown verdict. Probe never executes the
        capability or consumes credits.
      operationId: probe_tool_api_v1_tools_probe_post
      security:
        - HTTPBearer: []
      parameters:
        - name: tool_id
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            description: Tool ID to validate
            title: Tool Id
          description: Tool ID to validate
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicToolProbeResponse"
              example:
                schema:
                  valid: true
                quote:
                  estimate_credits: 5
                  currency: credits
                  exact: true
                  basis: per_call
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "400":
          description: Invalid probe request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiError"
              example:
                error: ValidationError
                message: Request validation failed
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "401":
          description: Unauthorized
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiError"
              example:
                status: failure
                status_code: 401
                message: Invalid API key
        "404":
          description: Capability not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiError"
              example:
                error: HTTPException
                message: Tool not found
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "429":
          description: Too Many Requests
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current rate-limit window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix epoch seconds when the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds until the client should retry after a rate-limit response.
              schema:
                type: integer
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
          content:
            application/json:
              example:
                status: failure
                status_code: 429
                message: Rate limit exceeded. Please try again later.
        "502":
          description: Upstream unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiError"
              example:
                status: failure
                status_code: 502
                message: Tool probe service is temporarily unavailable
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
        "504":
          description: Upstream timeout
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiError"
              example:
                status: failure
                status_code: 504
                message: Tool probe request timed out
          headers:
            X-Qveris-Api-Version:
              description: Version of the published QVeris REST API contract.
              required: true
              schema:
                type: string
                const: 2026-07-30.1
      x-qveris-visibility: public
      x-qveris-release-stage: published
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublicToolProbeRequest"
            example:
              parameters:
                q: London
              checks:
                - schema
                - quote
              live_budget: none
components:
  schemas:
    APIResponse_CreditsLedgerItem_:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        status_code:
          type: integer
          title: Status Code
          default: 0
        data:
          anyOf:
            - $ref: "#/components/schemas/CreditsLedgerItem"
            - type: "null"
        message_key:
          anyOf:
            - type: string
            - type: "null"
          title: Message Key
      type: object
      required:
        - status
        - message
      title: APIResponse[CreditsLedgerItem]
    APIResponse_CreditsLedgerReadinessResponse_:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        status_code:
          type: integer
          title: Status Code
          default: 0
        data:
          anyOf:
            - $ref: "#/components/schemas/CreditsLedgerReadinessResponse"
            - type: "null"
        message_key:
          anyOf:
            - type: string
            - type: "null"
          title: Message Key
      type: object
      required:
        - status
        - message
      title: APIResponse[CreditsLedgerReadinessResponse]
    APIResponse_CreditsLedgerResponse_:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        status_code:
          type: integer
          title: Status Code
          default: 0
        data:
          anyOf:
            - $ref: "#/components/schemas/CreditsLedgerResponse"
            - type: "null"
        message_key:
          anyOf:
            - type: string
            - type: "null"
          title: Message Key
      type: object
      required:
        - status
        - message
      title: APIResponse[CreditsLedgerResponse]
    APIResponse_SettlementHistoryResponse_:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        status_code:
          type: integer
          title: Status Code
          default: 0
        data:
          anyOf:
            - $ref: "#/components/schemas/SettlementHistoryResponse"
            - type: "null"
        message_key:
          anyOf:
            - type: string
            - type: "null"
          title: Message Key
      type: object
      required:
        - status
        - message
      title: APIResponse[SettlementHistoryResponse]
    APIResponse_TokenVerificationResponse_:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        status_code:
          type: integer
          title: Status Code
          default: 0
        data:
          anyOf:
            - $ref: "#/components/schemas/TokenVerificationResponse"
            - type: "null"
        message_key:
          anyOf:
            - type: string
            - type: "null"
          title: Message Key
      type: object
      required:
        - status
        - message
      title: APIResponse[TokenVerificationResponse]
    APIResponse_UsageCreditsSpentResponse_:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        status_code:
          type: integer
          title: Status Code
          default: 0
        data:
          anyOf:
            - $ref: "#/components/schemas/UsageCreditsSpentResponse"
            - type: "null"
        message_key:
          anyOf:
            - type: string
            - type: "null"
          title: Message Key
      type: object
      required:
        - status
        - message
      title: APIResponse[UsageCreditsSpentResponse]
    APIResponse_UsageEventItem_:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        status_code:
          type: integer
          title: Status Code
          default: 0
        data:
          anyOf:
            - $ref: "#/components/schemas/UsageEventItem"
            - type: "null"
        message_key:
          anyOf:
            - type: string
            - type: "null"
          title: Message Key
      type: object
      required:
        - status
        - message
      title: APIResponse[UsageEventItem]
    APIResponse_UsageEventSummaryResponse_:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        status_code:
          type: integer
          title: Status Code
          default: 0
        data:
          anyOf:
            - $ref: "#/components/schemas/UsageEventSummaryResponse"
            - type: "null"
        message_key:
          anyOf:
            - type: string
            - type: "null"
          title: Message Key
      type: object
      required:
        - status
        - message
      title: APIResponse[UsageEventSummaryResponse]
    APIResponse_UsageEventsResponse_:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        status_code:
          type: integer
          title: Status Code
          default: 0
        data:
          anyOf:
            - $ref: "#/components/schemas/UsageEventsResponse"
            - type: "null"
        message_key:
          anyOf:
            - type: string
            - type: "null"
          title: Message Key
      type: object
      required:
        - status
        - message
      title: APIResponse[UsageEventsResponse]
    APIResponse_dict_:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        status_code:
          type: integer
          title: Status Code
          default: 0
        data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Data
        message_key:
          anyOf:
            - type: string
            - type: "null"
          title: Message Key
      type: object
      required:
        - status
        - message
      title: APIResponse[dict]
    CreditsLedgerItem:
      properties:
        id:
          type: string
          title: Id
        entry_type:
          type: string
          title: Entry Type
        amount_credits:
          type: number
          title: Amount Credits
        source_system:
          type: string
          title: Source System
        source_ref_type:
          anyOf:
            - type: string
            - type: "null"
          title: Source Ref Type
        source_ref_id:
          anyOf:
            - type: string
            - type: "null"
          title: Source Ref Id
        execution_id:
          anyOf:
            - type: string
            - type: "null"
          title: Execution Id
        pre_settlement_bill:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Pre Settlement Bill
        settlement_result:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Settlement Result
        balance_before:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Balance Before
        balance_after:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Balance After
        ledger_metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Ledger Metadata
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - entry_type
        - amount_credits
        - source_system
        - created_at
      title: CreditsLedgerItem
    CreditsLedgerReadinessEntity:
      properties:
        entity_type:
          type: string
          title: Entity Type
        legacy_count:
          type: integer
          title: Legacy Count
        legacy_amount_credits:
          type: number
          title: Legacy Amount Credits
        ledger_count:
          type: integer
          title: Ledger Count
        ledger_amount_credits:
          type: number
          title: Ledger Amount Credits
        missing_count:
          type: integer
          title: Missing Count
        extra_count:
          type: integer
          title: Extra Count
        amount_delta_credits:
          type: number
          title: Amount Delta Credits
        ready:
          type: boolean
          title: Ready
      type: object
      required:
        - entity_type
        - legacy_count
        - legacy_amount_credits
        - ledger_count
        - ledger_amount_credits
        - missing_count
        - extra_count
        - amount_delta_credits
        - ready
      title: CreditsLedgerReadinessEntity
    CreditsLedgerReadinessResponse:
      properties:
        checked_at:
          type: string
          format: date-time
          title: Checked At
        start_date:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Start Date
        end_date:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: End Date
        scope:
          type: string
          title: Scope
        recommended_read_mode:
          type: string
          title: Recommended Read Mode
        ready:
          type: boolean
          title: Ready
        legacy_total_count:
          type: integer
          title: Legacy Total Count
        legacy_total_amount_credits:
          type: number
          title: Legacy Total Amount Credits
        ledger_total_count:
          type: integer
          title: Ledger Total Count
        ledger_total_amount_credits:
          type: number
          title: Ledger Total Amount Credits
        entities:
          items:
            $ref: "#/components/schemas/CreditsLedgerReadinessEntity"
          type: array
          title: Entities
      type: object
      required:
        - checked_at
        - scope
        - recommended_read_mode
        - ready
        - legacy_total_count
        - legacy_total_amount_credits
        - ledger_total_count
        - ledger_total_amount_credits
        - entities
      title: CreditsLedgerReadinessResponse
    CreditsLedgerResponse:
      properties:
        items:
          items:
            $ref: "#/components/schemas/CreditsLedgerItem"
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
        summary:
          anyOf:
            - $ref: "#/components/schemas/CreditsLedgerSummary"
            - type: "null"
      type: object
      required:
        - items
        - total
        - page
        - page_size
      title: CreditsLedgerResponse
    CreditsLedgerSummary:
      properties:
        start_date:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Start Date
        end_date:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: End Date
        bucket:
          type: string
          title: Bucket
        total_entries:
          type: integer
          title: Total Entries
        consume_count:
          type: integer
          title: Consume Count
        grant_count:
          type: integer
          title: Grant Count
        consumed_credits:
          type: number
          title: Consumed Credits
        granted_credits:
          type: number
          title: Granted Credits
        net_amount_credits:
          type: number
          title: Net Amount Credits
        max_amount_items:
          items:
            $ref: "#/components/schemas/CreditsLedgerItem"
          type: array
          title: Max Amount Items
        buckets:
          items:
            $ref: "#/components/schemas/CreditsLedgerSummaryBucket"
          type: array
          title: Buckets
      type: object
      required:
        - bucket
        - total_entries
        - consume_count
        - grant_count
        - consumed_credits
        - granted_credits
        - net_amount_credits
        - max_amount_items
        - buckets
      title: CreditsLedgerSummary
    CreditsLedgerSummaryBucket:
      properties:
        bucket_start:
          type: string
          format: date-time
          title: Bucket Start
        entry_count:
          type: integer
          title: Entry Count
        consume_count:
          type: integer
          title: Consume Count
        grant_count:
          type: integer
          title: Grant Count
        consumed_credits:
          type: number
          title: Consumed Credits
        granted_credits:
          type: number
          title: Granted Credits
        net_amount_credits:
          type: number
          title: Net Amount Credits
      type: object
      required:
        - bucket_start
        - entry_count
        - consume_count
        - grant_count
        - consumed_credits
        - granted_credits
        - net_amount_credits
      title: CreditsLedgerSummaryBucket
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: "#/components/schemas/ValidationError"
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    OAuthAccessTokenResponse:
      properties:
        access_token:
          type: string
          title: Access Token
        token_type:
          type: string
          const: Bearer
          title: Token Type
        expires_in:
          type: integer
          exclusiveMinimum: 0
          title: Expires In
        scope:
          type: string
          title: Scope
        resource:
          type: string
          title: Resource
        refresh_token:
          anyOf:
            - type: string
            - type: "null"
          title: Refresh Token
        refresh_token_expires_in:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
            - type: "null"
          title: Refresh Token Expires In
        id_token:
          anyOf:
            - type: string
            - type: "null"
          title: Id Token
        tool_api_key:
          anyOf:
            - type: string
            - type: "null"
          title: Tool Api Key
        tool_api_key_name:
          anyOf:
            - type: string
            - type: "null"
          title: Tool Api Key Name
      type: object
      required:
        - access_token
        - token_type
        - expires_in
        - scope
        - resource
      title: OAuthAccessTokenResponse
      description: Authorization Code, Device Code, or Refresh Token success response.
    OAuthDelegationActor:
      properties:
        client_id:
          type: string
          title: Client Id
      additionalProperties: false
      type: object
      required:
        - client_id
      title: OAuthDelegationActor
      description: Confidential Agent Runtime that requested a delegation token.
    OAuthDelegationConstraints:
      properties:
        model:
          anyOf:
            - type: string
              maxLength: 128
            - type: "null"
          title: Model
        tool_ids:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 100
            - type: "null"
          title: Tool Ids
        provider_ids:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 100
            - type: "null"
          title: Provider Ids
        run_id:
          anyOf:
            - type: string
              maxLength: 128
            - type: "null"
          title: Run Id
        max_credits:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
            - type: "null"
          title: Max Credits
      additionalProperties: false
      type: object
      title: OAuthDelegationConstraints
    OAuthDeviceAuthorizationResponse:
      properties:
        device_code:
          type: string
          title: Device Code
          description: Secret code used only to poll the token endpoint.
        user_code:
          type: string
          title: User Code
          description: Short code displayed to and verified by the user.
        verification_uri:
          type: string
          title: Verification Uri
          description: Browser URL where the user approves the request.
        verification_uri_complete:
          type: string
          title: Verification Uri Complete
          description: Verification URL with the user code prefilled.
        expires_in:
          type: integer
          exclusiveMinimum: 0
          title: Expires In
          description: Device and user code lifetime in seconds.
        interval:
          type: integer
          exclusiveMinimum: 0
          title: Interval
          description: Minimum token polling interval in seconds.
      additionalProperties: false
      type: object
      required:
        - device_code
        - user_code
        - verification_uri
        - verification_uri_complete
        - expires_in
        - interval
      title: OAuthDeviceAuthorizationResponse
      description: RFC 8628 device authorization response.
    OAuthErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: Stable OAuth error code.
        error_description:
          type: string
          title: Error Description
          description: Human-readable error detail.
        error_uri:
          anyOf:
            - type: string
            - type: "null"
          title: Error Uri
          description: Optional error documentation URI.
      additionalProperties: false
      type: object
      required:
        - error
        - error_description
      title: OAuthErrorResponse
      description: RFC 6749/RFC 8693 error response.
    OAuthIntrospectionActiveResponse:
      properties:
        active:
          type: boolean
          const: true
          title: Active
        token_type:
          type: string
          const: Bearer
          title: Token Type
        scope:
          type: string
          title: Scope
        client_id:
          type: string
          title: Client Id
        sub:
          type: string
          title: Sub
        token_use:
          type: string
          enum:
            - access
            - delegation
          title: Token Use
        exp:
          type: integer
          title: Exp
        iat:
          type: integer
          title: Iat
        nbf:
          type: integer
          title: Nbf
        aud:
          type: string
          title: Aud
        iss:
          type: string
          title: Iss
        jti:
          type: string
          title: Jti
        actor:
          anyOf:
            - $ref: "#/components/schemas/OAuthDelegationActor"
            - type: "null"
        parent_jti:
          anyOf:
            - type: string
            - type: "null"
          title: Parent Jti
        delegation:
          anyOf:
            - $ref: "#/components/schemas/OAuthDelegationConstraints"
            - type: "null"
      type: object
      required:
        - active
        - token_type
        - scope
        - client_id
        - sub
        - token_use
        - exp
        - iat
        - nbf
        - aud
        - iss
        - jti
      title: OAuthIntrospectionActiveResponse
    OAuthIntrospectionInactiveResponse:
      properties:
        active:
          type: boolean
          const: false
          title: Active
      additionalProperties: false
      type: object
      required:
        - active
      title: OAuthIntrospectionInactiveResponse
    OAuthRateLimitResponse:
      properties:
        status:
          type: string
          const: failure
          title: Status
        status_code:
          type: integer
          const: 429
          title: Status Code
        message:
          type: string
          title: Message
        data:
          type: "null"
          title: Data
      additionalProperties: false
      type: object
      required:
        - status
        - status_code
        - message
      title: OAuthRateLimitResponse
      description: Structured response returned when Device Authorization is throttled.
    OAuthTokenExchangeResponse:
      properties:
        access_token:
          type: string
          title: Access Token
        issued_token_type:
          type: string
          const: urn:ietf:params:oauth:token-type:access_token
          title: Issued Token Type
        token_type:
          type: string
          const: Bearer
          title: Token Type
        expires_in:
          type: integer
          maximum: 600
          exclusiveMinimum: 0
          title: Expires In
        scope:
          type: string
          title: Scope
        resource:
          type: string
          title: Resource
        constraints:
          $ref: "#/components/schemas/OAuthDelegationConstraints"
      additionalProperties: false
      type: object
      required:
        - access_token
        - issued_token_type
        - token_type
        - expires_in
        - scope
        - resource
      title: OAuthTokenExchangeResponse
      description: "Successful Agent-to-QVeris token exchange. This schema
        deliberately does not contain refresh_token: delegation tokens cannot be
        refreshed."
      examples:
        - access_token: eyJhbGciOiJSUzI1NiIs...
          constraints:
            max_credits: 25
            provider_ids:
              - openweathermap
            run_id: run-01J0QVERIS
            tool_ids:
              - openweathermap.weather.execute.v1
          expires_in: 600
          issued_token_type: urn:ietf:params:oauth:token-type:access_token
          resource: https://api.qveris.ai/tools
          scope: tools.inspect tools.execute
          token_type: Bearer
    PublicApiMetadata:
      properties:
        contract_version:
          type: string
          title: Contract Version
          description: Version of the published QVeris REST API contract.
          examples:
            - 2026-07-30.1
      additionalProperties: false
      type: object
      required:
        - contract_version
      title: PublicApiMetadata
      description: Unauthenticated metadata used by API clients for compatibility checks.
    SettlementHistoryItem:
      properties:
        id:
          type: string
          title: Id
        source:
          type: string
          title: Source
        entry_type:
          type: string
          title: Entry Type
        amount_credits:
          type: number
          title: Amount Credits
        source_system:
          type: string
          title: Source System
        source_ref_type:
          anyOf:
            - type: string
            - type: "null"
          title: Source Ref Type
        source_ref_id:
          anyOf:
            - type: string
            - type: "null"
          title: Source Ref Id
        execution_id:
          anyOf:
            - type: string
            - type: "null"
          title: Execution Id
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        display_target:
          anyOf:
            - type: string
            - type: "null"
          title: Display Target
        billing_summary:
          anyOf:
            - type: string
            - type: "null"
          title: Billing Summary
        billing_snapshot_status:
          anyOf:
            - type: string
            - type: "null"
          title: Billing Snapshot Status
        details_available:
          type: boolean
          title: Details Available
          default: true
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - source
        - entry_type
        - amount_credits
        - source_system
        - created_at
      title: SettlementHistoryItem
    SettlementHistoryResponse:
      properties:
        items:
          items:
            $ref: "#/components/schemas/SettlementHistoryItem"
          type: array
          title: Items
        next_cursor:
          anyOf:
            - type: string
            - type: "null"
          title: Next Cursor
        has_more:
          type: boolean
          title: Has More
        page_size:
          type: integer
          title: Page Size
      type: object
      required:
        - items
        - has_more
        - page_size
      title: SettlementHistoryResponse
    TokenVerificationResponse:
      properties:
        is_valid:
          type: boolean
          title: Is Valid
        is_expired:
          type: boolean
          title: Is Expired
        payload:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Payload
      type: object
      required:
        - is_valid
        - is_expired
      title: TokenVerificationResponse
    UsageCreditsSpentResponse:
      properties:
        total_credits:
          type: number
          title: Total Credits
        start_date:
          anyOf:
            - type: string
            - type: "null"
          title: Start Date
        end_date:
          anyOf:
            - type: string
            - type: "null"
          title: End Date
      type: object
      required:
        - total_credits
      title: UsageCreditsSpentResponse
    UsageEventApiKey:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        masked_value:
          type: string
          title: Masked Value
      type: object
      required:
        - id
        - name
        - masked_value
      title: UsageEventApiKey
    UsageEventItem:
      properties:
        id:
          type: string
          title: Id
        event_type:
          type: string
          title: Event Type
        source_system:
          type: string
          title: Source System
        source_ref_type:
          anyOf:
            - type: string
            - type: "null"
          title: Source Ref Type
        source_ref_id:
          anyOf:
            - type: string
            - type: "null"
          title: Source Ref Id
        credential_type:
          anyOf:
            - type: string
            - type: "null"
          title: Credential Type
        api_key:
          anyOf:
            - $ref: "#/components/schemas/UsageEventApiKey"
            - type: "null"
        api_key_attribution_status:
          type: string
          title: Api Key Attribution Status
          default: historical_unknown
        session_id:
          anyOf:
            - type: string
            - type: "null"
          title: Session Id
        search_id:
          anyOf:
            - type: string
            - type: "null"
          title: Search Id
        execution_id:
          anyOf:
            - type: string
            - type: "null"
          title: Execution Id
        tool_id:
          anyOf:
            - type: string
            - type: "null"
          title: Tool Id
        model:
          anyOf:
            - type: string
            - type: "null"
          title: Model
        query:
          anyOf:
            - type: string
            - type: "null"
          title: Query
        success:
          type: boolean
          title: Success
        charge_outcome:
          type: string
          title: Charge Outcome
        error_message:
          anyOf:
            - type: string
            - type: "null"
          title: Error Message
        duration_ms:
          anyOf:
            - type: number
            - type: "null"
          title: Duration Ms
        request_payload:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Request Payload
        response_payload_summary:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Response Payload Summary
        execution_outcome:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Execution Outcome
        outcome_schema_version:
          anyOf:
            - type: string
            - type: "null"
          title: Outcome Schema Version
        transport_success:
          anyOf:
            - type: boolean
            - type: "null"
          title: Transport Success
        provider_success:
          anyOf:
            - type: boolean
            - type: "null"
          title: Provider Success
        result_valid:
          anyOf:
            - type: boolean
            - type: "null"
          title: Result Valid
        billable_success:
          anyOf:
            - type: boolean
            - type: "null"
          title: Billable Success
        outcome:
          anyOf:
            - type: string
            - type: "null"
          title: Outcome
        outcome_status:
          anyOf:
            - type: string
            - type: "null"
          title: Outcome Status
        reason_code:
          anyOf:
            - type: string
            - type: "null"
          title: Reason Code
        outcome_message:
          anyOf:
            - type: string
            - type: "null"
          title: Outcome Message
        provider_status_code:
          anyOf:
            - type: string
            - type: "null"
          title: Provider Status Code
        provider_status_message:
          anyOf:
            - type: string
            - type: "null"
          title: Provider Status Message
        http_status_code:
          anyOf:
            - type: integer
            - type: "null"
          title: Http Status Code
        valid_result_count:
          anyOf:
            - type: integer
            - type: "null"
          title: Valid Result Count
        raw_result_count:
          anyOf:
            - type: integer
            - type: "null"
          title: Raw Result Count
        chargeable_quantity:
          anyOf:
            - type: number
            - type: "null"
          title: Chargeable Quantity
        retryable:
          anyOf:
            - type: boolean
            - type: "null"
          title: Retryable
        display_severity:
          anyOf:
            - type: string
            - type: "null"
          title: Display Severity
        billing_snapshot_status:
          anyOf:
            - type: string
            - type: "null"
          title: Billing Snapshot Status
        billing_rule_snapshot:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Billing Rule Snapshot
        pre_settlement_bill:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Pre Settlement Bill
        settlement_result:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Settlement Result
        requested_amount_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Requested Amount Credits
        actual_amount_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Actual Amount Credits
        credits_ledger_entry_id:
          anyOf:
            - type: string
            - type: "null"
          title: Credits Ledger Entry Id
        display_target:
          anyOf:
            - type: string
            - type: "null"
          title: Display Target
        billing_unit:
          anyOf:
            - type: string
            - type: "null"
          title: Billing Unit
        unit_price_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Unit Price Credits
        quantity:
          anyOf:
            - type: number
            - type: "null"
          title: Quantity
        list_amount_credits:
          anyOf:
            - type: number
            - type: "null"
          title: List Amount Credits
        minimum_charge_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Minimum Charge Credits
        pricing_profile_id:
          anyOf:
            - type: string
            - type: "null"
          title: Pricing Profile Id
        billing_summary:
          anyOf:
            - type: string
            - type: "null"
          title: Billing Summary
        pre_settlement_amount_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Pre Settlement Amount Credits
        settled_amount_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Settled Amount Credits
        pricing_context_id:
          anyOf:
            - type: string
            - type: "null"
          title: Pricing Context Id
        harbor_snapshot_id:
          anyOf:
            - type: string
            - type: "null"
          title: Harbor Snapshot Id
        harbor_snapshot_version:
          anyOf:
            - type: string
            - type: "null"
          title: Harbor Snapshot Version
        resolver_version:
          anyOf:
            - type: string
            - type: "null"
          title: Resolver Version
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - event_type
        - source_system
        - success
        - charge_outcome
        - created_at
      title: UsageEventItem
    UsageEventSummaryItem:
      properties:
        id:
          type: string
          title: Id
        event_type:
          type: string
          title: Event Type
        source_system:
          type: string
          title: Source System
        source_ref_type:
          anyOf:
            - type: string
            - type: "null"
          title: Source Ref Type
        source_ref_id:
          anyOf:
            - type: string
            - type: "null"
          title: Source Ref Id
        credential_type:
          anyOf:
            - type: string
            - type: "null"
          title: Credential Type
        api_key:
          anyOf:
            - $ref: "#/components/schemas/UsageEventApiKey"
            - type: "null"
        api_key_attribution_status:
          type: string
          title: Api Key Attribution Status
          default: historical_unknown
        session_id:
          anyOf:
            - type: string
            - type: "null"
          title: Session Id
        search_id:
          anyOf:
            - type: string
            - type: "null"
          title: Search Id
        execution_id:
          anyOf:
            - type: string
            - type: "null"
          title: Execution Id
        tool_id:
          anyOf:
            - type: string
            - type: "null"
          title: Tool Id
        model:
          anyOf:
            - type: string
            - type: "null"
          title: Model
        query:
          anyOf:
            - type: string
            - type: "null"
          title: Query
        success:
          type: boolean
          title: Success
        charge_outcome:
          type: string
          title: Charge Outcome
        error_message:
          anyOf:
            - type: string
            - type: "null"
          title: Error Message
        duration_ms:
          anyOf:
            - type: number
            - type: "null"
          title: Duration Ms
        transport_success:
          anyOf:
            - type: boolean
            - type: "null"
          title: Transport Success
        provider_success:
          anyOf:
            - type: boolean
            - type: "null"
          title: Provider Success
        result_valid:
          anyOf:
            - type: boolean
            - type: "null"
          title: Result Valid
        billable_success:
          anyOf:
            - type: boolean
            - type: "null"
          title: Billable Success
        outcome:
          anyOf:
            - type: string
            - type: "null"
          title: Outcome
        outcome_status:
          anyOf:
            - type: string
            - type: "null"
          title: Outcome Status
        reason_code:
          anyOf:
            - type: string
            - type: "null"
          title: Reason Code
        outcome_message:
          anyOf:
            - type: string
            - type: "null"
          title: Outcome Message
        provider_status_code:
          anyOf:
            - type: string
            - type: "null"
          title: Provider Status Code
        provider_status_message:
          anyOf:
            - type: string
            - type: "null"
          title: Provider Status Message
        http_status_code:
          anyOf:
            - type: integer
            - type: "null"
          title: Http Status Code
        valid_result_count:
          anyOf:
            - type: integer
            - type: "null"
          title: Valid Result Count
        raw_result_count:
          anyOf:
            - type: integer
            - type: "null"
          title: Raw Result Count
        chargeable_quantity:
          anyOf:
            - type: number
            - type: "null"
          title: Chargeable Quantity
        retryable:
          anyOf:
            - type: boolean
            - type: "null"
          title: Retryable
        display_severity:
          anyOf:
            - type: string
            - type: "null"
          title: Display Severity
        billing_snapshot_status:
          anyOf:
            - type: string
            - type: "null"
          title: Billing Snapshot Status
        requested_amount_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Requested Amount Credits
        actual_amount_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Actual Amount Credits
        credits_ledger_entry_id:
          anyOf:
            - type: string
            - type: "null"
          title: Credits Ledger Entry Id
        display_target:
          anyOf:
            - type: string
            - type: "null"
          title: Display Target
        billing_unit:
          anyOf:
            - type: string
            - type: "null"
          title: Billing Unit
        unit_price_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Unit Price Credits
        quantity:
          anyOf:
            - type: number
            - type: "null"
          title: Quantity
        list_amount_credits:
          anyOf:
            - type: number
            - type: "null"
          title: List Amount Credits
        minimum_charge_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Minimum Charge Credits
        pricing_profile_id:
          anyOf:
            - type: string
            - type: "null"
          title: Pricing Profile Id
        billing_summary:
          anyOf:
            - type: string
            - type: "null"
          title: Billing Summary
        pre_settlement_amount_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Pre Settlement Amount Credits
        settled_amount_credits:
          anyOf:
            - type: number
            - type: "null"
          title: Settled Amount Credits
        pricing_context_id:
          anyOf:
            - type: string
            - type: "null"
          title: Pricing Context Id
        harbor_snapshot_id:
          anyOf:
            - type: string
            - type: "null"
          title: Harbor Snapshot Id
        harbor_snapshot_version:
          anyOf:
            - type: string
            - type: "null"
          title: Harbor Snapshot Version
        resolver_version:
          anyOf:
            - type: string
            - type: "null"
          title: Resolver Version
        details_available:
          type: boolean
          title: Details Available
          default: true
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - event_type
        - source_system
        - success
        - charge_outcome
        - created_at
      title: UsageEventSummaryItem
    UsageEventSummaryResponse:
      properties:
        items:
          items:
            $ref: "#/components/schemas/UsageEventSummaryItem"
          type: array
          title: Items
        next_cursor:
          anyOf:
            - type: string
            - type: "null"
          title: Next Cursor
        has_more:
          type: boolean
          title: Has More
        page_size:
          type: integer
          title: Page Size
      type: object
      required:
        - items
        - has_more
        - page_size
      title: UsageEventSummaryResponse
    UsageEventsResponse:
      properties:
        items:
          items:
            $ref: "#/components/schemas/UsageEventItem"
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
        summary:
          anyOf:
            - $ref: "#/components/schemas/UsageEventsSummary"
            - type: "null"
      type: object
      required:
        - items
        - total
        - page
        - page_size
      title: UsageEventsResponse
    UsageEventsSummary:
      properties:
        start_date:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Start Date
        end_date:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: End Date
        bucket:
          type: string
          title: Bucket
        total_count:
          type: integer
          title: Total Count
        success_count:
          type: integer
          title: Success Count
        failure_count:
          type: integer
          title: Failure Count
        charge_outcome_counts:
          additionalProperties:
            type: integer
          type: object
          title: Charge Outcome Counts
        pre_settlement_credits:
          type: number
          title: Pre Settlement Credits
        settled_credits:
          type: number
          title: Settled Credits
        max_charge_items:
          items:
            $ref: "#/components/schemas/UsageEventItem"
          type: array
          title: Max Charge Items
        buckets:
          items:
            $ref: "#/components/schemas/UsageEventsSummaryBucket"
          type: array
          title: Buckets
      type: object
      required:
        - bucket
        - total_count
        - success_count
        - failure_count
        - charge_outcome_counts
        - pre_settlement_credits
        - settled_credits
        - max_charge_items
        - buckets
      title: UsageEventsSummary
    UsageEventsSummaryBucket:
      properties:
        bucket_start:
          type: string
          format: date-time
          title: Bucket Start
        total_count:
          type: integer
          title: Total Count
        success_count:
          type: integer
          title: Success Count
        failure_count:
          type: integer
          title: Failure Count
        charged_count:
          type: integer
          title: Charged Count
        included_count:
          type: integer
          title: Included Count
        failed_not_charged_count:
          type: integer
          title: Failed Not Charged Count
        failed_charged_review_count:
          type: integer
          title: Failed Charged Review Count
        pre_settlement_credits:
          type: number
          title: Pre Settlement Credits
        settled_credits:
          type: number
          title: Settled Credits
      type: object
      required:
        - bucket_start
        - total_count
        - success_count
        - failure_count
        - charged_count
        - included_count
        - failed_not_charged_count
        - failed_charged_review_count
        - pre_settlement_credits
        - settled_credits
      title: UsageEventsSummaryBucket
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    PublicApiError:
      type: object
      title: PublicApiError
      additionalProperties: true
      properties:
        status:
          type: string
          examples:
            - failure
        status_code:
          type: integer
        message:
          type: string
        error:
          type: string
        error_message:
          type: string
        data:
          anyOf:
            - type: object
              additionalProperties: true
            - type: "null"
        remaining_credits:
          anyOf:
            - type: number
            - type: "null"
        search_id:
          anyOf:
            - type: string
            - type: "null"
        execution_id:
          anyOf:
            - type: string
            - type: "null"
        total:
          type: integer
        results:
          type: array
          items:
            type: object
    PublicSearchRequest:
      type: object
      title: PublicSearchRequest
      required:
        - query
      properties:
        query:
          type: string
          description: Natural-language capability query or an exact tool ID for
            deterministic lookup.
          minLength: 1
        limit:
          type: integer
          description: Maximum number of ranked results to return.
          default: 20
          minimum: 1
          maximum: 100
        session_id:
          type: string
          description: Optional tracking and pricing-context identifier. It does not
            promise a cache hit.
        view:
          type: string
          enum:
            - routing
            - full
          description: Response projection. `routing` returns compact routing cards
            (`tool_id`, `capability`, `cost_class`, `reliability`,
            `as_of_support`) sized for model context; `full` or omitted returns
            the complete result shape, byte-identical to previous releases.
        lang:
          type: string
          enum:
            - zh
            - en
          description: Response language. When omitted the service negotiates from the
            `Accept-Language` header.
    PublicToolsByIdsRequest:
      type: object
      title: PublicToolsByIdsRequest
      required:
        - tool_ids
      properties:
        tool_ids:
          type: array
          items:
            type: string
          minItems: 1
          description: Capability ids returned by Discover.
        search_id:
          type: string
          description: Search id that returned these capabilities, when available.
        session_id:
          type: string
          description: Optional tracking and pricing-context identifier. It does not
            promise a cache hit.
        view:
          type: string
          enum:
            - full
            - lean
          description: Response projection. `lean` trims per-capability metadata for model
            context; `full` or omitted returns the complete result shape.
    PublicToolProbeRequest:
      type: object
      title: PublicToolProbeRequest
      properties:
        parameters:
          type: object
          additionalProperties: true
          default: {}
          description: Candidate parameters to validate without executing the capability.
        checks:
          type: array
          items:
            type: string
            enum:
              - schema
              - quote
              - coverage
              - sample
          minItems: 1
          default:
            - schema
        live_budget:
          type: string
          enum:
            - none
            - metadata
            - sampled
          default: none
          description: M1 is zero-cost; every value avoids an upstream tool execution.
    PublicProbeSchemaViolation:
      type: object
      title: PublicProbeSchemaViolation
      required:
        - type
        - message
      additionalProperties: false
      properties:
        param:
          anyOf:
            - type: string
            - type: "null"
        type:
          type: string
        message:
          type: string
    PublicProbeSchemaResult:
      type: object
      title: PublicProbeSchemaResult
      required:
        - valid
      additionalProperties: false
      properties:
        valid:
          type: boolean
        violations:
          anyOf:
            - type: array
              items:
                $ref: "#/components/schemas/PublicProbeSchemaViolation"
            - type: "null"
        note:
          anyOf:
            - type: string
            - type: "null"
    PublicProbeQuoteResult:
      type: object
      title: PublicProbeQuoteResult
      required:
        - currency
        - exact
      additionalProperties: false
      properties:
        estimate_credits:
          anyOf:
            - type: number
            - type: "null"
        currency:
          type: string
          enum:
            - credits
        exact:
          type: boolean
        basis:
          anyOf:
            - type: string
            - type: "null"
        detail:
          anyOf:
            - type: object
              additionalProperties: true
            - type: "null"
    PublicProbeUnknownResult:
      type: object
      title: PublicProbeUnknownResult
      required:
        - verdict
        - reason
      additionalProperties: false
      properties:
        verdict:
          type: string
          enum:
            - unknown
        reason:
          type: string
    PublicToolProbeResponse:
      type: object
      title: PublicToolProbeResponse
      additionalProperties: false
      properties:
        schema:
          $ref: "#/components/schemas/PublicProbeSchemaResult"
        quote:
          $ref: "#/components/schemas/PublicProbeQuoteResult"
        coverage:
          $ref: "#/components/schemas/PublicProbeUnknownResult"
        sample:
          $ref: "#/components/schemas/PublicProbeUnknownResult"
    PublicExecuteToolRequest:
      type: object
      title: PublicExecuteToolRequest
      required:
        - parameters
      properties:
        tool_id:
          type: string
          description: Capability id. Optional when supplied as the `tool_id` query
            parameter.
        search_id:
          type: string
          description: Search id that returned the selected capability.
        session_id:
          type: string
          description: Optional tracking and pricing-context identifier. If omitted, the
            service may use the execution id.
        parameters:
          type: object
          additionalProperties: true
          description: Capability-specific parameters validated by the selected tool schema.
        max_response_size:
          type: integer
          default: 20480
          description: Maximum response payload bytes before truncation. Use -1 for no
            limit.
        respond_with:
          type: string
          pattern: ^(full|summary|fields:.+)$
          description: Server-side result projection. `full` (default) returns the
            complete result, byte-identical to previous releases.
            `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` returns the
            response schema, size/row statistics, and a `full_content_file_url`
            for the complete payload.
    PublicToolParameter:
      type: object
      title: PublicToolParameter
      properties:
        name:
          type: string
        type:
          type: string
        required:
          type: boolean
        description:
          type: string
        enum:
          type: array
          items:
            type: string
      required:
        - name
        - type
        - required
    PublicToolStats:
      type: object
      title: PublicToolStats
      properties:
        avg_execution_time_ms:
          type:
            - number
            - "null"
        success_rate:
          type:
            - number
            - "null"
        sample_count:
          type: integer
          minimum: 0
        quality_sample_count:
          type: integer
          minimum: 0
        metrics_sample_count:
          type: integer
          minimum: 0
        success_rate_sample_count:
          type: integer
          minimum: 0
        latency_sample_count:
          type: integer
          minimum: 0
        minimum_sample_count:
          type: integer
          minimum: 1
        success_rate_minimum_sample_count:
          type: integer
          minimum: 1
        latency_minimum_sample_count:
          type: integer
          minimum: 1
        data_status:
          type: string
          enum:
            - available
            - insufficient
            - stale
            - unavailable
        quality_data_status:
          type: string
          enum:
            - available
            - insufficient
            - stale
            - unavailable
        success_rate_status:
          type: string
          enum:
            - available
            - insufficient
            - stale
            - unavailable
        latency_status:
          type: string
          enum:
            - available
            - insufficient
            - stale
            - unavailable
        metric_window:
          type: string
        window:
          type: string
        window_label:
          type: string
        window_start:
          type: string
          format: date-time
        window_end:
          type: string
          format: date-time
        metrics_updated_at:
          type: string
          format: date-time
        last_checked_at:
          type: string
          format: date-time
    PublicBillingRule:
      type: object
      title: PublicBillingRule
      additionalProperties: true
      description: Capability billing rule used for pre-call estimation. Final
        settlement is reflected in usage audit and credits ledger endpoints.
    PublicToolCategory:
      type: object
      title: PublicToolCategory
      additionalProperties: true
      description: Category/tag attached to a capability.
      properties:
        slug:
          type: string
        name:
          type: string
        description:
          type: string
    PublicCapabilityTag:
      type: object
      title: PublicCapabilityTag
      additionalProperties: true
      description: Coverage tag attached to a capability descriptor (e.g. market coverage).
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        description:
          type: string
    PublicToolCapability:
      type: object
      title: PublicToolCapability
      additionalProperties: true
      description: Standardized capability descriptor attached to a capability result
        (e.g. MKT.BARS.ADJUSTED with market coverage tags).
      properties:
        id:
          type: string
        tag:
          type: array
          items:
            $ref: "#/components/schemas/PublicCapabilityTag"
    PublicCapabilityResult:
      type: object
      title: PublicCapabilityResult
      additionalProperties: false
      required:
        - tool_id
      properties:
        tool_id:
          type: string
        name:
          type: string
        tool_name:
          type: string
        description:
          type: string
        provider_id:
          type: string
        provider_name:
          type: string
        provider_description:
          type: string
        category:
          type: string
        categories:
          type: array
          items:
            anyOf:
              - $ref: "#/components/schemas/PublicToolCategory"
              - type: string
          description: Categories/tags attached to the capability. Current responses
            return category objects; legacy responses returned plain strings.
        capabilities:
          type: array
          items:
            $ref: "#/components/schemas/PublicToolCapability"
          description: Standardized capability descriptors with coverage tags.
        region:
          type: string
        score:
          type: number
        why_recommended:
          type: string
          description: Human-readable explanation of why this capability was recommended
            for the query. Returned by Discover.
        params:
          type: array
          items:
            $ref: "#/components/schemas/PublicToolParameter"
        examples:
          type: object
          additionalProperties: true
        stats:
          $ref: "#/components/schemas/PublicToolStats"
        expected_cost:
          type: string
          description: Pre-call cost estimate returned by Discover/Inspect when available.
        cost:
          anyOf:
            - type: number
            - type: string
          description: Legacy cost estimate. Prefer `expected_cost` and `billing_rule` for
            pre-call display.
        billing_rule:
          $ref: "#/components/schemas/PublicBillingRule"
        calls_count:
          type: string
        capability:
          type: string
          description: "Compact capability summary. Returned instead of the full
            descriptor fields when the request sets `view: routing`."
        cost_class:
          type: string
          description: Coarse cost tier (e.g. `low`). Returned by the `routing` view.
        reliability:
          type: string
          description: Coarse reliability grade (e.g. `A`). Returned by the `routing` view.
        as_of_support:
          type: boolean
          description: Whether the capability supports as-of/point-in-time queries.
            Returned by the `routing` view.
    PublicSearchResponse:
      type: object
      title: PublicSearchResponse
      additionalProperties: false
      required:
        - query
        - search_id
        - total
        - results
      properties:
        query:
          type: string
        search_id:
          type: string
        total:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/PublicCapabilityResult"
        elapsed_time_ms:
          type: number
        remaining_credits:
          anyOf:
            - type: number
            - type: "null"
        error_message:
          anyOf:
            - type: string
            - type: "null"
    PublicInspectResponse:
      type: object
      title: PublicInspectResponse
      additionalProperties: false
      required:
        - search_id
        - total
        - results
      properties:
        search_id:
          type: string
        total:
          type: integer
        results:
          type: array
          items:
            $ref: "#/components/schemas/PublicCapabilityResult"
        elapsed_time_ms:
          type: number
        remaining_credits:
          anyOf:
            - type: number
            - type: "null"
        error_message:
          anyOf:
            - type: string
            - type: "null"
    PublicExecuteResult:
      type: object
      title: PublicExecuteResult
      additionalProperties: true
      properties:
        data:
          type: object
          additionalProperties: true
        message:
          type: string
        truncated_content:
          type: string
        full_content_file_url:
          type: string
          format: uri
        content_schema:
          type: object
          additionalProperties: true
        respond_with:
          type: string
          description: Echo of the requested projection mode when `respond_with` was set
            (e.g. `summary`).
        summary:
          type: object
          additionalProperties: true
          description: Size and shape statistics returned by the `summary` projection.
          properties:
            size_bytes:
              type: integer
            row_count:
              type: integer
            fields:
              type: array
              items:
                type: string
    PublicCompactBillingStatement:
      type: object
      title: PublicCompactBillingStatement
      additionalProperties: false
      properties:
        summary:
          type: string
        list_amount_credits:
          type: number
        final_amount_credits:
          type: number
    PublicExecuteToolResponse:
      type: object
      title: PublicExecuteToolResponse
      additionalProperties: false
      required:
        - execution_id
        - result
        - success
      properties:
        execution_id:
          type: string
        result:
          description: Capability result. Projected responses use the documented object
            shape; default/full responses may contain any JSON value.
          anyOf:
            - $ref: "#/components/schemas/PublicExecuteResult"
            - type: array
              items: {}
            - type: string
            - type: number
            - type: boolean
            - type: "null"
        success:
          type: boolean
        error_message:
          anyOf:
            - type: string
            - type: "null"
        execution_time:
          type: number
        elapsed_time_ms:
          type: number
        billing:
          $ref: "#/components/schemas/PublicCompactBillingStatement"
        cost:
          type: number
        remaining_credits:
          anyOf:
            - type: number
            - type: "null"
        details:
          type: array
          description: Field-level validation failures. Present when a request parameter
            or projection such as `respond_with` is invalid.
          items:
            $ref: "#/components/schemas/ValidationError"
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/v1/auth/login
    HTTPBearer:
      type: http
      scheme: bearer
    OAuthClientBasic:
      type: http
      scheme: basic
      description: HTTP Basic client authentication. Required for Token Exchange and
        Introspection; supported by confidential clients on Device Authorization
        and Revocation.
servers:
  - url: https://qveris.ai/api/v1
    description: QVeris API
tags:
  - name: Metadata
    description: Unauthenticated API contract metadata for client compatibility checks.
  - name: Discovery
    description: Search and provider discovery APIs that are released for enterprise
      integration.
  - name: Tool Execution
    description: Tool metadata lookup and execution.
  - name: Account
    description: Credits, usage audit, and billing ledger APIs.
  - name: Authentication
    description: OAuth Device Flow, token issuance and exchange, introspection, and
      revocation.
x-qveris-route-count: 24
x-qveris-public-operation-count: 24
x-qveris-private-operation-count: 0
x-qveris-generation-source: Filtered from qveris-internal-api.openapi.json
