# 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.

1. Create a token from [Dashboard > Settings > API Access](/dashboard/api_tokens)
2. Send the token as a bearer token with each request
3. Use the full plaintext token shown right after creation. The token name and the last four characters shown later will not authenticate.

```http
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:

```bash
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](/.well-known/oauth-authorization-server)
and the API contract in the
[OAuth protected resource metadata](/.well-known/oauth-protected-resource/api).
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](/openapi.json)
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](/openapi.json) for agents, code generators, and API tooling
- [Compact guest OpenAPI JSON](/openapi/guest.json) for five unauthenticated schedule operations
- [Compact manager OpenAPI JSON](/openapi/manager.json) for OAuth-authenticated schedule onboarding and management
- [Interactive Playpass API docs](/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](/dashboard/api_tokens)
- Install the `playpass` CLI with `curl -fsSL https://playpass.com/install.sh | sh`
- Download the machine-readable [OpenAPI specification](/openapi.json)
- Choose a compact [guest](/openapi/guest.json) or [manager](/openapi/manager.json) contract for function calling
- Review endpoints and request/response examples in the [Playpass API docs](/api/docs)