# Make your first API call

Use the HTTP API to discover a tool, inspect its contract and submit a recoverable request.

## Authenticate from your application

The API base URL is https://api.purrkey.app. Store your API key as PURRKEY_API_KEY in your server or terminal environment. The examples use that variable so you do not need to paste credentials into request files.

> Use the key on a trusted server or local client. Never ship it in public browser JavaScript.

```
curl --fail-with-body 'https://api.purrkey.app/v1/balance' \
  -H "Authorization: Bearer $PURRKEY_API_KEY"
```

## Discover a capability

Choose a candidate from candidates, then copy its toolId and toolRevision. Discovery recommends tools; it does not run them.

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

## Inspect the chosen tool

Use inputSchema to construct input. Copy tool.toolRevision and tool.price.priceRevision from the inspection. Read the price unit, limitations and behavior before deciding how much a bounded call can cost.

Context.dev tools priced per credit settle using verified creditsUsed. Brand search has a zero user price; availability limits still apply. Read the inspected price and request limit before submitting.

```
curl --fail-with-body 'https://api.purrkey.app/v1/inspect' \
  -H "Authorization: Bearer $PURRKEY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"toolId":"<toolId>","toolRevision":"<toolRevision>"}'
```

## Save your request

This is a template, not an executable request. Replace every placeholder, including the input object and spending cap. Amounts are decimal integer strings: 1000000 micro-units equals 1 USD. The cap must cover your bounded request at the inspected price.

```
{
  "toolId": "<toolId from inspect>",
  "toolRevision": "<toolRevision from inspect>",
  "priceRevision": "<priceRevision from inspect>",
  "input": {
    "<required field>": "<value matching inputSchema>"
  },
  "idempotencyKey": "<unique key saved for this task>",
  "maxChargeMicros": "<integer spending cap in USD micro-units>",
  "funding": {
    "mode": "balance"
  }
}
```

## Submit and keep the Run ID

HTTP 202 means the Run was accepted and billing is still HELD or REVIEW; execution may already have ended. HTTP 200 does not by itself prove successful execution. Keep runId and check status, billing and result separately. If the response is lost, resend the identical request file with its original idempotency key.

```
curl --fail-with-body 'https://api.purrkey.app/v1/runs' \
  -H "Authorization: Bearer $PURRKEY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json
```

## Retrieve the original result

GET returns the current Run with HTTP 200 even when work is still pending. Follow pollAfterMs when present. Read output only when result.status is available; polling does not make a new purchase.

```
curl --fail-with-body 'https://api.purrkey.app/v1/runs/<runId>' \
  -H "Authorization: Bearer $PURRKEY_API_KEY"
```

- [API reference](/docs/api/overview): Request fields, response fields and endpoint behavior.