PlayableLabs Docs

Cơ bản về REST API, base URL, định dạng request, rate limiting, phân trang và mã lỗi của PlayableLabs

Base URL

Tất cả yêu cầu API sử dụng base URL sau:

https://api.playablelabs.ai/api

Định Dạng Request

API chấp nhận và trả về JSON. Thêm các header sau trong mỗi request:

Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

Xác Thực

Mỗi request phải có token hợp lệ. PlayableLabs hỗ trợ hai phương thức xác thực:

JWT session token -- Lấy từ quy trình đăng nhập web app (NextAuth v5)
API token -- Tạo từ Developers > Tokens để truy cập lập trình

Xem Hướng dẫn Xác Thực để biết chi tiết.

Rate Limiting

API áp dụng giới hạn tần suất để đảm bảo sử dụng công bằng:

Tầng	Giới hạn	Khung thời gian	Chiến lược
Tiêu chuẩn	100 request	1 phút	Fixed window
Endpoint nhạy cảm	20 request	1 phút	Sliding window
Export	10 request	5 phút	Fixed window

Khi bị giới hạn, API trả về 429 Too Many Requests với các header:

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

Phân Trang

Các endpoint danh sách trả về kết quả phân trang. Sử dụng query parameter để điều khiển:

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

Tham số	Kiểu	Mặc định	Mô tả
`page`	number	1	Số trang (bắt đầu từ 1)
`limit`	number	20	Số mục mỗi trang (tối đa 100)
`sort`	string	`createdAt`	Trường để sắp xếp
`order`	string	`desc`	Hướng sắp xếp: `asc` hoặc `desc`

Response phân trang bao gồm metadata:

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

Phạm Vi Đa Tổ Chức

Tất cả dữ liệu được giới hạn theo tổ chức. Truyền organizationId qua query parameter hoặc trong request body khi cần. Bạn chỉ có thể truy cập dữ liệu thuộc tổ chức mà bạn là thành viên.

Mã Lỗi

API sử dụng mã trạng thái HTTP chuẩn và trả về response lỗi có cấu trúc:

{
  "statusCode": 400,
  "error": "VALIDATION_ERROR",
  "message": "Name is required"
}

Status	Mã lỗi	Mô tả
400	`VALIDATION_ERROR`	Request body hoặc tham số không hợp lệ
401	`AUTHENTICATION_REQUIRED`	Token thiếu hoặc không hợp lệ
403	`INSUFFICIENT_PERMISSIONS`	Token thiếu quyền cần thiết
404	`RESOURCE_NOT_FOUND`	Tài nguyên không tồn tại
409	`DUPLICATE_RESOURCE`	Tài nguyên đã tồn tại
429	`RATE_LIMIT_EXCEEDED`	Quá nhiều request
500	`INTERNAL_SERVER_ERROR`	Lỗi server không mong đợi

Endpoint Chính

Method	Endpoint	Mô tả
GET	`/api/games`	Danh sách game
POST	`/api/games`	Tạo game
GET	`/api/assets`	Danh sách tài nguyên
POST	`/api/storage/urls`	Lấy URL tải lên
POST	`/api/export`	Kích hoạt xuất
GET	`/api/tokens`	Danh sách API token

Bước Tiếp Theo

Xác Thực -- Chi tiết JWT và API token
SDK và Ví Dụ -- Thư viện client và code mẫu

Tổng Quan API