API Overview

Base URLCopy Anchor Link

All API requests use the following base URL:

https://api.playablelabs.ai/api

Request FormatCopy Anchor Link

The API accepts and returns JSON. Include these headers in every request:

Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

AuthenticationCopy Anchor Link

Every request must include a valid token. PlayableLabs supports two authentication methods:

• JWT session tokens -- Obtained via the web app login flow (NextAuth v5)
• API tokens -- Created in Developers > Tokens for programmatic access

See the Authentication guide for details.

Rate LimitingCopy Anchor Link

The API enforces rate limits to ensure fair usage:

When rate-limited, the API returns 429 Too Many Requests with these headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000000
Retry-After: 30

Response ShapeCopy Anchor Link

Every successful response wraps the payload in a single data key. Nothing else is added to the body: there is no timestamp, path or method field.

{ "data": { "id": "a1", "name": "Merge Blitz" } }

List endpoints add a meta block next to data (see Pagination).

PaginationCopy Anchor Link

List endpoints return paginated results. Use query parameters to control pagination:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.playablelabs.ai/api/games?page=1&limit=20&sort=createdAt&order=desc"

Paginated responses return the items in data and the paging details in meta. Some endpoints add counters beside the four standard fields (for example nonDemoCount on the games list). Endpoints addressed by offset (activity and audit logs) still accept offset; meta.page is floor(offset / limit) + 1 and meta.offset echoes the requested offset.

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 54,
    "totalPages": 3
  }
}

Multi-Tenant ScopingCopy Anchor Link

All data is scoped by organization. Pass the organizationId as a query parameter or in the request body where required. You can only access data belonging to organizations you are a member of.

Error CodesCopy Anchor Link

The API uses standard HTTP status codes and returns structured error responses:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Name is required",
  "requestId": "6f1c0a52-8d0e-4c1b-9a43-0d4f6a1b2c3d"
}

requestId is the same value the API returns in the X-Request-ID response header (omitted if the error happens before the request is assigned an id). Quote it when reporting a failed request. Errors may also carry errorCode, code, suggestedName, retryAfter, param or details next to these keys; they are never nested.

Key EndpointsCopy Anchor Link

Next StepsCopy Anchor Link

• Authentication -- JWT and API token details
• SDKs and examples -- Client libraries and code samples