developers

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 so a crawler does not have to render this page to find them.

Papayya API

OpenAPI 3.1 specification: /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 — 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 <token>, 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 "<timestamp>.<body>") 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
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

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.

Machine-readable files on this site

/llms.txt: /llms.txt — site index for agents, with explicit when-to-use guidance.
/openapi.json: /openapi.json — OpenAPI 3.1 description of the API.
/sitemap.xml: /sitemap.xml — every indexable URL with a lastmod date.
/robots.txt: /robots.txt — crawl policy and sitemap pointer.
/.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 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 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.