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 the fail-closed verification and execution-restriction contract. 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": [
"live_check_samples",
"schema",
"authentication_path",
"description",
"provider_id",
"verified_at",
"expires_at",
"test_run_digest",
"verification_status"
],
"safe_fixes": [
"supply_missing_fields",
"inspect"
],
"retryable": true,
"next_action": "inspect",
"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": false,
"technical": "unknown",
"authentication": "unknown",
"eligibility": "unknown",
"license": "unknown",
"regions": {
"allow": [],
"deny": []
},
"region_status": "unknown",
"commercial_use": "unknown",
"freshness": "unknown",
"price_certainty": "exact",
"warnings": [
"Region restrictions are malformed or contradictory."
],
"confidence": 0.125,
"allowed_actions": [
"discover",
"inspect",
"probe"
],
"blocked_actions": [
"execute"
],
"next_action": "inspect",
"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?