# PlayerOS API — Developer & Agent Reference

> Markdown reference for the PlayerOS REST API, for AI agents and developers.
> Machine-readable spec: https://playeros.ai/openapi.json (YAML: https://playeros.ai/openapi.yaml)
> Authentication guide: https://playeros.ai/auth.md

PlayerOS is a casino marketing and player-engagement platform. This API gives
programmatic access to the player database, multi-channel campaigns (email, SMS,
AI voice, web push, Player Inbox), journeys, games, and TCPA/CCPA/GDPR compliance.

- **Base URL:** `https://api.playeros.ai`
- **Auth:** property-scoped API keys via the `X-Api-Key` header (see Authentication)
- **Format:** JSON request and response bodies

## Authentication

PlayerOS uses **property-scoped API keys**. Each key starts with `pk_`, is bound to a
single property (tenant), and carries `read` and/or `write` scopes.

1. Sign in at https://playeros.ai → **Settings → API Keys**.
2. **Generate Key**, copy the secret (shown once; only a hash is stored).
3. Send it as the `X-Api-Key` header on every request.

```bash
curl https://api.playeros.ai/api/players \
  -H "X-Api-Key: pk_your_key_here"
```

Dashboard sessions may instead use a Cognito JWT via `Authorization: Bearer <token>`.
Programmatic key management: `POST /api/functions/create-api-key`, `list-api-keys`,
`revoke-api-key`.

### Scopes

| Scope   | Grants                                                            |
|---------|------------------------------------------------------------------|
| `read`  | List and retrieve resources (players, campaigns, content, stats).|
| `write` | Create, update, send, and delete resources.                      |

Every key is bound to one property. A JWT user with multiple properties selects one
with the `X-Property-Id: <uuid>` header.

## Conventions

- **Functions** (most writes): `POST /api/functions/{name}` with a JSON body.
- **Table CRUD:** `GET|POST|PATCH|DELETE /api/{table}` (and `/api/{table}/{id}`).
- **Filters** (PostgREST-style): `?email.ilike=%jane%&status.eq=active&order=created_at.desc&limit=50`.
  Operators: `eq, neq, gt, gte, lt, lte, like, ilike, in, is, not`.
- **Errors:** JSON `{ "error": "..." }`. `401` (auth), `403` (scope/permission),
  `404` (not found), `429` (rate limited, with `retry_after`).

## Endpoints by area

### Authentication & API keys
- `POST /api/auth/login` — obtain a user JWT (public)
- `POST /api/auth/me` — current user
- `POST /api/functions/create-api-key` — issue a key `{ property_id, name, scopes[] }`
- `POST /api/functions/list-api-keys` — list keys for a property
- `POST /api/functions/revoke-api-key` — revoke `{ key_id }`

### Players
- `GET /api/players` — list/search (filters, `order`, `limit`, `offset`)
- `GET /api/players/{id}` — retrieve
- `POST /api/players` — create
- `PATCH /api/players/{id}` — update
- `DELETE /api/players/{id}` — delete

Gaming-specific fields include `player_id`, `tier`, `adt`, `coin_in`, `status`.

### Campaigns
- `POST /api/functions/send-campaign` — send an email campaign `{ campaignId, propertyId }`
- `POST /api/functions/send-sms-campaign` — send an SMS campaign (TCPA pre-check)
- `GET /api/campaigns` / `POST /api/campaigns` — manage campaigns

### Consent & compliance (TCPA)
- `POST /api/functions/consent-record` — record a consent event with audit trail
- `POST /api/functions/consent-revoke` — revoke consent
- `POST /api/functions/compliance-check` — pre-send check against suppression/DNC/consent

### Data privacy (CCPA / GDPR)
- `POST /api/functions/data-export` — export all data for a player
- `POST /api/functions/data-deletion` — right-to-erasure

### Webhooks
PlayerOS delivers signed event callbacks (campaign, player, consent, game events) with
retries. Manage subscriptions via CRUD on `/api/webhook_endpoints` (`{ url, events[] }`).

**Signature verification.** Each delivery includes `X-PlayerOS-Event`,
`X-PlayerOS-Timestamp` (Unix seconds), and `X-PlayerOS-Signature: v1=<hmac>`. Verify by
computing `v1=` + `HMAC-SHA256(signing_secret, "{timestamp}.{raw_body}")` (hex) and
comparing in constant time. Reject deliveries whose timestamp is older than a few
minutes to prevent replay.

```python
import hmac, hashlib
expected = "v1=" + hmac.new(secret.encode(), f"{ts}.{raw_body}".encode(), hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, received_signature)
```

## Rate limits

Each API key carries a configurable rate-limit value (default 100). Every response
includes advisory `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`
(Unix seconds) headers. Authentication endpoints are additionally throttled per IP and
per account; throttled requests return `429` with `retry_after`.

## Versioning & deprecation

The API is date-versioned. Every response carries an `API-Version` header (current:
`2026-06-05`). Changes are additive wherever possible; deprecations are announced via
`Deprecation` and `Sunset` (RFC 8594) response headers before any removal.

## MCP server

An MCP server (Streamable HTTP) for AI agents is at `https://api.playeros.ai/api/mcp`
(discovery: `https://playeros.ai/.well-known/mcp.json`). It exposes PlayerOS operations
as agent tools and authenticates with the same property-scoped API key.

## More

- OpenAPI spec: https://playeros.ai/openapi.json
- Authentication guide: https://playeros.ai/auth.md
- AI plugin manifest: https://playeros.ai/.well-known/ai-plugin.json
- llms.txt: https://playeros.ai/llms.txt
- Human docs: https://playeros.ai/api-docs