Discover tools
Describe a capability to receive ranked tool candidates without executing a tool.
View as MarkdownEndpoint
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/discoverRequest 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 | — |