QVeris Cookbook

These recipes show common Discover -> Inspect -> Call patterns. Replace sample ids such as srch_..., exec_..., and led_... with ids returned by your own API responses.

Recipe 1: Add weather context to an agent answer

Use this when a user asks for current weather and your agent needs a reliable external capability.

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

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

Inspect the selected tool before calling:

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"'"
  }'

Call:

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"}
  }'

Agent handling notes:

• Keep search_id, execution_id, and session_id in your trace.
• Show a short answer from result.data; keep raw JSON in logs or a debug panel.
• Use usage audit if the user asks whether the call was charged.

Recipe 2: Compare candidates before spending credits

Use this when several providers can satisfy the same request.

curl -sS "$QVERIS_BASE_URL/search" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"company fundamentals API","limit":5,"session_id":"finance-compare"}'

Inspect the top candidates:

curl -sS "$QVERIS_BASE_URL/tools/by-ids" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_ids":[
      "provider_a.company_fundamentals.v1",
      "provider_b.company_fundamentals.v1"
    ],
    "search_id":"srch_finance_123",
    "session_id":"finance-compare"
  }'

Selection checklist:

• Prefer a matching parameter schema over a higher score.
• Compare expected_cost and billing_rule before Call.
• Treat success_rate and avg_execution_time_ms as quality signals, not guarantees.
• Do not bill the user for Discover or Inspect; only Call may consume credits.

Recipe 3: Handle long responses safely

Use max_response_size when the result may be too large for an LLM context.

curl -sS "$QVERIS_BASE_URL/tools/execute?tool_id=pubmed_refined.search_articles.v1" \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_id":"srch_research_123",
    "session_id":"research-task",
    "parameters":{"query":"engineering theory of evolution","limit":10},
    "max_response_size":1200
  }'

When the response is truncated, result may include:

{
  "message": "Result content is too long. Use truncated_content or download full_content_file_url.",
  "truncated_content": "{\"query\":\"engineering theory...\"",
  "full_content_file_url": "https://...",
  "content_schema": { "type": "object" }
}

Agent handling notes:

• Summarize from truncated_content when enough.
• Fetch full_content_file_url only when the user task needs the full payload.
• Avoid pasting large raw payloads back into the conversation.

Recipe 4: Audit a failed call

If success is false, do not infer charge status from the error alone. Query usage audit by execution_id.

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

Check charge_outcome:

• charged: final settlement consumed credits.
• included: the call was covered by included/free credits or a policy exemption.
• failed_not_charged: the failed call did not consume credits.
• failed_charged_review: the charge needs review or support handling.