# Discover tools

Describe a capability to receive ranked tool candidates without executing a tool.

## Endpoint

candidates contains each tool, its rank, matchReasons and limitations. retrievalMode reports hybrid or keyword_fallback; semanticCoverage reports complete, partial or unavailable. These are retrieval signals, not a guarantee of data quality.

Describe one capability in your own words. If only keyword search is available and results are weak, retry with a shorter phrase and a known platform or capability name.

Discovery does not consume tool credits. Choose a candidate, then inspect its exact revision before execution.

```
POST /v1/discover
```

## Request body

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| query | string | Required | Min length: 1; Max length: 2000 |
| limit | integer | Optional / conditional | Minimum: 1; Maximum: 20; Default: 5 |
| providerId | string | Optional / conditional | — |
| category | string | Optional / conditional | — |

## Request example

Set PURRKEY_API_KEY in your trusted server or terminal environment. Replace any angle-bracket placeholders with values from your own inspection or Run.

```
curl --fail-with-body --request POST 'https://api.purrkey.app/v1/discover' \
  -H "Authorization: Bearer $PURRKEY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"query":"public video comments","limit":5}'
```

## Successful response

Success HTTP status: 200. Top-level response fields are listed below. Conditional and nested requirements are defined in the downloadable OpenAPI contract.

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| requestId | string | Required | — |
| catalogVersion | string | Required | — |
| retrievalMode | string | Required | hybrid \| keyword_fallback |
| semanticCoverage | string | Required | complete \| partial \| unavailable |
| degradationReason | string | Optional / conditional | — |
| candidates | object[] | Required | — |

## Errors and related reading

- [Error handling](/docs/guides/errors): Read requestId, business codes and safe retry behavior.
- [Download OpenAPI](/docs/openapi.yaml): The complete HTTP contract, version 0.4.3.