# Inspect a tool

Read the selected tool's input and output schemas, fixed revisions, price and delivery rules.

## Endpoint

toolRevision is optional, but specifying the discovered revision lets you inspect that exact contract. Use the returned tool.toolRevision and tool.price.priceRevision when constructing a Run.

inputSchema and outputSchema are tool-specific JSON Schema documents. Read inputExamples and limitations; do not substitute another tool's fields.

behavior declares kind, executionMode, sideEffects, cacheScope and coalesceScope. delivery declares supportsArtifacts and windowSeconds. Cache permission and in-flight coalescing permission are independent.

```
POST /v1/inspect
```

## Request body

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| toolId | string | Required | — |
| toolRevision | 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/inspect' \
  -H "Authorization: Bearer $PURRKEY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"toolId":"<toolId>","toolRevision":"<toolRevision>"}'
```

## 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 |
| --- | --- | --- | --- |
| tool | object | Required | — |
| inputSchema | object | Required | — |
| outputSchema | object | Required | — |
| inputExamples | JSON value[] | Required | — |
| limitations | string[] | Required | — |
| supportsCancel | boolean | Required | — |
| behavior | object | Required | — |
| delivery | 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.