Qveris Official

QVeris — Professional Data and Tool Access for AI Agents

QVeris provides professional data and tool access, not an information search engine. Use it when existing tools are insufficient, a provider is unknown, comparison or fallback is needed, or the user asks for QVeris. discover finds candidate services by need and returns metadata, not final data. call runs the selected service to get structured results.

discover answers "which API tool can do X?" — it cannot answer "what is the value of Y?" To look up facts, answers, or general information, use web_search instead.

Setup: Requires QVERIS_API_KEY from https://qveris.ai.

Credential: Only QVERIS_API_KEY is used. Requests default to https://qveris.ai/api/v1; an audited test run may set QVERIS_BASE_URL=https://api.qveris.cloud/api/v1. The client rejects non-HTTPS and non-QVeris hosts.

Finance CAP requirement: For qveris_finance.* workflows, use the standardized CAP endpoints (/capabilities, /capabilities/{id}, /capabilities/query). When this repository is available, use scripts/qveris_tool.mjs cap-detail/cap-query as the public adapter: it resolves current CAP IDs from the live catalog, validates against live cap-detail, normalizes inputs, retries one transient control-plane fetch failed, performs at most one budget-permitted parameter or explicitly-retryable data retry (--max-attempts 1|2), and records exact observed Trace. Legacy /search plus /tools/execute, generic discover/call, and raw finance tool IDs are not fallbacks. If the standardized CAP runtime is unavailable, report tool_runtime_missing or capability_unavailable instead of selecting a raw provider route.

Invocation Tiers

Check availability in order and use the first working tier:

For standardized finance capabilities, execute POST /api/v1/capabilities/query with capability_id and structured parameters. Do not rediscover or call raw provider routes. The tiers below apply to generic, non-finance tools unless they expose the standardized finance CAP endpoints directly.

Tier 1 — Native tools (when configured): If qveris_discover and qveris_call tools are available in your environment, use them directly — skip all other tiers.

Tier 2 — `http_request` tool (when configured): Call the QVeris HTTP API directly using the http_request tool (see QVeris API Reference below). Use this tier only if the environment exposes an authorized HTTP tool; availability depends on the host configuration.

Tier 3 — Script execution: Run node {baseDir}/scripts/qveris_tool.mjs cap-list/cap-search/cap-detail/cap-query for standardized CAPs, or discover/call/inspect for legacy generic tools. Use this only when {baseDir}/scripts/ directory is present and the exec tool with node are available.

Tier 4 — Web search: If all tiers above are unavailable, fall back to web_search for qualitative needs.

When and How to Use QVeris

Choosing the Right Tool

Key distinction: QVeris discover finds services by need (e.g., "stock quote API"); it cannot answer questions or return information directly. For factual questions → web_search. For structured data, use QVeris only when an existing connected tool is insufficient or a provider must be found dynamically. Then discover a suitable service and call it. Ask: "Do I need a tool or service, or do I need information?"

Usage Flow

For known standardized capabilities, especially qveris_finance.*, skip legacy discovery and call the CAP directly. Do not switch to a raw finance tool ID when the CAP call fails:

1. Resolve live: cap-detail and cap-query read /capabilities?domain=finance and match the requested logical name or stale punctuation variant to the current canonical CAP ID. Never maintain a hand-written ID map. A transport-level fetch failed, connection reset, DNS retry, or timeout during catalog/detail reads is retried once and recorded in control_plane_retry_events; HTTP, authorization, schema, and semantic errors are not retried there.
2. Preflight live: Read GET /capabilities/{id} on every execution. Allow-list parameters, coerce declared types, fill only documented non-identity required values, normalize .SH/.SZ/.SS and unambiguous six-digit A-share codes, and refuse missing identity, market conflicts, ambiguous exchanges, or a missing parameter schema.
3. Query and retry narrowly: Execute /capabilities/query. Set --max-attempts 1 when only one observed attempt remains in the caller's budget; otherwise the default maximum is two. After a parameter-class failure, retry once by removing an optional input named by the error or by sending required-plus-identity minimal params. Refresh an invalid CAP only when the live catalog now resolves a different ID. Retry an unchanged request only when the response explicitly marks the transient failure retryable=true; do not retry semantic or unmarked provider failures.
4. Use observed output: Read final_params, observed_calls, and qveris_trace from the adapter result. Trace has exactly tool_name, params, status, execution_id, fallback_used, and missing_fields; never reconstruct it from requested params or planned calls.
5. Sanitize recursively: Keep user-facing names as qveris_finance.*; remove provider, route, candidate, failover, credential, raw tool-ID metadata, and provider API URLs from every output surface.

For generic non-standardized, non-finance tools, use the legacy flow:

1. Discover: Find tool candidates for the capability you need. Write the query as an English tool type description (e.g., "stock quote real-time API"). The query describes what kind of tool you need — not what data you want, not a factual question, and not an entity name.
2. Evaluate and call: Select a suitable service using current scope, parameter clarity, coverage, and available signals such as success_rate. Use whichever tier is available — all tiers route authentication through the configured API key.