# Papayya developer resources > Every machine-readable entry point into Papayya: the REST API, the OpenAPI 3.1 specification, the Python SDK and CLI, authentication, webhooks and error semantics. This page is the index a developer — or an agent acting for one — should start from. Each entry is a stable URL, and each is listed again in [/llms.txt](/llms.txt) so a crawler does not have to render this page to find them. ## Papayya API - **OpenAPI 3.1 specification** — [/openapi.json](/openapi.json) — the full typed surface. Every operation carries a unique `operationId`, a description, typed parameters and response schemas, which is what makes it usable directly as an LLM function-calling tool set. - **REST API reference** — [https://docs.getpapayya.com/api](https://docs.getpapayya.com/api) — prose reference with request and response examples, terminal error codes, and webhook payload shapes. - **Base URL** — Your own install's origin. Papayya's server runs in your infrastructure, so the base URL is a hostname you chose — `http://localhost:8090` when the stack runs on one machine. Point the SDK and CLI at it with `PAPAYYA_BASE_URL`. - **Authentication** — Every protected endpoint takes `Authorization: Bearer `, where the token is either a project API key (prefix `pk_`) or a session JWT. Keys are created per project in the dashboard or with `papayya api-keys`. A key is scoped to its project and cannot reach another project's items. - **Errors** — Errors are JSON, never HTML. The body is `{ "error": { "code", "message" } }` — `code` is a stable machine-readable string, safe to branch on; `message` is for a human. Some endpoints add `hint`, `status` and `docs`. Branch on `code`, never on the wording of `message`. - **Webhooks** — Set `callback_url` on a run to receive a POST on every terminal transition. Each delivery is signed with `X-Papayya-Signature` (HMAC-SHA256 over `"."`) and `X-Papayya-Timestamp`. Verify both before trusting the payload. ## Papayya CLI The `papayya` CLI is the official command-line tool and is published on PyPI. It is the fastest way for an agent to drive Papayya without writing an HTTP client. - Install: `pip install papayya` (or `uv tool install papayya`) — [pypi.org/project/papayya](https://pypi.org/project/papayya/) - Authenticate: `papayya login` (or set `PAPAYYA_API_KEY`) - Run and inspect: `papayya run`, `papayya runs list`, `papayya runs submit`, `papayya items list`, `papayya items get`, `papayya items stream` - Recover: `papayya triage list`, `papayya replay`, `papayya resume`, `papayya verify`, `papayya release` - Operate: `papayya deploy`, `papayya agents`, `papayya schedules`, `papayya triggers`, `papayya secrets`, `papayya usage`, `papayya rate-card` - Reference: [https://docs.getpapayya.com/cli](https://docs.getpapayya.com/cli) ## Papayya Python SDK The same PyPI distribution ships the SDK. The floor of adoption is one decorator: put `@agent` on the function you already have, and each item it processes becomes independently graded, replayable and priced. Reference at [https://docs.getpapayya.com/sdk](https://docs.getpapayya.com/sdk). ## Machine-readable files on this site - **/llms.txt** — [/llms.txt](/llms.txt) — site index for agents, with explicit when-to-use guidance. - **/openapi.json** — [/openapi.json](/openapi.json) — OpenAPI 3.1 description of the API. - **/sitemap.xml** — [/sitemap.xml](/sitemap.xml) — every indexable URL with a lastmod date. - **/robots.txt** — [/robots.txt](/robots.txt) — crawl policy and sitemap pointer. - **/.well-known/security.txt** — [/.well-known/security.txt](/.well-known/security.txt) — RFC 9116 vulnerability reporting. ## Markdown content negotiation Every page on this site is served as markdown to a client that asks for it. Send `Accept: text/markdown` to any page URL and you get `text/markdown; charset=utf-8` back, with `Vary: Accept` set so a cache never hands you the wrong variant. Appending `.md` to a page path works too, so [/developers.md](/developers.md) is this page as markdown without a header. ## Status The SDK and CLI are published and installable today. The server they talk to is one you run, so the specification at [/openapi.json](/openapi.json) describes the API your own control plane serves — every operation in it is callable the moment your install is up. There is no shared endpoint to be granted access to.