Playpass Developers: API, CLI, OAuth, and AI Agents

Use the Playpass API and playpass CLI to automate workflows with your AI agents and internal tools.

Common use cases include reading schedules, registrations, memberships, bookings, waivers, and website content, plus creating or updating organizer resources.

Using an AI agent like Codex, Claude Code, or OpenClaw? Share this guide link and tell the agent exactly what you want to build or automate.

Authentication setup

Most manager automation starts with an API token.

Create a token from Dashboard > Settings > API access
Send the token as a bearer token with each request
Use the full plaintext token shown right after creation. The token name and the last four characters shown later will not authenticate.

Authorization: Bearer <your_plaintext_api_token>
X-Playpass-Api-Version: 2026-02-08

Manager API tokens are organizer-scoped and best for server-side or agent workflows. Each token is limited to the creating user's permissions for that organizer and still respects organizer pricing-plan limits.

If you open /api/... URLs directly in your browser, or your tool sends anything other than the full plaintext token, Playpass will return 401.

With PLAYPASS_API_TOKEN set to the full plaintext token:

curl "https://playpass.com/api/schedules?organizer_id=<your_organizer_slug>" \
  --oauth2-bearer "$PLAYPASS_API_TOKEN" \
  -H "X-Playpass-Api-Version: 2026-02-08"

If you need player account authorization, use the OAuth endpoints in the same API reference.

OAuth clients use the authorization-code flow with PKCE S256. Discover the complete server contract in the OAuth authorization server metadata and the API contract in the OAuth protected resource metadata. Request api:read for read-only access or api:write for read and mutation access. New clients should request the least privilege they need explicitly.

API versioning and deprecations

Playpass uses date-based API versions. The current published version is 2026-02-08. Send it in X-Playpass-Api-Version; requests that omit the header use the current version. The meta.api_version value in JSON responses confirms the version associated with the request.

Requests with an unlisted version fail with 400 unsupported_api_version. Playpass never echoes an unknown version while silently serving a different contract.

We evolve the API with these rules:

Backward-compatible additions can ship within the current version. Examples include a new optional request field, response field, resource, or endpoint.
A change that would break a documented request or response requires a new dated API version and migration instructions.
A deprecated version or field remains available for at least 90 days after its deprecation is announced, except when an urgent security, privacy, legal, or reliability issue requires a faster change.
Deprecations are published in this guide and the API reference. Affected responses include a Deprecation header. Once a removal date is scheduled, they also include a Sunset header and a link to migration instructions.

Only versions listed in this guide and the OpenAPI specification are supported. Pin the documented version in production integrations and review the guide before moving to a newer dated version.

Rate limits and retries

API responses expose the evaluated limits without revealing the identity used to partition a limit:

RateLimit-Policy describes each applicable quota and window.
RateLimit reports the remaining requests and estimated seconds until reset.
RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset provide the same primary-policy values for clients that use the transitional split fields.
A 429 Too Many Requests response includes Retry-After in seconds.

The shared API ceiling is currently 1,200 requests per IP address per minute and 600 requests per authenticated actor per minute. Sensitive or expensive operations, including token creation, OAuth exchange, payment actions, and externally triggered messages, have lower limits. When more than one policy is present, wait for Retry-After after a 429; otherwise use the most constrained remaining value and add randomized exponential backoff.

Playpass CLI

The playpass CLI wraps the same public API and is useful for shell scripts, local testing, and AI-agent workflows.

Install the latest released CLI with the wrapper script:

curl -fsSL https://playpass.com/install.sh | sh

The installer automatically:

Detects the current platform
Downloads the latest published Playpass archive
Verifies the archive against SHA256SUMS.txt
Installs playpass into a writable bin directory

Today the published binaries support:

macOS Apple Silicon (darwin-arm64)
Linux x86_64 (linux-amd64)

If you need a different install location, set PLAYPASS_INSTALL_DIR before running the script.

Use the same token and API version header defaults from above:

export PLAYPASS_API_TOKEN="<your_plaintext_api_token>"
export PLAYPASS_API_VERSION="2026-02-08"
export PLAYPASS_OUTPUT="table"

playpass schedules list --organizer-id <your_organizer_slug> --view current
playpass organizers show <your_organizer_slug>

If you need an endpoint that is not yet wrapped by a first-class command, use the raw passthrough commands:

playpass api get "/api/schedules?organizer_id=<your_organizer_slug>&view=current"

Automate an exact-date group booking page

Create a specific-date Booking Page, add an eight-person time, and publish it:

BOOKING_PAGE_ID="$(
  playpass reservation-offerings create \
    --name "Saturday Clinic" \
    --availability-mode specific_dates \
    --slot-capacity 8 \
  | jq -r '.data.reservation_offering.id'
)"

playpass reservation-offerings add-time "$BOOKING_PAGE_ID" \
  --starts-at "2026-08-08T12:00:00-04:00" \
  --capacity 8

playpass reservation-offerings publish "$BOOKING_PAGE_ID"

Use an RFC 3339 timestamp with an explicit UTC offset for --starts-at. list-times, show-time, update-time, and delete-time expose the rest of the booking-time lifecycle. The same operations are available through the nested /api/reservation_offerings/{reservation_offering_id}/reservation_slots API endpoints.

Full API reference

Raw OpenAPI JSON for agents, code generators, and API tooling
Compact guest OpenAPI JSON for five unauthenticated schedule operations
Compact manager OpenAPI JSON for OAuth-authenticated schedule onboarding and management
Interactive Playpass API docs for endpoint examples and schemas

Unknown /api/... routes return a JSON route_not_found error with a request ID, API version, and a link back to this guide. Other API errors use the same stable error and meta envelope documented in the OpenAPI contract.

What's next?

Create an API token from Dashboard > Settings > API access
Install the playpass CLI with curl -fsSL https://playpass.com/install.sh | sh
Download the machine-readable OpenAPI specification
Choose a compact guest or manager contract for function calling
Review endpoints and request/response examples in the Playpass API docs