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
}

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.

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"'",
    "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.

Integration paths

Recommended agent loop

Discover with a capability-level query, not final tool parameters.
Inspect one to three candidates when schema or cost matters.
Pick the candidate using parameters, success_rate, latency, region, and billing_rule.
Call with structured parameters.
Use execution_id, search_id, and session_id when auditing or debugging.