API Reference

The PlaylogiQ public REST API is versioned under /api/v1.

Base URL: https://api.playlogiq.com/api/v1
Machine-readable spec (OpenAPI 3.1): /api/v1/openapi.json

The OpenAPI document is the source of truth — paste it into any OpenAPI viewer (Swagger UI, Redoc, Insomnia, Postman) to explore request/response schemas.

Authentication

Every endpoint except GET /health and the spec itself requires an operator API key, sent in the x-api-key header:

x-api-key: plq_your_api_key

API keys are tenant-scoped. Brand-scoped endpoints additionally accept an optional brand selector — either the x-brand header or the ?brand= query parameter — whose value is a brand id (UUID) or slug. When omitted, the tenant’s default brand is used.

x-api-key: plq_your_api_key
x-brand: main          # optional — brand id or slug

Conventions

Content type: application/json for all request and response bodies.
Single resources are returned as { "data": { ... } }.
Collections return either { "data": [...], "pagination": {...} } (players, missions) or { "items": [...], "total": n } style wrappers (campaigns, templates) — see the spec for the exact shape per endpoint.
Errors return { "error": string, "code"?: string, "details"?: object } with an appropriate HTTP status (400, 401, 404, 500).

Endpoints

System

Method	Path	Description
GET	`/health`	Service status + Supabase connectivity (public, no API key).

Events

Method	Path	Description
POST	`/events`	Ingest a single event or a batch (up to 100). Players are upserted by `player_id`.

Single event:

{
  "player_id": "player-123",
  "event_type": "player.deposit",
  "payload": { "amount": 100, "currency": "EUR" }
}

Batch (up to 100 events):

{
  "events": [
    { "player_id": "p1", "event_type": "player.login", "payload": {} },
    { "player_id": "p2", "event_type": "player.deposit", "payload": { "amount": 50 } }
  ]
}

Players

Method	Path	Description
GET	`/players`	List players (paginated; `search`, `status` filters).
POST	`/players`	Create or upsert a player by `external_id`.
GET	`/players/{id}`	Get a player (UUID) with its profile.
PATCH	`/players/{id}`	Update status, email, phone, or metadata (shallow-merged).

Segments

Method	Path	Description
GET	`/segments`	List segments (optional `type` filter).
POST	`/segments`	Create a segment.

Campaigns

Method	Path	Description
GET	`/campaigns`	List campaigns (paginated; `status` filter).
POST	`/campaigns`	Create a campaign.
GET	`/campaigns/{id}`	Get a campaign.
PATCH	`/campaigns/{id}`	Update fields or transition status.
DELETE	`/campaigns/{id}`	Soft-cancel (sets status `cancelled`).

Campaign status transitions are validated: draft → scheduled | running, scheduled → running | cancelled, running → paused | cancelled, paused → running | cancelled; completed and cancelled are terminal.

Notifications

Method	Path	Description
GET	`/notifications/templates`	List templates (`channel`, `active` filters).
POST	`/notifications/templates`	Create a template (auto-extracts `{{variables}}`).
GET	`/notifications/templates/{id}`	Get a template.
PATCH	`/notifications/templates/{id}`	Update a template.
DELETE	`/notifications/templates/{id}`	Deactivate (sets `active=false`).
POST	`/notifications/send`	Queue a notification to a player (returns `202`).

Gamification

Method	Path	Description
GET / POST	`/gamification/levels`	List / create loyalty levels.
GET / PATCH / DELETE	`/gamification/levels/{id}`	Read / update / delete a level.
GET / POST	`/gamification/missions`	List (paginated, `status`/`type`) / create missions.
GET / PATCH / DELETE	`/gamification/missions/{id}`	Read / update / delete a mission.
GET / POST	`/gamification/badges`	List / create badges.
GET / PATCH / DELETE	`/gamification/badges/{id}`	Read / update / delete a badge.
GET / POST	`/gamification/currencies`	List / create point currencies.
GET / PATCH / DELETE	`/gamification/currencies/{id}`	Read / update / delete a currency.
GET	`/gamification/player/{playerId}`	Full gamification profile: level, balances, active missions, badges.

Bonuses

Method	Path	Description
GET / POST	`/bonuses`	List / create bonuses.
GET / PATCH / DELETE	`/bonuses/{id}`	Read / update / delete a bonus.

Tournaments

Method	Path	Description
GET / POST	`/tournaments`	List / create tournaments.
GET / PATCH / DELETE	`/tournaments/{id}`	Read / update / delete a tournament.

SDK

The official @playlogiq/sdk wraps the Events and Players endpoints. See the Quick Start on the home page for installation and usage.

Architecture