# Purrkey documentation

> Guides and references for connecting agents, discovering tools and recovering paid Runs.

## Get started

- [Welcome to Purrkey](https://purrkey.app/docs/markdown): Give your agent access to external tools with one connection. Find a tool, check its inputs and price, and pay for the calls you make.
- [How Purrkey works](https://purrkey.app/docs/markdown/how-it-works): The tool tells you what it can do. A Run records what you asked for, what happened and what you paid.
- [Set up an Agent Skill](https://purrkey.app/docs/markdown/quickstart/skill): Give an agent a repeatable process for discovery, price checks, execution and recovery.
- [Connect with MCP](https://purrkey.app/docs/markdown/quickstart/mcp): Use Purrkey as a remote tool server in a client that supports Streamable HTTP.
- [Start with the CLI](https://purrkey.app/docs/markdown/quickstart/cli): Install Purrkey, connect an API key and find your first tool from the terminal.
- [Make your first API call](https://purrkey.app/docs/markdown/quickstart/api): Use the HTTP API to discover a tool, inspect its contract and submit a recoverable request.

## Guides

- [Authentication and permissions](https://purrkey.app/docs/markdown/guides/authentication): Give each client the access it needs and keep account management separate from tool execution.
- [Pricing and spending limits](https://purrkey.app/docs/markdown/guides/billing): Check the pricing unit, set a maximum charge and read the actual bill from the Run.
- [Runs, retries and cancellation](https://purrkey.app/docs/markdown/guides/runs): Recover interrupted calls using the original request identity, without buying the same task twice.
- [Results and file delivery](https://purrkey.app/docs/markdown/guides/results): Read output only when it is available, and save files within their delivery window.
- [Errors and troubleshooting](https://purrkey.app/docs/markdown/guides/errors): Use the error code and request ID to choose a next step while preserving the original Run.

## Examples

- [Try the five homepage workflows](https://purrkey.app/docs/markdown/examples/homepage-workflows): Choose a research task and follow the tool steps, sample prompts and estimated costs
- [Research public social content](https://purrkey.app/docs/markdown/examples/social-research): Turn a focused question into a bounded sample of public posts and comments with traceable sources.
- [Compare findings across sources](https://purrkey.app/docs/markdown/examples/compare-sources): Build a research brief that preserves source differences instead of treating every result as the same kind of evidence.

## API reference

- [HTTP API overview](https://purrkey.app/docs/markdown/api/overview): Build the discover → inspect → run → retrieve flow into your own application.
- [List tools](https://purrkey.app/docs/markdown/api/tools): Browse the published tools accessible to the current credential.
- [Discover tools](https://purrkey.app/docs/markdown/api/discover): Describe a capability to receive ranked tool candidates without executing a tool.
- [Inspect a tool](https://purrkey.app/docs/markdown/api/inspect): Read the selected tool's input and output schemas, fixed revisions, price and delivery rules.
- [Create a Run](https://purrkey.app/docs/markdown/api/run): Execute a balance-funded tool request with a fixed contract, spending cap and idempotency key.
- [List Runs](https://purrkey.app/docs/markdown/api/list-runs): List the current account's Runs with optional filters and cursor pagination.
- [Retrieve a Run](https://purrkey.app/docs/markdown/api/get-run): Read an original Run and its currently deliverable result without another purchase.
- [Cancel a Run](https://purrkey.app/docs/markdown/api/cancel-run): Request cancellation, then retrieve the same Run to learn its final execution and billing outcome.
- [Read your balance](https://purrkey.app/docs/markdown/api/balance): Read account funds, current reservations and whether paid calls are allowed.

## CLI reference

- [CLI overview](https://purrkey.app/docs/markdown/cli/overview): Use the purrkey executable to discover tools, make account-balance calls and recover results.
- [Keys and configuration](https://purrkey.app/docs/markdown/cli/configuration): Configure one active credential securely and understand which API origin the CLI will use.
- [Discover and inspect](https://purrkey.app/docs/markdown/cli/discover): Find a candidate tool, then read its fixed contract before creating a Run.
- [Run a tool](https://purrkey.app/docs/markdown/cli/run): Submit a saved request with a fixed price revision, spending cap and idempotency key.
- [Retrieve and cancel Runs](https://purrkey.app/docs/markdown/cli/results): Check results and request cancellation using the original Run ID.

## Contracts

- [OpenAPI](https://purrkey.app/docs/openapi.yaml)
- [Agent Skill](https://purrkey.app/SKILL.md)