---
title: "Probe a capability without executing it"
method: POST
path: "/tools/probe"
tags: ["Tool Execution"]
---

# Probe a capability without executing it

`POST /tools/probe`

## Request

- Base URL: `https://qveris.ai/api/v1`
- URL: `https://qveris.ai/api/v1/tools/probe`
- Auth: HTTP bearer

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.

## Query parameters

- `tool_id` string, required: Tool ID to validate

## Request body

- PublicToolProbeRequest
  - `parameters` object: Candidate parameters to validate without executing the capability.
  - `checks` string[]
  - `live_budget` 'none' | 'metadata' | 'sampled': M1 is zero-cost; every value avoids an upstream tool execution.
  - `sub_user_id` string: Optional sub-user identity used for provider OAuth readiness checks.

## Response `200`

Successful Response

- PublicToolProbeResponse
  - `exists` boolean
  - `executable` boolean
  - `status` integer
  - `reason` 'tool_unavailable' | 'tool_disabled' | 'realtime_unavailable' | 'region_restricted' | 'insufficient_scope' | 'delegation_budget_not_supported' | 'oauth2_signin_required'
  - `schema` PublicProbeSchemaResult
    - `valid` boolean, required
    - `violations` PublicProbeSchemaViolation[], nullable
      - `param` string, nullable
      - `required_any_of` string[], nullable: For one_of_required violations, supply any one non-empty parameter from this group.
      - `type` string, required
      - `message` string, required
    - `note` string, nullable
  - `quote` PublicProbeQuoteResult
    - `estimate_credits` number, nullable
    - `currency` 'credits', required
    - `exact` boolean, required
    - `basis` string, nullable
    - `detail` object, nullable
  - `coverage` PublicProbeUnknownResult
    - `verdict` 'unknown', required
    - `reason` string, required
  - `sample` PublicProbeUnknownResult
    - `verdict` 'unknown', required
    - `reason` string, required
  - `recovery` PublicProbeRecoveryAdvice, required
    - `missing_fields` string[], required
    - `missing_field_groups` array[], required: Each group requires any one non-empty parameter, not every member.
      - string[]
    - `safe_fixes` string[], required
    - `retryable` boolean, required
    - `next_action` 'execute' | 'inspect' | 'probe' | 'authorize' | 'confirm_budget' | 'switch_provider' | 'retry', required
    - `provider_fallback` boolean, required
  - `verification_status` 'unverified' | 'verifying' | 'verified' | 'stale' | 'failed' | 'restricted', required
  - `verification` PublicCatalogVerification, required: Fail-closed catalog verification result. Only records with every required check passed, a valid test digest, and an unexpired 24-hour evidence window are verified.
    - `status` 'unverified' | 'verifying' | 'verified' | 'stale' | 'failed' | 'restricted', required
    - `policy_version` string, required
    - `required_checks` string[], required
    - `checks` PublicVerificationCheck[], required
      - `name` 'schema' | 'authentication' | 'description_contract' | 'provider_identity' | 'permissions' | 'freshness' | 'live_check', required
      - `status` 'missing' | 'verifying' | 'passed' | 'stale' | 'failed' | 'restricted', required
      - `checked_at` string, date-time, nullable
      - `evidence_digest` string, nullable
      - `reason` string, nullable
    - `verified_at` string, date-time, nullable
    - `expires_at` string, date-time, nullable
    - `test_run_digest` string, nullable
    - `quality_issues` string[], required
  - `execution_restrictions` PublicExecutionRestrictions, required: Additive readiness axes and action guidance. Discovery remains available for unknown or incomplete evidence. Explicit restrictions fail closed through blocked_actions. Missing provider restriction metadata is not an execution denial: a candidate with usable input and a fixed per-call catalog price may be called directly. The catalog price is an estimate, not a reserved quote; variable pricing still requires budget confirmation. Probe is optional unless preflight validation or a current quote is needed. Call remains subject to live authorization, availability, and billing checks.
    - `callable` boolean, required
    - `eligibility` 'unknown' | 'not_required' | 'required' | 'restricted', required
    - `license` 'unknown' | 'not_required' | 'required' | 'approved' | 'restricted', required
    - `regions` PublicRegionRestrictions, required
      - `allow` string[], required
      - `deny` string[], required
    - `commercial_use` 'unknown' | 'allowed' | 'conditional' | 'prohibited', required
    - `data_as_of` string, date-time, nullable
    - `warnings` string[], required
    - `technical` 'unknown' | 'ready' | 'blocked'
    - `authentication` 'unknown' | 'ready' | 'required' | 'blocked'
    - `region_status` 'unknown' | 'ready' | 'conditional' | 'blocked'
    - `freshness` 'unknown' | 'fresh' | 'stale' | 'failed'
    - `price_certainty` 'unknown' | 'estimated' | 'exact'
    - `confidence` number
    - `allowed_actions` string[]
    - `blocked_actions` string[]
    - `next_action` string
    - `retryable` boolean
  - `contract_features` string[]

## Other responses

- `400`: Invalid probe request
- `401`: Unauthorized
- `404`: Capability not found
- `422`: Validation Error
- `429`: Too Many Requests
- `502`: Upstream unavailable
- `504`: Upstream timeout

---

[API](https://skmtc.dev/qveris/apis/qveris-public-rest-api.md) · [All operations](https://skmtc.dev/qveris/apis/qveris-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/qveris/apis/qveris-public-rest-api/revisions/7b78aeef092a?raw)