Version: 2026-10-29.1
The authenticated REST API exposes the core agent path. Explicit public read-only access below exposes a restricted Discover/Inspect projection:
| Protocol action | Endpoint | Cost behavior |
|---|---|---|
| Discover | POST /search | Free; returns ranked capabilities and optional cost signals |
| Inspect | POST /tools/by-ids | Free; returns full schemas, examples, quality signals, and cost signals |
| Probe | POST /tools/probe | Free; validates parameters and returns a pre-call quote without execution |
| Call | POST /tools/execute | May consume credits according to the selected capability's billing_rule |
| Usage audit | GET /auth/usage/history/v2 | Final request status and charge outcome |
| Credits ledger | GET /auth/credits/ledger | Final credit balance movements |
Replace sample ids such as srch_..., exec_..., and led_... with ids returned by your own API responses.
Focused references: Discover, Inspect, Probe, Call. The sidebar and public OpenAPI JSON cover every published operation.
https://qveris.ai/api/v1
For authenticated access, send your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Use X-Qveris-Access-Mode: public-readonly only in an explicitly uncredentialed REST request. This mode supports Discover (POST /search) and Inspect (POST /tools/by-ids) only. It creates no account, API key or trial grant and never executes a provider operation. The authenticated API remains the default when the header is absent.
Public Discover searches published catalog keywords. Start with a short keyword such as weather; no matches is a valid empty result, not an authentication failure.
Do not combine this mode with any Authorization, Cookie or session proof, including empty/invalid credentials or unrelated cookies. The server returns 400 access_mode_conflict instead of discarding them. Configure a separate uncredentialed client deliberately; do not strip a configured key to recover from an authentication error. Browser HTTP requests must set credentials: "omit" and must not attach Authorization through a shared interceptor.
The following standalone curl request opts into public Discover without loading curl configuration:
curl -q --fail-with-body --silent --show-error https://qveris.ai/api/v1/search \
-H 'Content-Type: application/json' \
-H 'X-Qveris-Access-Mode: public-readonly' \
-d '{"query":"weather","limit":5,"view":"routing"}'
For Inspect, send {"tool_ids":["TOOL_ID_FROM_DISCOVER"],"view":"routing"} to https://qveris.ai/api/v1/tools/by-ids with the same two headers and no credentials. Replace the ID with one returned by Discover. An optional search_id must be the public context returned by that request.
| Public request | Accepted input |
|---|---|
| Discover | Trimmed query: 1–1024 characters; limit: integer, default 10, maximum 20; optional view: full or routing. |
| Inspect | tool_ids: 1–10 unique IDs, each 1–255 printable characters; optional public search_id and view. |
| Both | JSON body up to 8192 bytes; no unknown fields, session/user/provider/pricing selectors or cursor/offset/page fields. This mode supports bounded first-page reads. |
Successful responses keep the existing flat Search/Inspect JSON shapes rather than adding an API envelope. They include contract_features: ["public-readonly-v1", ...], a pub_ UUID search context and the response header X-Qveris-Access-Mode: public-readonly. They omit prices, balance, user activity, owner/private metadata and raw examples. A public catalog result is not a current account-specific quote or execution permission. Client responses, including errors, are no-store.
| HTTP status | What to do |
|---|---|
400 | Resolve the explicit access-mode/credential conflict. Do not silently drop the credential. |
401 | Authenticate for the normal API or requested authenticated operation. Missing the explicit mode does not enable public access; an invalid supplied key never downgrades to public access. |
413 / 422 | Reduce the oversized body or correct the mode, fields, limits or public context. Invalid/repeated access-mode values are rejected. |
429 | Honor Retry-After and use a bounded read retry policy. Discover and Inspect share a 30-per-minute budget keyed by the observed client IP; proxy/common-egress clients may share this bucket, so it is not a personal allowance. Do not create trial identities or rotate credentials to evade limits. |
502 / 504 | Report unavailable/malformed catalog data or a timeout; do not treat it as empty successful discovery or proof of execution. |
Errors use the standard APIResponse error envelope. Probe, Call, history and ledger are outside public read-only access. To continue with Call, explicitly authenticate with the intended identity, retain only the selected tool/input intent, and refresh Inspect, permissions and any necessary quote before confirming cost. A public search_id is correlation only; never pass it as execution authority to Probe or Call. An already selected tool does not require an extra Discover solely to upgrade authentication.
These instructions describe REST. Hosted MCP still uses its authenticated default, and local tool listing alone does not prove read-only invocation support. CLI/SDK examples must match an actually published supporting version; do not invent a flag or use an empty key as a substitute. See the authentication and trial guide for the separate authenticated and trial flows.
For recoverable issuance, bounded quote admission and new- or existing-account claim, use the Agent trial preparation and activation operations. Privately save a cryptographically random possession proof before preparation; use the same proof to recover a lost response. Only activation issues credits. Review actual execution eligibility and costs before Call. Humans complete account verification and confirmation on the claim page.
The actual allowance and expiry come from the issued trial response and the current API metadata, not a fixed promotional amount. Anonymous tool trials do not include the model gateway. The bounded admission envelope is not a hard lock on the supplier's final price.
The following older API returns an API key and claim code immediately. It retains its original budget rules and supports new-email claim only; do not assume it provides the bounded trial or existing-account transfer contract. Save the actual returned allowance and absolute expiry.
curl -X POST https://qveris.ai/api/v1/agent/anonymous-register \
-H "Content-Type: application/json" \
-d '{"agent_name":"demo-agent"}'
Save the returned api_key and claim_code. The API key is shown only once.
When the trial needs to become a formal account, claim it with an email:
# Step 1: bind the email and receive a 6-digit verification code
curl -X POST https://qveris.ai/api/v1/agent/claim \
-H "Content-Type: application/json" \
-d '{"claim_code":"<claim_code>","email":"operator@example.com"}'
# Step 2: verify the code; the existing API key remains active
curl -X POST https://qveris.ai/api/v1/agent/claim-verify \
-H "Content-Type: application/json" \
-d '{"claim_code":"<claim_code>","email":"operator@example.com","code":"123456"}'
Human operators can also open the claim page on the website. Claim codes cannot be bound to an email that already belongs to a formal account.
Discover, Inspect, and Probe are free. Discover and Inspect may return expected_cost, legacy cost, or billing_rule; Probe validates the selected parameters and returns a zero-cost quote before spending credits.
Every capability returned by Discover or Inspect, and every successful Probe, includes verification_status, the supporting verification checks, and execution_restrictions. Only verified means the complete evidence is current. Verification is an evidence claim, not an execution prerequisite: other states remain discoverable and may be attempted when no explicit blocker applies. Missing eligibility, license, commercial-use, or region declarations are unknown, not a denial. Read execution_restrictions.region_status and execution_restrictions.regions for geographic evidence. callable: true means the current catalog evidence does not prevent attempting Call, not that live authorization, availability, or billing is guaranteed. Use blocked_actions and next_action for actual remediation, and use Probe when parameters or a quote need preflight validation. A positive live Probe can advance an otherwise undisclosed candidate to Call; explicit permission, region, license, scope, tool-availability, or budget blockers still take precedence. The legacy callable field does not control Discover or Inspect visibility.
A legacy result with a fixed billing_rule price per call may be attempted directly even when price_certainty remains estimated; the catalog price is not a reserved quote. Variable metering or an explicitly inexact Probe quote still requires budget confirmation.
The default/full Call response can return compact pre-settlement fields such as billing and cost. Projection responses (summary and fields:*) intentionally omit billing internals to keep the response small. Final settlement is reported by usage audit and the credits ledger; use those endpoints for support, reconciliation, and user-facing billing history.
session_id is optional. Use one stable value per user task or conversation for tracing, analytics, and pricing context. It is not a cache contract and does not promise cache reuse or session_cache_hit.
Use the selected capability's current contract as the source of truth for Call. A full Discover result can be enough to call directly. Inspect only when the selected result omits required contract detail, its metadata may be stale, or you need to compare candidates. Probe only when the parameters need preflight validation or a budget decision needs a current quote.
Recommended contract:
session_id for a user task or conversation.POST /search with a capability-level query.search_id.verification_status and disclose eligibility, license, region, data-as-of, and commercial-use restrictions before execution. Do not take the first result and attach unrelated sample parameters.params contract, build parameters from it. An explicit empty contract describes a true zero-parameter capability; an omitted or incomplete contract requires Inspect. Ask the user for missing business inputs instead of guessing them.POST /tools/probe?tool_id=... only when you need schema validation or a current quote. An exact Probe quote can resolve the price-readiness check for the current request; an estimate without a bound still requires budget confirmation. A Probe quote is not a price reservation or authorization to execute.POST /tools/execute, passing tool_id, parameters, search_id, session_id, and, for agent clients, model.execution_id for audit and support. Do not automatically replay a paid Call when its execution outcome is unknown.Do not infer parameters from the tool name alone. Do not reuse parameters from another tool, another provider, or an old cached schema. If you cache tool metadata, use a short TTL or refresh it whenever the selected tool is returned by a new search.
examples.sample_parameters is a starter example, not a contract or user intent. Preserve required, enum, and alternative/one-of constraints, but replace sample business values with values from the current request.
For LLM/agent integrations, include model in Call metadata whenever possible, for example "model": "gpt-4.1" or "model": "deepseek-v4-pro". This helps correlate tool selection and parameter-generation quality with the model that produced the call.
After a user selects a current service or tool, a discovery surface may send its public selection to the Plugins page. This is a manual handoff, not an execution or authorization contract: the installation page validates the context and lets the user copy exact IDs or a JSON template into their agent. It never copies request parameters, a user prompt, or an API key into the URL.
Version 1 uses these query parameters:
| Parameter | Required | Contract |
|---|---|---|
context_version | Recommended | Producer contract version. Missing values default to version 1; newer versions remain usable when their minimum consumer version is supported. |
context_min_version | No | Oldest consumer version that can safely interpret the stable fields. A value above the consumer version triggers refresh while preserving safe public IDs. |
context_issued_at | Yes | Unix time in seconds. It may be at most five minutes ahead of the consumer clock. |
context_expires_at | Yes | Unix time in seconds, later than context_issued_at, with a maximum lifetime of 24 hours. |
task_id | Yes | Public task identifier, 1–128 characters. |
service_id | Conditional | Public service identifier. At least one of service_id or tool_id is required. |
tool_id | Conditional | Exact public tool identifier returned by Discover or Inspect. |
template_id | No | Public template identifier; it is not template content or a prompt. |
platform | No | An installation-page platform identifier already supported by the Plugins page. |
extensions.<namespace>.<field> | No | Forward-compatible public metadata. Names and values use the same restricted public-ID alphabet; private or credential-shaped values are removed. |
Public IDs must start with an ASCII letter or digit and may contain only ASCII letters, digits, ., _, :, /, or -. Producers must not put prompt, query, parameters, payload, api_key, token, authorization, credentials, PII, or other private data in an installation URL. The consumer strictly removes those values. Ordinary unknown fields are ignored with a warning instead of invalidating the whole handoff. Safe field-name casing, surrounding whitespace, and equivalent duplicates are canonicalized; conflicting duplicates, ambiguity, and security risks are rejected.
Example shape (generate fresh timestamps; do not reuse these literal values):
/plugins?context_version=1&context_issued_at=1800000000&context_expires_at=1800003600&task_id=company-latest-filing&service_id=service.market-data.v1&tool_id=provider.company.lookup.v1&template_id=filing-summary.v1
The handoff remains in the same site-relative URL during login. On return, the installation page automatically revalidates it. Expiration invalidates only discovery-time snapshots such as availability, price, and permission signals; safe task intent and public service/tool/task/template IDs remain available for one-click rediscovery. Changing the selected installation platform also preserves safe public intent.
Recoverable and rejected states expose a structured issue with code, retryable, next_action, and preserved_safe_fields. Consumers should follow next_action rather than deleting the whole handoff. Safe warnings use stable codes such as unknown_field_ignored, duplicate_collapsed, and newer_version_accepted.
Troubleshooting:
| Message | Meaning | Recovery |
|---|---|---|
| Snapshot expired | Availability, price, permission, or terms may have changed. | Use the one-click Tool Finder action to rediscover with the preserved safe task intent. |
| Context incomplete | task_id or both service/tool identifiers are absent or malformed. | Rediscover while preserving any remaining safe public IDs. |
| Invalid snapshot | Timestamps are malformed, future-issued beyond clock tolerance, reversed, or longer than 24 hours. | Refresh discovery metadata; do not discard safe task intent. |
| Version refresh required | context_min_version is newer than the consumer. | Refresh from Tool Finder; stable public IDs remain preserved. |
| Ambiguous context | The same canonical field has conflicting values. | Resolve the producer conflict before applying the handoff. |
| Unsafe context | The URL included a credential, PII, prompt, parameters, payload, or another dangerous field. | Remove private data at the producer boundary. Rotate a credential if it was exposed before removal. |
The installation page provides guidance only. A valid context, copied template, or installation confirmation does not prove service availability and must not be counted as a tool call, useful result, charge, or settlement. Immediately before execution, clients must strictly re-confirm authentication, authorization, current price, limits, parameter schema, provider/upstream status, and any required user approval. If execution fails, use the returned structured state to rediscover or refresh instead of silently replaying a paid call.
QVeris separates pre-call estimate, execution outcome, pre-settlement billing, and final ledger settlement.
| Stage | Where to read it | Important fields | How to use it |
|---|---|---|---|
| Pre-call estimate | Discover / Inspect | expected_cost, billing_rule | Show users the pricing rule before executing a capability. |
| Execution result | Call | success, error_message | Explain whether the provider/result was usable. Do not use success alone to decide final billing. |
| Provider/result outcome | Usage audit | execution_outcome, reason_code, billable_success | Inspect structured provider and result classification without expanding the Call response. |
| Pre-settlement bill | Default/full Call and usage audit | billing, pre_settlement_bill, requested_amount_credits | Show the amount requested before final settlement, discounts, or no-charge rules are applied. |
| Final request status | Usage audit | charge_outcome, reason_code, settlement_result, actual_amount_credits | Answer whether the request was finally charged and why. |
| Final balance movement | Credits ledger | amount_credits, balance_before, balance_after, execution_id | Reconcile account balance and support tickets. |
Recommended reconciliation flow:
billing_rule / expected_cost.execution_id and legacy cost; default/full clients may also save compact billing./auth/usage/history/v2?execution_id=... to read charge_outcome, reason_code, actual_amount_credits, and credits_ledger_entry_id./auth/credits/ledger or the linked ledger entry to verify the final signed balance movement.Client guidance:
execution_id and cost from Call responses. Read structured outcome and final billing details from usage audit.charge_outcome and reason_code for automation; use billing_summary and error_message for user-facing text.cost is kept for backward compatibility. New billing UIs should prefer usage audit and credits ledger for final settlement.Authenticated rate limits are shared by all API keys owned by the same account. Anonymous website traffic is limited per client IP.
| Action | Default quota |
|---|---|
Discover (POST /search) | 120 requests/minute |
Inspect (POST /tools/by-ids) | 120 requests/minute |
Probe (POST /tools/probe) | 120 requests/minute |
Call (POST /tools/execute) | 200 requests/minute |
Rate-limited responses include:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the current window |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix epoch seconds when the current window resets |
Retry-After | Seconds until retry is recommended; always present on 429 |
POST /search
This walkthrough uses the exact tool ID as its query so every following step is reproducible. For dynamic discovery, pass a natural-language capability description and select one of the returned tools.
{
"query": "openweathermap.weather.execute.v1",
"limit": 10,
"session_id": "sess_7Q9m"
}
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Natural-language capability query, or an exact tool ID for deterministic lookup |
limit | integer | No | Maximum result count; default 20, range 1-100 |
session_id | string | No | Tracking and pricing-context id for this user task |
view | string | No | Response projection: routing returns compact routing cards plus required verification and restriction fields; full or omitted returns the complete shape. |
lang | string | No | Response language, zh or en; defaults to Accept-Language negotiation |
For readability, this walkthrough omits the required verification and execution_restrictions objects from the JSON sample. Use the fields below or the OpenAPI schema for their complete shape.
{
"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
}
| Field | Type | Description |
|---|---|---|
query | string | Original search query when available. |
search_id | string | Search id returned by Discover. Use this id in later Inspect or Call requests. |
total | integer | Number of capability results returned. |
results | array | Ranked capability results. |
elapsed_time_ms | number | Search elapsed time in milliseconds. |
remaining_credits | number/null | Remaining account credits when available. |
error_message | string/null | Error detail for business failures. |
| Field | Type | Description |
|---|---|---|
tool_id | string | Unique capability id used by Inspect and Call. |
verification_status | string | Evidence state: unverified, verifying, verified, stale, failed, or restricted. Only verified asserts complete current evidence; other states remain visible with recovery guidance. |
verification | object | Policy version, required checks, evidence timestamps, test-run digest, and quality issues. |
execution_restrictions | object | Immediate callability plus eligibility, license, region, data-as-of, and commercial-use restrictions. |
name | string | Human-readable capability name. |
description | string | Capability description. |
provider_name | string | Capability provider name. |
params | array | Parameter definitions. Each item can include name, type, required, description, and enum. |
examples | object | Example parameters when available. |
expected_cost | string | Human-readable pre-call cost signal when available. |
billing_rule | object | Structured cost signal when available. |
stats.avg_execution_time_ms | number | Historical average execution time in milliseconds. |
stats.success_rate | number | Historical success rate from 0 to 1. |
Invalid API key:
{
"query": "openweathermap.weather.execute.v1",
"search_id": "srch_failed",
"total": 0,
"results": []
}
Insufficient credits:
{
"query": "openweathermap.weather.execute.v1",
"search_id": "srch_failed",
"total": 0,
"results": [],
"error_message": "Insufficient credits",
"remaining_credits": 0
}
Rate limited:
{
"status": "failure",
"status_code": 429,
"message": "Rate limit exceeded. Please try again later."
}
POST /tools/by-ids
Inspect returns the same capability result shape as Discover, usually with more complete parameters and examples.
Inspect may also return catalog_capabilities, the evaluated directory relationships for a tool, with capability_id and localized name (en / zh). This is separate from the existing skill descriptors in capabilities. An empty array confirms no directory relationships. If lookup fails, the field is omitted and catalog_capabilities_warning is unavailable; do not treat that as an empty mapping. For relationship enrichment, the tool_ids array length must be at most 100; Inspect still accepts longer arrays but reports relationships as unavailable.
{
"tool_ids": ["openweathermap.weather.execute.v1"],
"search_id": "srch_01HZX9QK7J3M9T",
"session_id": "sess_7Q9m"
}
| Field | Type | Required | Description |
|---|---|---|---|
tool_ids | string[] | Yes | Capability ids returned by Discover |
search_id | string | No | Search id that returned the capability |
session_id | string | No | Tracking and pricing-context id for this user task |
view | string | No | Response projection: lean trims per-capability metadata for model context; full or omitted returns the complete shape |
Each result also contains the required verification_status, verification, and execution_restrictions fields described under Discover.
{
"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
}
| Field | Type | Description |
|---|---|---|
search_id | string | Search id associated with the inspected tools when available. |
total | integer | Number of capability results returned. |
results | array | Capability results. Each item uses the same capability result fields as Discover. |
elapsed_time_ms | number | Inspect elapsed time in milliseconds when available. |
remaining_credits | number/null | Remaining account credits when available. |
error_message | string/null | Error detail for business failures. |
Timeout:
{
"error": "Request timeout",
"remaining_credits": 995
}
Unexpected proxy failure:
{
"error": "Tools by-ids failed: upstream service unavailable",
"remaining_credits": 995
}
POST /tools/probe?tool_id={tool_id}
Probe is an optional preflight that validates candidate parameters or returns a current quote without executing the capability or consuming credits. Use it when validation or a quote is needed for the task; it is not required before Call. The response includes recovery with missing fields, safe fixes, retryability, the next action, and provider-fallback guidance. Missing noncritical metadata lowers confidence or produces a warning instead of hiding the capability; explicit safety, identity, legal, region, budget, or irreversible-execution conflicts still block the corresponding action.
{
"parameters": {
"q": "London"
},
"checks": ["schema", "quote"],
"live_budget": "none"
}
Use the exact tool_id selected during Discover or Inspect. Keep live_budget set to none for a validation-only probe.
{
"schema": {
"valid": true
},
"quote": {
"estimate_credits": 5,
"currency": "credits",
"exact": true,
"basis": "per_call"
},
"recovery": {
"missing_fields": [],
"missing_field_groups": [],
"safe_fixes": [],
"retryable": true,
"next_action": "execute",
"provider_fallback": false
}
}
recovery.missing_fields lists only absent required call parameters (missing_required). Type, enum, and format violations do not add already supplied fields to this list. When parameter repair is the next step, recovery.safe_fixes includes correct_parameters and probe.
For a one_of_required violation, schema.violations[].required_any_of supplies the alternatives and recovery.missing_field_groups lists each unsatisfied group; provide any one non-empty parameter per group, not every member. For example, missing_field_groups: [["symbol", "cik"]] means supply either symbol or cik, then Probe again. Older responses without structured alternatives retain generic correction guidance.
Catalog evidence gaps remain under verification.quality_issues and do not, by themselves, require another agent step before Call.
A probe can return 400 for invalid input, 404 for an unknown capability, 429 when rate limited, or 502/504 when the probe service is unavailable. See the focused Probe reference for the exact schema and all responses.
POST /tools/execute?tool_id={tool_id}
You may pass tool_id as a query parameter or in the JSON body. Use the query parameter form when possible because it is easier to trace in logs.
{
"search_id": "srch_01HZX9QK7J3M9T",
"session_id": "sess_7Q9m",
"model": "gpt-4.1",
"parameters": {
"q": "London"
},
"max_response_size": 20480
}
| Field | Type | Required | Description |
|---|---|---|---|
tool_id | string | Required overall | Unique id of the tool to execute. Provide it as the query parameter or in this JSON body. |
search_id | string | Recommended | Search id that returned the selected tool |
session_id | string | No | Tracking and pricing-context id; if omitted, the service may use the execution id |
model | string | Recommended for agents | Non-blank model identifier without whitespace or control characters, at most 128 characters, that selected the tool or generated the parameters, such as gpt-4.1, deepseek-v4-pro, or claude-sonnet-4 |
parameters | object | Yes | Capability-specific parameters built from the selected current contract returned by Discover or Inspect |
max_response_size | integer | No | Automatic inline-delivery limit measured from serialized result.data in UTF-8 bytes; default 20480, -1 means unlimited. An explicit full takes precedence over a finite value; summary ignores it. |
respond_with | string | No | Delivery mode: omit it for compatibility auto-delivery; explicit full forces complete inline result.data; fields:<JSONPath,...> projects first and then applies the size limit; summary returns statistics or preserves a data/overflow fallback. |
Invalid tool parameters or projections return HTTP 422 with field-level details; authentication failures return the standard API error object instead of a successful Call or empty Search shape.
Delivery precedence:
respond_with | max_response_size | Delivery |
|---|---|---|
| Omitted | Omitted / positive | Inline within the default / requested limit; otherwise a truncated preview and full-content URL |
| Omitted | -1 | Complete inline data |
full | Any value or omitted | Complete inline result.data; a finite size value does not downgrade it |
fields:... | Omitted / positive / -1 | Project first, then apply the default / requested / unlimited inline rule |
summary | Any value or omitted | Statistics, lossless data, or complete overflow fallback |
If explicit full exceeds the platform hard safety limit, the request fails with error_code: response_too_large; it is never silently converted into an overflow envelope. Binary attachments keep their attachment delivery contract and are not implicitly base64-encoded into JSON.
Build parameters from the selected tool only:
params field as the required schema.required and enum fields.one_of_required; each group means at least one field in that group must be present.examples.sample_parameters only as a hint for shape and typical values.tool_id; it often means the client mixed schemas from two tools.{
"execution_id": "exec_01HZX9R2R4S2E",
"result": {
"data": {
"temperature": 15.5,
"description": "partly cloudy"
}
},
"success": true,
"error_message": null,
"execution_time": 0.211,
"elapsed_time_ms": 211,
"billing": {
"summary": "5 credits per successful request",
"list_amount_credits": 5
},
"cost": 5,
"remaining_credits": 990
}
| Field | Type | Description |
|---|---|---|
execution_id | string | Unique id for this execution. Replace sample exec_... values with ids returned by your response. |
result | object | Tool result payload. Compatibility auto-delivery and fields projection may use the overflow shape below; successful explicit full always includes result.data. |
success | boolean | Whether the tool execution succeeded. Do not infer final charge outcome from this field alone. |
error_message | string/null | Error detail when success is false. |
execution_time | number | Execution elapsed time in seconds. This is the legacy execute response timing field. |
elapsed_time_ms | number | Execution elapsed time in milliseconds when available. |
billing | object | Compact pre-settlement billing statement when available. |
cost | number | Legacy/pre-settlement cost signal when available. |
remaining_credits | number/null | Remaining account credits when available. |
Summary mode preserves at least one usable payload: a summary object, lossless data, or truncated_content together with full_content_file_url. These fields may coexist. Neither statistics nor a URL is guaranteed by the mode alone. Check success first, then field availability; failed summary calls retain an empty data object. Optional metadata includes content_schema and message. Use any signed URL exactly as returned.
Some providers return a valid response that contains no usable result. In this case success can be false, the user message should explain the empty result, and the final usage audit should normally classify it as failed_not_charged.
{
"execution_id": "exec_01HZX9EMPTY",
"result": {
"data": {}
},
"success": false,
"error_message": "The provider returned no results for the current parameters. Try different parameters.",
"execution_time": 0.184,
"elapsed_time_ms": 184,
"billing": {
"summary": "No charge: provider returned no usable result",
"list_amount_credits": 0
},
"cost": 0,
"remaining_credits": 990
}
Missing tool_id:
{
"execution_id": "exec_01HZX9R2R4S2E",
"result": {
"data": {}
},
"success": false,
"error_message": "Missing required parameter: tool_id. Provide it as query (?tool_id=xxx) or in JSON body.",
"execution_time": 0.01
}
Insufficient credits:
{
"execution_id": "exec_01HZX9R2R4S2E",
"result": {
"data": {}
},
"success": false,
"error_message": "Insufficient credits",
"execution_time": 0.01,
"remaining_credits": 0
}
Upstream tool failure:
{
"execution_id": "exec_01HZX9R2R4S2E",
"result": {
"data": {}
},
"success": false,
"error_message": "Execute API error: HTTP 502",
"execution_time": 0.211,
"remaining_credits": 990
}
| Error category | Typical symptom | What to check | Recommended action |
|---|---|---|---|
tool_id format error | The request is rejected before provider execution. | Was the full tool_id copied from Discover or Inspect? | Use the exact tool_id returned by the API. Do not shorten, normalize, or guess ids. |
tool_id not found | The service cannot resolve the selected capability. | Is the tool stale, unavailable in this region, or from an old cache? | Run Discover again and execute a currently returned tool. |
| Parameter error | Missing required field, invalid enum, invalid type, invalid date range, or invalid code/ticker format. | Compare the request body with the selected tool's current params. | Regenerate parameters from the selected result or Inspect response. |
| Schema mismatch | Parameters look valid for a different provider or a different tool. | Did the agent choose one tool_id but fill parameters from another search result? | Keep search_id, selected result, and parameter schema together in one context object. |
| Permission or region error | Auth, OAuth, or region restriction appears before provider execution. | Is the account authorized? Is the client using the right regional API base URL? | Ask the user to connect OAuth, change region, or select another returned tool. |
| Provider failure | Parameters are accepted but upstream returns an HTTP/provider error. | Check error_message; use usage audit when the structured reason_code is needed. | Retry when appropriate, choose another provider, or share execution_id with support. |
When contacting support, include execution_id, search_id, session_id, tool_id, and, for agent clients, model. These fields make it possible to tell whether the failure came from search ranking, tool selection, parameter generation, local validation, or the third-party provider.
GET /tools/executions/by-idempotency-key?key={original_idempotency_key}
When a Call loses its HTTP response, query this read-only endpoint with the original Idempotency-Key. Paid and zero-cost Calls retain an execution record independently of how credits are settled. This endpoint never authorizes another provider execution. The response uses the standard API envelope; data.status is pending, completed, or unavailable. A completed response contains the original recoverable Call in data.response. pending can mean the Provider outcome or settlement is still unknown; keep the original key and reconcile before any further action. unavailable means the execution is known but its full result cannot be reproduced safely, for example after a short-lived overflow download URL expired. A confirmed zero-cost execution reports not_charged and does not require a debit ledger entry.
When respond_with is omitted, or after a fields:... projection, exceeding the effective max_response_size may replace data with the overflow fields below. This shape is never a successful response to explicit respond_with: "full".
{
"result": {
"message": "Result content is too long. Use truncated_content or download full_content_file_url.",
"full_content_file_url": "https://oss.qveris.ai/tool_result_cache/result.json?Expires=1700007200&Signature=example",
"truncated_content": "{\"query\":\"evolution\",\"total_results\":890994",
"content_schema": {
"type": "object"
}
}
}
| Field | Description |
|---|---|
truncated_content | Initial bytes of the tool response |
full_content_file_url | Temporary signed HTTPS URL for downloading the full content directly from QVeris object storage. Use it exactly as returned; do not rewrite it or assume it shares the API origin. The link expires. |
message | LLM-safe explanation of truncation |
content_schema | JSON schema for the full content when available |
Use usage audit to answer: "Did this request succeed?", "Was a failed request charged?", and "Which execution should support review?" Agent, CLI, and MCP clients should prefer precise filters or summary=true instead of dumping full history into an LLM context.
GET /auth/usage/history/v2
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer API key |
| Parameter | Type | Required | Description | Default / range |
|---|---|---|---|---|
start_date | string | No | Start of the audit window. Accepts YYYY-MM-DD or ISO-8601 datetime. | - |
end_date | string | No | End of the audit window. YYYY-MM-DD expands to the end of that day. | - |
event_type | string | No | Exact event type filter: search, search_by_ids, tool_execute, capabilities_query, or model_call. | - |
kind | string | No | Higher-level grouping. discover maps to search + search_by_ids; call maps to tool_execute + capabilities_query; model maps to model_call. | - |
success | boolean | No | Transport/business success flag recorded for the usage event. | - |
billable_success | boolean | No | Billing-specific success flag when available. This can differ from transport success for provider/outcome edge cases. | - |
outcome | string | No | Normalized execution outcome filter from execution_outcome.outcome. | - |
reason_code | string | No | Normalized execution outcome reason, for example provider or validation reason codes. | - |
has_execution_outcome | boolean | No | true returns only events with structured execution outcome; false returns only events without it. | - |
charge_outcome | string | No | Final charge classification: charged, included, failed_not_charged, failed_charged_review. | - |
anomaly | string | No | Audit anomaly filter: failed_charged_review, missing_ledger_link, missing_billing_snapshot. | - |
search_id | string | No | Focus on events linked to a Discover request. | - |
execution_id | string | No | Focus on one Call execution. Best filter for "was this call charged?" | - |
min_credits | number | No | Minimum effective settled/requested credits. Must be >= 0. | - |
max_credits | number | No | Maximum effective settled/requested credits. Must be >= 0. | - |
page | integer | No | Page number. | Default 1, minimum 1 |
page_size | integer | No | Page size when limit is absent. | Default 50, range 1-50000 |
summary | boolean | No | Include server-side aggregates and high-signal samples. If both dates are omitted, the summary window defaults to the last 24 hours. | Default false |
bucket | string | No | Summary time bucket. | hour, day, or week; auto-selects day for windows over 3 days, otherwise hour |
limit | integer | No | Overrides returned sample size and clamps it to a context-safe maximum. Use this for Agent/CLI/MCP summaries. | 1-50; default summary sample 10 |
| Value | Meaning |
|---|---|
charged | The effective success flag is true and the settled/effective credit amount is positive. |
included | The effective success flag is true and the settled/effective credit amount is zero, for example included credits or a policy exemption. |
failed_not_charged | The effective success flag is false and the settled/effective credit amount is zero. |
failed_charged_review | The effective success flag is false but the settled/effective amount is positive; treat this as a support/review case. |
reason_code is stable enough for automation, filters, and support workflows. User-facing text can change; machine clients should prefer the code.
| Reason code | Typical charge outcome | User-facing meaning |
|---|---|---|
result.valid | charged or included | The provider returned usable data. |
result.partial_success | charged, included, or failed_not_charged | The provider returned partial data; inspect the result and billing statement. |
result.empty | failed_not_charged | The provider responded but returned no usable result data. |
provider.error | failed_not_charged | The provider returned an error. |
provider.http_error | failed_not_charged | The provider returned a non-success HTTP response. |
provider.rate_limited | failed_not_charged | The upstream provider rate-limited the request. |
provider.auth_or_permission | failed_not_charged | The upstream provider rejected auth or permission. |
transport.timeout | failed_not_charged | QVeris did not receive a provider response before timeout. |
transport.no_response | failed_not_charged | QVeris could not obtain a provider response. |
transport.execution_failed | failed_not_charged | The execution path failed before a billable provider result was available. |
validation_error | failed_not_charged | Request parameters were invalid or incomplete. |
tool_unavailable | failed_not_charged | The selected capability is unavailable. |
region_restricted | failed_not_charged | The selected capability is not available in the current region. |
oauth_signin_required | failed_not_charged | The capability requires OAuth sign-in before execution. |
curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?execution_id=exec_01HZX9R2R4S2E" \
-H "Authorization: Bearer $QVERIS_API_KEY"
{
"status": "success",
"message": "Usage events retrieved successfully",
"status_code": 0,
"data": {
"items": [
{
"id": "evt_01HZX9R31GH2R",
"event_type": "tool_execute",
"source_system": "qveris_website",
"source_ref_type": "execute_history",
"source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
"session_id": "sess_7Q9m",
"search_id": "srch_01HZX9QK7J3M9T",
"execution_id": "exec_01HZX9R2R4S2E",
"tool_id": "openweathermap.weather.execute.v1",
"success": true,
"charge_outcome": "charged",
"reason_code": "result.valid",
"duration_ms": 211,
"billing_snapshot_status": "upstream_provided",
"billing_rule_snapshot": {
"unit": "request",
"amount_credits": 5
},
"pre_settlement_bill": {
"summary": "5 credits per successful request",
"list_amount_credits": 5
},
"settlement_result": {
"settled_amount_credits": 5
},
"pre_settlement_amount_credits": 5,
"settled_amount_credits": 5,
"actual_amount_credits": 5,
"credits_ledger_entry_id": "led_01HZX9R39K6QZ",
"display_target": "openweathermap.weather.execute.v1",
"billing_summary": "5 credits per successful request",
"created_at": "2026-05-16T08:30:12Z"
}
],
"total": 1,
"page": 1,
"page_size": 50,
"summary": null
}
}
curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?summary=true&bucket=day&kind=call&limit=5&start_date=2026-05-01&end_date=2026-05-16" \
-H "Authorization: Bearer $QVERIS_API_KEY"
{
"status": "success",
"message": "Usage events retrieved successfully",
"status_code": 0,
"data": {
"items": [
{
"id": "evt_01HZX9R31GH2R",
"event_type": "tool_execute",
"execution_id": "exec_01HZX9R2R4S2E",
"tool_id": "openweathermap.weather.execute.v1",
"success": true,
"charge_outcome": "charged",
"settled_amount_credits": 5,
"created_at": "2026-05-16T08:30:12Z"
}
],
"total": 42,
"page": 1,
"page_size": 5,
"summary": {
"start_date": "2026-05-01T00:00:00Z",
"end_date": "2026-05-16T23:59:59.999999Z",
"bucket": "day",
"total_count": 42,
"success_count": 40,
"failure_count": 2,
"charge_outcome_counts": {
"charged": 35,
"included": 5,
"failed_not_charged": 2,
"failed_charged_review": 0
},
"pre_settlement_credits": 210,
"settled_credits": 175,
"max_charge_items": [],
"buckets": [
{
"bucket_start": "2026-05-16T00:00:00Z",
"total_count": 8,
"success_count": 8,
"failure_count": 0,
"charged_count": 7,
"included_count": 1,
"failed_not_charged_count": 0,
"failed_charged_review_count": 0,
"pre_settlement_credits": 40,
"settled_credits": 35
}
]
}
}
}
Top-level response uses the standard APIResponse envelope.
| Field | Type | Description |
|---|---|---|
status | string | success or failure. |
message | string | Human-readable server message. |
status_code | integer | Application status code. Success is 0; validation failures use negative codes. |
data.items | array | Usage events in reverse chronological order. |
data.total | integer | Total rows matching filters. |
data.page | integer | Current page. |
data.page_size | integer | Effective returned item/sample size. If limit is set, it overrides page_size and is capped at 50. |
data.summary | object/null | Aggregate summary when summary=true; otherwise null. |
Important data.items[] fields:
| Field | Description |
|---|---|
event_type | Canonical event type. search = Discover, search_by_ids = Inspect, tool_execute / capabilities_query = Call, model_call = model usage. |
search_id / execution_id | Correlation ids for the Discover or Call flow. |
success | Recorded success flag for the usage event. |
charge_outcome | User-facing final charge classification. Use this instead of guessing from success alone. |
error_message | Error details when available. |
duration_ms | Request duration in milliseconds. |
request_payload / response_payload_summary | Stored request/response summaries for audit. Agent clients should avoid dumping these by default. |
execution_outcome and outcome fields | Structured provider/result outcome details when available. |
billing_rule_snapshot | Billing rule captured at request time. |
pre_settlement_bill | Pre-settlement billing statement captured before final ledger settlement. |
settlement_result | Final settlement details when available. |
requested_amount_credits / actual_amount_credits | Requested versus settled/effective credits. |
credits_ledger_entry_id | Ledger row id when this usage event produced a final balance movement. |
display_target / billing_summary | UI-safe target and billing summary. |
Invalid date or bucket:
{
"status": "failure",
"message": "Invalid start_date format. Use YYYY-MM-DD or ISO-8601 datetime",
"status_code": -7,
"data": null
}
Invalid credit range:
{
"status": "failure",
"message": "min_credits cannot be greater than max_credits",
"status_code": -7,
"data": null
}
Use the credits ledger to explain the final account balance. Usage audit describes requests; the ledger describes immutable credit movements. A charged Call should normally have a usage event with charge_outcome=charged and a linked ledger item.
GET /auth/credits/ledger
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer API key |
| Parameter | Type | Required | Description | Default / range |
|---|---|---|---|---|
start_date | string | No | Start of the ledger window. Accepts YYYY-MM-DD or ISO-8601 datetime. | - |
end_date | string | No | End of the ledger window. YYYY-MM-DD expands to the end of that day. | - |
entry_type | string | No | Exact ledger event type, for example consume_tool_execute. | - |
scope | string | No | Preset entry-type group. account_history includes grant_payment_recharge, consume_tool_search, consume_tool_execute, and consume_model_call. | - |
direction | string | No | Balance direction. consume returns negative credit movements; grant returns positive movements; any returns both. | Default any; allowed consume, grant, any |
min_credits | number | No | Minimum absolute credit amount. For example min_credits=5 matches both -5 and +5. Must be >= 0. | - |
max_credits | number | No | Maximum absolute credit amount. Must be >= 0. | - |
page | integer | No | Page number. | Default 1, minimum 1 |
page_size | integer | No | Page size when limit is absent. | Default 50, range 1-500 |
summary | boolean | No | Include aggregate balance movement summary. If both dates are omitted, the summary window defaults to the last 24 hours. | Default false |
bucket | string | No | Summary time bucket. | hour, day, or week; auto-selects day for windows over 3 days, otherwise hour |
limit | integer | No | Overrides returned sample size and summary max-amount samples, capped for Agent/CLI/MCP use. | 1-50; default summary sample 10 |
entry_type values| Value | Meaning |
|---|---|
grant_payment_recharge | Credits granted by a recharge/payment. |
grant_welcome_bonus | Welcome or promotional credit grant. |
grant_invitation_reward | Invitation/referral credit grant. |
consume_tool_search | Credits consumed for Discover when a deployment charges search. |
consume_tool_execute | Credits consumed for a capability Call. |
consume_model_call | Credits consumed for model calls. |
consume_payment_refund | Credit movement related to a payment refund. |
curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?entry_type=consume_tool_execute&page=1&page_size=10" \
-H "Authorization: Bearer $QVERIS_API_KEY"
{
"status": "success",
"message": "Credits ledger retrieved successfully",
"status_code": 0,
"data": {
"items": [
{
"id": "led_01HZX9R39K6QZ",
"entry_type": "consume_tool_execute",
"amount_credits": -5,
"source_system": "qveris_website",
"source_ref_type": "execute_history",
"source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
"execution_id": "exec_01HZX9R2R4S2E",
"pre_settlement_bill": {
"execution_id": "exec_01HZX9R2R4S2E",
"summary": "5 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": 10,
"summary": null
}
}
curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?summary=true&scope=account_history&direction=any&bucket=day&limit=5&start_date=2026-05-01&end_date=2026-05-16" \
-H "Authorization: Bearer $QVERIS_API_KEY"
{
"status": "success",
"message": "Credits ledger retrieved successfully",
"status_code": 0,
"data": {
"items": [
{
"id": "led_01HZX9R39K6QZ",
"entry_type": "consume_tool_execute",
"amount_credits": -5,
"source_ref_type": "execute_history",
"source_ref_id": "2b7f7c4a-9f3a-4f61-8b59-3a983a8192a0",
"execution_id": "exec_01HZX9R2R4S2E",
"created_at": "2026-05-16T08:30:13Z"
}
],
"total": 18,
"page": 1,
"page_size": 5,
"summary": {
"start_date": "2026-05-01T00:00:00",
"end_date": "2026-05-16T23:59:59.999999",
"bucket": "day",
"total_entries": 18,
"consume_count": 14,
"grant_count": 4,
"consumed_credits": 175,
"granted_credits": 1000,
"net_amount_credits": 825,
"max_amount_items": [],
"buckets": [
{
"bucket_start": "2026-05-16T00:00:00",
"entry_count": 3,
"consume_count": 3,
"grant_count": 0,
"consumed_credits": 15,
"granted_credits": 0,
"net_amount_credits": -15
}
]
}
}
}
| Field | Type | Description |
|---|---|---|
data.items | array | Ledger rows in reverse chronological order. |
data.total | integer | Total rows matching filters. |
data.page / data.page_size | integer | Current page and effective returned item/sample size. |
data.summary | object/null | Aggregate balance summary when summary=true; otherwise null. |
Important data.items[] fields:
| Field | Description |
|---|---|
entry_type | Immutable ledger event type. |
amount_credits | Signed balance movement. Negative values consume credits; positive values grant credits. |
source_system | System that created the ledger row. |
source_ref_type / source_ref_id | Source row reference for backend audit. |
execution_id | Call execution id returned by /tools/execute; use this for user reconciliation. Present for Call ledger rows when available. |
pre_settlement_bill | Billing snapshot before final settlement. |
settlement_result | Final settlement result. |
balance_before / balance_after | Balance snapshots around this movement when available. |
ledger_metadata | Additional internal-safe metadata for audit/debugging. |
description | Human-readable ledger description. |
created_at | Creation timestamp. |
Summary fields:
| Field | Description |
|---|---|
total_entries | Count of matching ledger rows. |
consume_count / grant_count | Number of negative and positive movements. |
consumed_credits / granted_credits | Absolute consumed and granted totals. |
net_amount_credits | Signed net sum; grants positive, consumption negative. |
max_amount_items | High-signal largest absolute movements, capped by limit. |
buckets | Per-bucket time series for charts or compact Agent summaries. |
Invalid direction:
{
"status": "failure",
"message": "Invalid direction. Use consume, grant, or any",
"status_code": -7,
"data": null
}
Invalid credit range:
{
"status": "failure",
"message": "min_credits must be greater than or equal to 0",
"status_code": -7,
"data": null
}
session_id.search_id.tool_id; confirm required params and pre-call cost fields.parameters; save execution_id.execution_id.The QVeris Public OpenAPI document is available as stable JSON and YAML, with versioned JSON and YAML URLs for pinned integrations. It includes request bodies, response schemas, and examples for every published operation. Legacy-compatibility fixtures remain available from the projection fixtures.
Was this page helpful?