POST /tools/probe
Optionally validate candidate parameters or obtain a zero-cost quote when the task needs preflight validation or a current quote. Probe is not required before Call and a quote does not reserve price or authorize execution. The M1 schema and quote checks are implemented; coverage and sample return an explicit unknown verdict. Every successful Probe includes verification evidence and execution restrictions. Explicit blockers take precedence. Probe never executes the capability or consumes credits.
REST API overview · OpenAPI JSON · OpenAPI YAML
| Stability | Authentication | Cost | Operation ID |
|---|---|---|---|
| Published | Bearer API key | Free | probe_tool_api_v1_tools_probe_post |
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tool_id | query | Yes | string | Tool ID to validate |
Schema: PublicToolProbeRequest
| Name | Required | Type | Description |
|---|---|---|---|
parameters | No | object | Candidate parameters to validate without executing the capability. |
checks | No | "schema" | "quote" | "coverage" | "sample"[] | — |
live_budget | No | "none" | "metadata" | "sampled" | M1 is zero-cost; every value avoids an upstream tool execution. |
sub_user_id | No | string | Optional sub-user identity used for provider OAuth readiness checks. |
curl --request POST \
--url "https://qveris.ai/api/v1/tools/probe?tool_id=string" \
--header "Authorization: Bearer $QVERIS_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"parameters": {
"q": "London"
},
"checks": [
"schema",
"quote"
],
"live_budget": "none"
}'
const response = await fetch("https://qveris.ai/api/v1/tools/probe?tool_id=string", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.QVERIS_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"parameters": {
"q": "London"
},
"checks": [
"schema",
"quote"
],
"live_budget": "none"
}),
})
if (!response.ok) throw new Error(`QVeris request failed: ${response.status}`)
console.log(await response.json())
import json
import os
import requests
response = requests.request(
"POST",
"https://qveris.ai/api/v1/tools/probe?tool_id=string",
headers={"Authorization": f"Bearer {os.environ['QVERIS_API_KEY']}"},
json=json.loads(r'''{
"parameters": {
"q": "London"
},
"checks": [
"schema",
"quote"
],
"live_budget": "none"
}'''),
timeout=30,
)
response.raise_for_status()
print(response.json())
| Status | Meaning | Schema |
|---|---|---|
200 | Successful Response | PublicToolProbeResponse |
400 | Invalid probe request | PublicApiError |
401 | Unauthorized | PublicApiError |
404 | Capability not found | PublicApiError |
422 | Validation Error | HTTPValidationError |
429 | Too Many Requests | unknown |
502 | Upstream unavailable | PublicApiError |
504 | Upstream timeout | PublicApiError |
{
"schema": {
"valid": true
},
"quote": {
"estimate_credits": 5,
"currency": "credits",
"exact": true,
"basis": "per_call"
},
"recovery": {
"missing_fields": [],
"safe_fixes": [],
"retryable": true,
"next_action": "execute",
"provider_fallback": false
},
"verification_status": "unverified",
"verification": {
"status": "unverified",
"policy_version": "catalog-verification-v1",
"required_checks": [
"schema",
"authentication",
"description_contract",
"provider_identity",
"permissions",
"freshness",
"live_check"
],
"checks": [
{
"name": "schema",
"status": "missing",
"reason": "schema_missing"
},
{
"name": "authentication",
"status": "missing",
"reason": "authentication_path_missing"
},
{
"name": "description_contract",
"status": "missing",
"reason": "description_missing"
},
{
"name": "provider_identity",
"status": "missing",
"reason": "provider_id_missing"
},
{
"name": "permissions",
"status": "missing"
},
{
"name": "freshness",
"status": "missing",
"reason": "expires_at_missing"
},
{
"name": "live_check",
"status": "missing",
"reason": "live_check_samples_missing"
}
],
"quality_issues": [
"live_check_samples_missing",
"schema_missing",
"authentication_path_missing",
"description_missing",
"provider_id_missing",
"permission_disclosure_incomplete",
"verified_at_missing",
"expires_at_missing",
"test_run_digest_missing",
"verification_status_missing"
]
},
"execution_restrictions": {
"callable": true,
"technical": "ready",
"authentication": "unknown",
"eligibility": "unknown",
"license": "unknown",
"regions": {
"allow": [],
"deny": []
},
"region_status": "unknown",
"commercial_use": "unknown",
"freshness": "unknown",
"price_certainty": "exact",
"warnings": [],
"confidence": 0.25,
"allowed_actions": [
"discover",
"inspect",
"probe",
"execute"
],
"blocked_actions": [],
"next_action": "execute",
"retryable": true
},
"contract_features": [
"verification-evidence-v1",
"action-guidance-v1",
"probe-recovery-v1"
]
}
POST Discover capabilities · POST Inspect capabilities · POST Call a capability
Was this page helpful?