HTTP connection guide

Connection addresses

Website: https://purrkey.app

API: https://api.purrkey.app

MCP: https://api.purrkey.app/mcp

Skill: https://purrkey.app/SKILL.md

With the CLI installed, configure your API key

purrkey keys add YOUR_API_KEY

Replace YOUR_API_KEY with the key you create in API keys, then run the command. The CLI connects to Purrkey.ai automatically, verifies access and saves your key

Authenticate your client

Create a scoped API key in API keys. Send it as Authorization: Bearer <your key> to the API origin shown above. Do not put keys in URLs, browser storage, or conversation messages

Google sign-in sessions manage your account on the website. API keys grant the tool scopes you select

Discover and inspect

POST /v1/discover
{"query":"public video comments"}

POST /v1/inspect
{"toolId":"<candidate toolId>","toolRevision":"<revision>"}

Inspect the tool’s JSON schemas, limitations, price revision, and freshness. Discovery candidates are suggestions; your client chooses a tool

Submit a call from your client

{
  "toolId": "<selected toolId>",
  "toolRevision": "<inspected revision>",
  "priceRevision": "<inspected priceRevision>",
  "input": "<value matching inputSchema>",
  "idempotencyKey": "<unique key saved for this request>",
  "maxChargeMicros": "<maximum charge>",
  "funding": {
    "mode": "balance"
  }
}

Use POST /v1/runs. Preserve the same idempotency key and effective request after a lost response. A changed request requires a new key

Retrieve the original result

GET /v1/runs/{runId} reads the original call without a new purchase. A 202 response means processing is incomplete. Keep the Run ID and follow the server’s polling guidance

Read output only when result.status is available. JSON null is a valid output. If the result is expired, the original bill still applies and no new call is made. Never infer cancellation, free usage, or a final charge from a browser timeout

Cancellation uses POST /v1/runs/{runId}/cancel. Acceptance does not confirm that the supplier stopped. Check the original call again