QVeris Documentation

QVeris is a capability routing network for agents. A client can discover useful capabilities with natural language, inspect the candidate schemas and cost signals, then call the selected capability with structured parameters.

Five-minute first call

This path uses the public REST API because every SDK and MCP integration maps to the same Discover -> Inspect -> Call flow.

Replace sample ids such as srch_..., exec_..., and led_... with ids returned by your own API responses.

1. Create an API key

Create a key from the Dashboard / API Keys page and keep it out of source control.

export QVERIS_API_KEY="qv_your_key"
export QVERIS_BASE_URL="https://qveris.ai/api/v1"
export QVERIS_SESSION_ID="quickstart-$(date +%s)"

2. Discover a capability

Discover is free. It returns a search_id plus ranked capability candidates.

curl -sS "$QVERIS_BASE_URL/search" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "weather forecast API for a city",
    "limit": 3,
    "session_id": "'"$QVERIS_SESSION_ID"'"
  }'

Example response:

{
  "search_id": "srch_01HZX9QK7J3M9T",
  "total": 1,
  "results": [
    {
      "tool_id": "openweathermap.weather.execute.v1",
      "name": "Current Weather",
      "provider_name": "OpenWeatherMap",
      "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
}

Keep the returned search_id with the selected result. If you are building an agent, pass the selected result's tool_id, params, and examples.sample_parameters together to the model. Do not let the model fill parameters from a different tool.

3. Inspect the candidate

Inspect is also free. Use it before Call when you need full parameter details, examples, quality metrics, or the latest billing_rule.

curl -sS "$QVERIS_BASE_URL/tools/by-ids" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_ids": ["openweathermap.weather.execute.v1"],
    "search_id": "srch_01HZX9QK7J3M9T",
    "session_id": "'"$QVERIS_SESSION_ID"'"
  }'

4. Call the capability

Call may consume credits. Use the tool_id from Discover or Inspect and build parameters from that same tool's schema. For agent clients, include model so failed calls can be correlated with the model that selected the tool or generated parameters.

curl -sS "$QVERIS_BASE_URL/tools/execute?tool_id=openweathermap.weather.execute.v1" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_id": "srch_01HZX9QK7J3M9T",
    "session_id": "'"$QVERIS_SESSION_ID"'",
    "model": "gpt-4o",
    "parameters": { "city": "London", "units": "metric" },
    "max_response_size": 20480
  }'

Example response:

{
  "execution_id": "exec_01HZX9R2R4S2E",
  "result": {
    "data": {
      "temperature": 15.5,
      "description": "partly cloudy"
    }
  },
  "success": true,
  "billing": {
    "summary": "5 credits per successful request",
    "list_amount_credits": 5
  },
  "cost": 5,
  "remaining_credits": 990
}

5. Verify settlement

billing and cost in the Call response are pre-settlement signals. For final status, query usage audit or the credits ledger.

curl -sS "$QVERIS_BASE_URL/auth/usage/history/v2?execution_id=exec_01HZX9R2R4S2E" \
  -H "Authorization: Bearer $QVERIS_API_KEY"

curl -sS "$QVERIS_BASE_URL/auth/credits/ledger?entry_type=consume_tool_execute&limit=10" \
  -H "Authorization: Bearer $QVERIS_API_KEY"

Cost semantics

Discover and Inspect are free. They may return expected_cost, cost, or billing_rule so your agent can estimate the Call before spending credits.

Call follows the selected capability's billing_rule. The Call response may include a compact billing object and cost, but the usage audit and credits ledger are the source of truth for final settlement.

session_id semantics

Use a stable session_id for one user task or conversation. Today it is used for tracing, analytics, and pricing context. It is not a cache contract and does not promise session_cache_hit. If a future API adds explicit cache fields, they will be documented separately.

Debugging failed calls

Most integration failures come from a small set of causes:

• The tool_id was not copied exactly from Discover or Inspect.
• The tool is stale or unavailable in the current region.
• Required parameters are missing, have the wrong type, use an invalid enum, or use an invalid date/code format.
• The client selected one tool but generated parameters from another tool's schema.
• The account needs OAuth, permission, or regional access.
• The third-party provider returned an upstream error after parameters were accepted.

For support and audits, keep execution_id, search_id, session_id, tool_id, and model together. These fields let QVeris separate search quality, agent tool choice, parameter generation, platform validation, and provider availability.

Integration paths

• REST API: REST API Reference
• Cookbook: Cookbook
• CLI: CLI documentation
• MCP: MCP Server documentation
• Python SDK: Python SDK

Recommended agent loop

1. Discover with a capability-level query, not final tool parameters.
2. Inspect one to three candidates when schema or cost matters.
3. Pick the candidate using parameters, success_rate, latency, region, and billing_rule.
4. Call with structured parameters generated from that candidate's schema.
5. Send model when an LLM selected the tool or wrote the parameters.
6. Use execution_id, search_id, and session_id when auditing or debugging.