---
title: "Discover capabilities"
method: POST
path: "/search"
tags: ["Discovery"]
---

# Discover capabilities

`POST /search`

## Request

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

Find ranked capabilities from a natural-language query. Discover is free. Results include verification evidence and execution restrictions; clients must not treat any status other than `verified` as verified. Results may include `expected_cost` and `billing_rule` so clients can estimate a later Call.

## Request body

- PublicSearchRequest
  - `query` string, required: Natural-language capability query or an exact tool ID for deterministic lookup.
  - `limit` integer: Maximum number of ranked results to return.
  - `session_id` string: Optional tracking and pricing-context identifier. It does not promise a cache hit.
  - `view` 'routing' | 'full': Response projection. `routing` returns compact routing cards (`tool_id`, `capability`, `cost_class`, `reliability`, `as_of_support`) plus the required verification and restriction contract; `full` or omitted returns the complete result shape.
  - `lang` 'zh' | 'en': Response language. When omitted the service negotiates from the `Accept-Language` header.

## Response `200`

Successful Response

- PublicSearchResponse
  - `query` string, required
  - `search_id` string, required
  - `total` integer, required
  - `results` PublicCapabilityResult[], required
    - `tool_id` string, required
    - `name` string
    - `tool_name` string
    - `description` string
    - `updated_at` string: Catalog update timestamp when provided by the source.
    - `provider_id` string
    - `provider_name` union: Provider display name as text or a locale-keyed text map.
      - string
      - object
    - `provider_description` string
    - `category` string
    - `categories` union[]: Categories/tags attached to the capability. Current responses return category objects; legacy responses returned plain strings.
      - union
        - PublicToolCategory: Category/tag attached to a capability.
          - `slug` string
          - `name` string
          - `description` string
        - string
    - `capabilities` PublicToolCapability[]: Standardized capability descriptors with coverage tags.
      - `id` string
      - `tag` PublicCapabilityTag[]
        - `id` string
        - `name` string
        - `type` string
        - `description` string
    - `region` string
    - `score` number
    - `why_recommended` string: Human-readable explanation of why this capability was recommended for the query. Returned by Discover.
    - `params` union: Provider parameter contract preserved for catalog inspection.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `parameters` union: Alternative public input contract when supplied by the provider.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `input_schema` union: Provider input schema used by catalog verification.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `parameters_schema` union: Provider parameter schema used by catalog verification.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `query_params` union: Provider query-parameter contract used by catalog verification.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `body_params` union: Provider request-body parameter contract used by catalog verification.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `requestBody` union: OpenAPI request body contract used by catalog verification.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `output_schema` union: Public output schema advertised by the capability when available.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `examples` object
    - `stats` PublicToolStats
      - `avg_execution_time_ms` number, nullable
      - `success_rate` number, nullable
      - `sample_count` integer
      - `quality_sample_count` integer
      - `metrics_sample_count` integer
      - `success_rate_sample_count` integer
      - `latency_sample_count` integer
      - `minimum_sample_count` integer
      - `success_rate_minimum_sample_count` integer
      - `latency_minimum_sample_count` integer
      - `data_status` 'available' | 'insufficient' | 'stale' | 'unavailable'
      - `quality_data_status` 'available' | 'insufficient' | 'stale' | 'unavailable'
      - `success_rate_status` 'available' | 'insufficient' | 'stale' | 'unavailable'
      - `latency_status` 'available' | 'insufficient' | 'stale' | 'unavailable'
      - `metric_window` string
      - `window` string
      - `window_label` string
      - `window_start` string, date-time
      - `window_end` string, date-time
      - `metrics_updated_at` string, date-time
      - `last_checked_at` string, date-time
    - `has_last_execution` boolean: Whether the capability has a recorded execution used as a bounded verification signal.
    - `expected_cost` string: Pre-call cost estimate returned by Discover/Inspect when available.
    - `cost` union: Legacy cost estimate. Prefer `expected_cost` and `billing_rule` for pre-call display.
      - number
      - string
    - `billing_rule` PublicBillingRule: Capability billing rule used for pre-call estimation. Final settlement is reflected in usage audit and credits ledger endpoints.
    - `calls_count` string
    - `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
    - `capability` string: Compact capability summary. Returned instead of the full descriptor fields when the request sets `view: routing`.
    - `cost_class` string: Coarse cost tier (e.g. `low`). Returned by the `routing` view.
    - `reliability` string: Coarse reliability grade (e.g. `A`). Returned by the `routing` view.
    - `as_of_support` boolean: Whether the capability supports as-of/point-in-time queries. Returned by the `routing` view.
  - `elapsed_time_ms` number
  - `remaining_credits` number, nullable
  - `error_message` string, nullable
  - `contract_warnings` string[]
  - `contract_features` string[]

## Other responses

- `401`: Unauthorized
- `402`: Insufficient credits
- `429`: Too Many Requests

---

[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)