@qverisai/sdk
This page is generated from the public package exports and source comments. See the TypeScript SDK guide for installation, authentication, and complete workflows.
A credential provider backed by a static QVeris API key.
new ApiKeyCredentialProvider(
apiKey):ApiKeyCredentialProvider
string
getCredential(
_context):Promise<string>
Promise<string>
CredentialProvider.getCredential
QVeris API client.
import { Qveris } from '@qverisai/sdk';
const qveris = new Qveris({ apiKey: process.env.QVERIS_API_KEY! });
const found = await qveris.discover('stock price market data API', { limit: 5 });
const tool = found.results[0];
const outcome = await qveris.call(tool.tool_id, {
searchId: found.search_id,
parameters: { symbol: 'AAPL' },
});
new Qveris(
config):Qveris
get rateLimitRetryCount():
number
How many times the client has backed off on a rate-limited (429) / transient (503) response so far. Rate-limit backoff is retried pressure, not failure — observe this rather than counting the retried responses.
number
call(
toolId,options):Promise<ExecuteResponse>
Call a capability. The response may include pre-settlement billing; final charges are reflected in usage() and ledger().
string
Promise<ExecuteResponse>
credits():
Promise<CreditsResponse>
Get current credit balance and bucket details.
Promise<CreditsResponse>
discover(
query,options?):Promise<SearchResponse>
Discover capabilities from a natural-language query. Free.
string
DiscoverOptions = {}
Promise<SearchResponse>
inspect(
toolIds,options?):Promise<SearchResponse>
Inspect capabilities by id to get current parameter schemas. Free. An empty id list resolves locally without a network request.
string | string[]
InspectOptions = {}
Promise<SearchResponse>
ledger(
filters?):Promise<CreditsLedgerResponse>
Query final credits ledger entries.
CreditsLedgerRequest = {}
Promise<CreditsLedgerResponse>
probe(
toolId,options?):Promise<ProbeResponse>
Validate candidate parameters and request a zero-cost quote without executing the capability.
string
ProbeOptions = {}
Promise<ProbeResponse>
usage(
filters?):Promise<UsageEventsResponse>
Query request-level usage audit history.
UsageHistoryRequest = {}
Promise<UsageEventsResponse>
staticfromEnv(overrides?):Qveris
Create a client from the QVERIS_API_KEY environment variable. An explicit baseUrl override takes priority over QVERIS_BASE_URL.
Omit<QverisClientOptions, "apiKey" | "credentialProvider">
Error thrown for any failed QVeris API interaction: HTTP errors, failure envelopes, timeouts, and network failures.
Carries the same shape as the wire-level ApiError so callers can
branch on status and inspect observability for diagnostics.
Errornew QverisApiError(
error):QverisApiError
Error.constructor
readonlyoptionalcause?:string
Lower-level transport or runtime cause when available
Error.cause
readonlyoptionaldetails?:unknown
Original error details if available
message:
string
Error message
Error.message
name:
string
Error.name
readonlyoptionalobservability?:ApiObservability
Request metadata for diagnosing API failures
optionalstack?:string
Error.stack
readonlystatus:number
HTTP status code (0 for network errors, 408 for timeouts)
staticstackTraceLimit:number
The Error.stackTraceLimit property specifies the number of stack frames
collected by a stack trace (whether generated by new Error().stack or
Error.captureStackTrace(obj)).
The default value is 10 but may be set to any valid JavaScript number. Changes
will affect any stack trace captured after the value has been changed.
If set to a non-number value, or set to a negative number, stack traces will not capture any frames.
Error.stackTraceLimit
staticcaptureStackTrace(targetObject,constructorOpt?):void
Creates a .stack property on targetObject, which when accessed returns
a string representing the location in the code at which
Error.captureStackTrace() was called.
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack; // Similar to `new Error().stack`
The first line of the trace will be prefixed with
${myObject.name}: ${myObject.message}.
The optional constructorOpt argument accepts a function. If given, all frames
above constructorOpt, including constructorOpt, will be omitted from the
generated stack trace.
The constructorOpt argument is useful for hiding implementation
details of error generation from the user. For instance:
function a() {
b();
}
function b() {
c();
}
function c() {
// Create an error without stack trace to avoid calculating the stack trace twice.
const { stackTraceLimit } = Error;
Error.stackTraceLimit = 0;
const error = new Error();
Error.stackTraceLimit = stackTraceLimit;
// Capture the stack trace above function b
Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
throw error;
}
a();
object
Function
void
Error.captureStackTrace
staticprepareStackTrace(err,stackTraces):any
Error
CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
T
data:
T
optionalmessage?:string
status:
string
optionalstatus_code?:number
optionalcause?:string
Lower-level transport or runtime cause when available.
optionaldetails?:unknown
Original error details if available
message:
string
Error message
optionalobservability?:ApiObservability
Request metadata for diagnosing API/provider/tool-chain failures.
status:
number
HTTP status code
endpoint:
string
optionalerror_type?:ApiErrorType
optionalhttp_status?:number
method:
"GET"|"POST"
operation:
ApiOperation
optionalquery_params?:Record<string,string>
optionalrequest_id?:string
source:
"qveris_api"
timeout_ms:
number
url:
string
optionalamount_credits?:number|null
component_key:
string
optionaldescription?:string|null
optionalis_adjustment?:boolean|null
optionalprice?:BillingPrice|null
optionalquantity?:number|null
optionalunit?:string|null
optionalunit_label?:string|null
amount_credits:
number
optionalper?:number|null
optionalunit?:string|null
optionalunit_label?:string|null
optionalbilling_unit?:string
optionalbilling_unit_label?:string
optionaldescription?:string
optionalmetering_mode?:string
optionalminimum_charge_credits?:number|null
optionalprice?:BillingPrice|null
optionalprice_breakdown?:Record<string,unknown>[] |null
optionalpricing_dimensions?:Record<string,unknown>[] |null
optionalpricing_source_system?:string|null
optionalruntime_pricing_version?:string|null
optionalsnapshot_id?:number|null
optionalsnapshot_version?:string|null
Options for Qveris.call.
optionalmaxResponseSize?:number
Max response bytes before truncation (-1 for no limit, server default 20480)
parameters:
Record<string,unknown>
Key-value parameters matching the tool's parameter schema
optionalrespondWith?:"full"|`fields:${string}`|"summary"
Server-side result projection. Omit for the legacy/full response.
optionalsearchId?:string
The search_id from the discover call that returned this tool
optionalsessionId?:string
Session identifier for tracking
optionaltimeoutMs?:number
Per-request timeout override in milliseconds (default 120s)
optionalcharge_lines?:BillingChargeLine[] |null
optionallist_amount_credits?:number|null
optionalminimum_charge_credits?:number|null
optionalprice?:BillingPrice|null
optionalquantity?:number|null
optionalrequested_amount_credits?:number|null
optionalsummary?:string|null
Context supplied whenever the client requests a credential.
resource:
string
API resource the credential will be sent to.
scopes: readonly
string[]
Requested authorization scopes. Empty until a public scope contract is available.
Supplies a bearer credential for an API request.
getCredential(
context):string|Promise<string>
string | Promise<string>
amount_credits:
number
optionalbalance_after?:Record<string,unknown> |null
optionalbalance_before?:Record<string,unknown> |null
created_at:
string
optionaldescription?:string|null
entry_type:
string
id:
string
optionalledger_metadata?:Record<string,unknown> |null
optionalpre_settlement_bill?:Record<string,unknown> |null
optionalsettlement_result?:Record<string,unknown> |null
optionalsource_ref_id?:string|null
optionalsource_ref_type?:string|null
source_system:
string
optionalbucket?:string
optionaldirection?:string
optionalend_date?:string
optionalentry_type?:string
optionallimit?:number
optionalmax_credits?:number
optionalmin_credits?:number
optionalpage?:number
optionalpage_size?:number
optionalstart_date?:string
optionalsummary?:boolean
items:
CreditsLedgerItem[]
page:
number
page_size:
number
optionalsummary?:Record<string,unknown> |null
total:
number
optionaldaily_free?:Record<string,unknown>
optionalinvite_reward?:Record<string,unknown>
optionalpurchased?:Record<string,unknown>
remaining_credits:
number
optionalwelcome_bonus?:Record<string,unknown>
Options for Qveris.discover.
optionallang?:"zh"|"en"
Response language. Omit to use server-side language negotiation.
optionallimit?:number
Maximum number of results (1-100, server default 20)
optionalsessionId?:string
Session identifier for tracking
optionaltimeoutMs?:number
Per-request timeout override in milliseconds
optionalview?:"routing"|"full"
Response projection. Omit for the legacy/full response shape.
Request body for the Execute Tool API.
optionalmax_response_size?:number
Maximum size of response data in bytes.
If the tool generates data longer than this, it will be truncated
and a download URL will be provided for the full content.
Minimum: -1 (-1 means no limit).
20480 (20KB)
parameters:
Record<string,unknown>
Key-value pairs of parameters to pass to the tool. Must match the parameter schema from the tool's definition.
optionalrespond_with?:"full"|`fields:${string}`|"summary"
Server-side result projection. Omit for the legacy/full response.
search_id:
string
The search_id from the search that returned this tool. Links the execution to the original search for analytics and billing.
optionalsession_id?:string
Session identifier for tracking user sessions.
Response from the Execute Tool API.
optionalbilling?:CompactBillingStatement
Structured pre-settlement billing statement when available
optionalcost?:number
Legacy fallback estimate; use usage audit or credits ledger for final charge
optionalcreated_at?:string
Timestamp of execution (ISO 8601 format)
optionalelapsed_time_ms?:number
Execution duration in milliseconds (alternative field)
optionalerror_message?:string|null
Error message if execution failed. Common reasons: insufficient balance, quota exceeded, invalid parameters.
execution_id:
string
Unique identifier for this execution record
optionalexecution_time?:number
Execution duration in seconds
optionalparameters?:Record<string,unknown>
The parameters that were passed to the tool
optionalpre_settlement_bill?:Record<string,unknown>
Legacy/full pre-settlement bill snapshot when returned directly
optionalremaining_credits?:number
User's remaining credits after this execution
optionalresult?:ExecuteResult
The execution result.
Contains either data (if within size limit) or truncation info.
success:
boolean
Whether the execution completed successfully
optionaltool_id?:string
The tool that was executed
Result data when the response fits within max_response_size.
data:
unknown
The actual result data from the tool execution
Selected result fields returned by a fields:<JSONPath,...> projection.
optionaldata?:unknown
respond_with:
`fields:${string}`
Compact result returned by respond_with: "summary".
optionalcontent_schema?:Record<string,unknown>
optionalfull_content_file_url?:string
optionalmessage?:string
respond_with:
"summary"
optionalsummary?:object
[key: string]: unknown
optionalfields?:string[]
optionalrow_count?:number
optionalsize_bytes?:number
Result data when the response exceeds max_response_size. Provides truncated content and a URL to download the full result.
optionalcontent_schema?:Record<string,unknown>
JSON Schema describing the structure of the full content. Helps the agent understand the data shape without downloading.
full_content_file_url:
string
URL to download the complete result file. Valid for 120 minutes.
message:
string
Explanation message about the truncation
truncated_content:
string
The initial portion of the response (max_response_size bytes). Useful for previewing the data structure.
Request body for the Get Tools by IDs API.
optionalsearch_id?:string
The search_id from the search that returned the tool(s).
optionalsession_id?:string
Session identifier for tracking user sessions.
tool_ids:
string[]
Array of tool IDs to retrieve information for.
Options for Qveris.inspect.
optionalsearchId?:string
The search_id from the discover call that returned the tool(s)
optionalsessionId?:string
Session identifier for tracking
optionaltimeoutMs?:number
Per-request timeout override in milliseconds
Options for Qveris.probe.
optionalchecks?:ProbeCheck[]
Checks to run. Defaults to schema.
optionalliveBudget?:ProbeLiveBudget
Probe budget. Every current value avoids capability execution.
optionalparameters?:Record<string,unknown>
Candidate parameters to validate without executing the capability.
optionaltimeoutMs?:number
Per-request timeout override in milliseconds.
optionalbasis?:string|null
currency:
"credits"
optionaldetail?:Record<string,unknown> |null
optionalestimate_credits?:number|null
exact:
boolean
optionalchecks?:ProbeCheck[]
optionallive_budget?:ProbeLiveBudget
optionalparameters?:Record<string,unknown>
optionalcoverage?:ProbeUnknownResult
optionalquote?:ProbeQuoteResult
optionalsample?:ProbeUnknownResult
optionalschema?:ProbeSchemaResult
optionalnote?:string|null
valid:
boolean
optionalviolations?:ProbeSchemaViolation[] |null
message:
string
optionalparam?:string|null
type:
string
reason:
string
verdict:
"unknown"
Configuration options for the Qveris API client.
apiKey:
string
API authentication token
optionalbaseUrl?:string
API base URL. Overrides QVERIS_BASE_URL and the built-in default.
optionalmaxRetries?:number
Max automatic retries for rate-limited (429) / transient (503) responses.
Honors Retry-After, otherwise backs off exponentially with jitter.
Defaults to 3; set to 0 to disable.
optionaltimeoutMs?:number
Default request timeout in milliseconds
Request body for the Search Tools API.
optionallang?:"zh"|"en"
Response language. Omit to use server-side language negotiation.
optionallimit?:number
Maximum number of results to return. Minimum: 1. Maximum: 100.
20
query:
string
Natural language search query describing the tool capability you need.
optionalsession_id?:string
Session identifier for tracking user sessions.
optionalview?:"routing"|"full"
Response projection. Omit for the legacy/full response shape.
Response from the Search Tools API.
optionalelapsed_time_ms?:number
Total elapsed time in milliseconds
optionalquery?:string
The original search query
optionalremaining_credits?:number
User's remaining credits after this operation
results:
ToolInfo[]
Array of matching tools
search_id:
string
Unique identifier for this search. Required when calling call for any tool from these results.
optionalstats?:SearchStats
Search performance statistics
optionaltotal?:number
Total number of results returned
Performance statistics for a search operation.
optionalfulltext_recall_count?:number
Fulltext recall count
optionalsearch_time_ms?:number
Total time to complete the search in milliseconds
optionalvector_recall_count?:number
Vector recall count
Standardized capability descriptor attached to a tool (e.g. "MKT.BARS.ADJUSTED" with market coverage tags).
optionalid?:string
optionaltag?:ToolCapabilityTag[]
Coverage tag attached to a capability (e.g. market coverage).
optionaldescription?:string
optionalid?:string
optionalname?:string
optionaltype?:string
Category/tag attached to a tool.
Current API responses return category objects; legacy responses returned
plain strings, so ToolInfo.categories accepts both.
optionaldescription?:string
optionalname?:string
optionalslug?:string
Example usage for a tool, showing sample parameters.
optionalsample_parameters?:Record<string,unknown>
Sample parameter values demonstrating typical usage
Information about a tool returned from search results. Contains everything needed to understand and execute the tool.
optionalas_of_support?:boolean
Whether the capability supports point-in-time requests.
optionalbilling_rule?:BillingRule
Structured rule-level billing metadata when available
optionalcapabilities?:ToolCapability[]
Standardized capability descriptors with coverage tags
optionalcapability?:string
Compact capability label returned by the routing projection.
optionalcategories?: (string|ToolCategory)[]
Tool categories/tags: category objects, or plain strings in legacy responses
optionalcost_class?:string
Compact cost class returned by the routing projection.
optionaldescription?:string
Detailed description of what the tool does
optionaldocs_url?:string
Documentation URL for the tool
optionalexamples?:ToolExamples
Usage examples with sample parameters
optionalexpected_cost?:string|number
Pre-call cost estimate in credits, when available
optionalfinal_score?:number
Relevance score for the search query (0.0 - 1.0, higher = better match)
optionalhas_last_execution?:boolean
Whether this tool has been executed before (verified in production)
optionallast_execution_record?:Record<string,unknown>
Most recent execution record, if available
optionalname?:string
Human-readable display name
optionalparams?:ToolParameter[]
List of parameters the tool accepts
optionalprotocol?:string
Protocol type
optionalprovider_description?:string
Description of the provider
optionalprovider_id?:string
Provider identifier
optionalprovider_name?:string
Name of the organization/service providing this tool
optionalprovider_website_url?:string
Provider website URL
optionalregion?:string
Geographic availability of the tool.
optionalreliability?:string
Compact reliability grade returned by the routing projection.
optionalstats?:ToolStats
Historical execution performance statistics
tool_id:
string
Unique identifier for the tool (used in call)
optionalwhy_recommended?:string
Human-readable explanation of why this tool was recommended (Discover results only)
Parameter definition for a tool.
description:
string
Human-readable description of what this parameter does
optionalenum?:string[]
If present, restricts valid values to this list
name:
string
Parameter name (used as key in the parameters object)
required:
boolean
Whether this parameter must be provided
type:
"string"|"number"|"boolean"|"object"|"array"
Data type of the parameter
Historical execution performance statistics for a tool.
optionalavg_execution_time_ms?:number
Historical average execution time in milliseconds
optionalcost?:number
Legacy fallback estimate in credits per call
optionalsuccess_rate?:number
Historical success rate (0.0 - 1.0)
optionalactual_amount_credits?:number|null
optionalbilling_snapshot_status?:string|null
optionalbilling_summary?:string|null
optionalcharge_outcome?:string|null
created_at:
string
optionalcredits_ledger_entry_id?:string|null
optionaldisplay_target?:string|null
optionalerror_message?:string|null
event_type:
string
optionalexecution_id?:string|null
id:
string
optionalkind?:string|null
optionalmodel?:string|null
optionalpre_settlement_amount_credits?:number|null
optionalpre_settlement_bill?:Record<string,unknown> |null
optionalquery?:string|null
optionalrequested_amount_credits?:number|null
optionalsearch_id?:string|null
optionalsession_id?:string|null
optionalsettled_amount_credits?:number|null
optionalsettlement_result?:Record<string,unknown> |null
optionalsource_ref_id?:string|null
optionalsource_ref_type?:string|null
source_system:
string
success:
boolean
optionaltool_id?:string|null
items:
UsageEventItem[]
page:
number
page_size:
number
optionalsummary?:Record<string,unknown> |null
total:
number
optionalbucket?:string
optionalcharge_outcome?:string
optionalend_date?:string
optionalevent_type?:string
optionalexecution_id?:string
optionalkind?:string
optionallimit?:number
optionalmax_credits?:number
optionalmin_credits?:number
optionalpage?:number
optionalpage_size?:number
optionalsearch_id?:string
optionalstart_date?:string
optionalsuccess?:boolean
optionalsummary?:boolean
ApiErrorType =
"http_error"|"invalid_json"|"timeout"|"network_error"
ApiOperation =
"discover"|"inspect"|"probe"|"call"|"credits"|"usage_history"|"credits_ledger"
Error response from the Qveris API.
ExecuteResult =
ExecuteResultData|ExecuteResultTruncated|ExecuteResultSummary|ExecuteResultFields|unknown[] |string|number|boolean|null
Union type for execution results (either full data or truncated).
ProbeCheck =
"schema"|"quote"|"coverage"|"sample"
ProbeLiveBudget =
"none"|"metadata"|"sampled"
QverisClientOptions =
Omit<QverisClientConfig,"apiKey"> & {apiKey:string;credentialProvider?:never; } | {apiKey?:never;credentialProvider:CredentialProvider; }
Configuration accepted by the QVeris REST client.
getQverisTools(
qveris,options?):object
Build Vercel AI SDK tools for the QVeris discover/inspect/call workflow.
The Qveris client to route calls through.
Optional sessionId for correlation/pricing context.
string
object
A tools object keyed by qveris_discover / qveris_inspect /
qveris_call, ready to pass to generateText/streamText.
qveris_call:
object&object&object&object&object|never|object&object&object&object&object|never|object&object&object&object&object|never|object&object&object&object&object|never
qveris_discover:
object&object&object&object&object|never|object&object&object&object&object|never|object&object&object&object&object|never|object&object&object&object&object|never
qveris_inspect:
never|object&object&object&object&object|never|object&object&object&object&object|never|object&object&object&object&object|never|object&object&object&object&object