API Reference

本页列出第三方集成的所有可用 API 端点。

Authentication

第三方集成使用在 x-api-key 头中传递的 API key 进行身份验证：

curl -H "x-api-key: dpk_YOUR_API_KEY" https://app.dailyplay.ai/api/...

面板管理端点改用 Clerk bearer token：

curl -H "Authorization: Bearer <clerk_token>" https://app.dailyplay.ai/api/...

Public Stream Status

公开 streams 的轻量可用性检查（无需 API key）。在挂载嵌入或浮层前使用。完整指南：Stream Status API。

GET /api/stream-status?org_slug=<org-slug>&stream_slug=<stream-slug>

响应 200（摘录）：

{
  "success": true,
  "data": {
    "available": true,
    "reason": null,
    "total_games": 4,
    "timezone": "UTC",
    "server_time": "2026-10-15T07:23:43.597Z",
    "stream": { "slug": "summer-campaign", "status": "active" },
    "organization": { "slug": "your-org" }
  }
}

当 available 为 false 时，reason 为以下之一：not_public、stream_inactive、stream_not_started、stream_ended、no_games。

Session Endpoints

这些端点由第三方集成用于创建与管理一次性会话令牌。

Create Session

为游戏或 stream 创建一次性会话令牌。

POST /api/org-api-keys?action=create-session

Headers：

Header	Value
`Content-Type`	`application/json`
`x-api-key`	您的 API key（`dpk_...`）

Body：

{
  "game_id": 42,
  "stream_id": null,
  "external_ref": "user-12345",
  "metadata": { "campaign": "summer-promo" },
  "expires_in_minutes": 60
}

字段	类型	必填	说明
`game_id`	number	*	目标游戏 ID
`stream_id`	number	*	目标 stream ID
`external_ref`	string	否	您的追踪参考
`metadata`	object	否	任意 JSON 数据
`expires_in_minutes`	number	否	过期时间（默认：1440）

* 至少需要 game_id 或 stream_id 之一。

响应 200：

{
  "success": true,
  "data": {
    "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "stream_id": null,
    "game_id": 42,
    "expires_at": "2026-02-17T12:00:00.000Z",
    "external_ref": "user-12345"
  }
}

Validate Session

检查会话令牌是否仍有效，而不消费它。

GET /api/org-api-keys?action=validate-session&token=<uuid>

查询参数：

参数	类型	必填	说明
`token`	string (UUID)	是	要验证的会话令牌

响应 200：

{
  "success": true,
  "data": {
    "valid": true,
    "status": "active",
    "stream_id": null,
    "game_id": 42,
    "expires_at": "2026-02-17T12:00:00.000Z",
    "external_ref": "user-12345",
    "metadata": { "campaign": "summer-promo" }
  }
}

Consume Session

原子地消费会话令牌，使其无法重复使用。

POST /api/org-api-keys?action=consume-session

Headers：

Header	Value
`Content-Type`	`application/json`

Body：

{
  "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "player_uuid": "player-uuid-here"
}

字段	类型	必填	说明
`token`	string (UUID)	是	要消费的会话令牌
`player_uuid`	string	否	标识玩家的 UUID

响应 200：

{
  "success": true,
  "data": {
    "session_id": 1,
    "org_id": 5,
    "stream_id": null,
    "game_id": 42,
    "external_ref": "user-12345",
    "metadata": { "campaign": "summer-promo" }
  }
}

响应 410（已消费/已过期）：

{
  "success": false,
  "error": "Session is invalid, already consumed, or expired"
}

API Key Management Endpoints

这些端点需要 Clerk bearer token，由 DailyPlay 面板用于管理 API keys。

List API Keys

GET /api/org-api-keys?org_id=<id>

返回指定组织的所有 API keys。

Create API Key

POST /api/org-api-keys

Body：

{
  "org_id": 1,
  "name": "Production CRM",
  "description": "Used by the CRM to issue game links",
  "allowed_game_ids": [42, 43],
  "allowed_stream_ids": null,
  "rate_limit_per_minute": 60,
  "rate_limit_per_day": 10000,
  "expires_at": "2027-01-01T00:00:00Z"
}

响应 200：

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Production CRM",
    "key_prefix": "dpk_a1b2",
    "key": "dpk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Update / Revoke API Key

PATCH /api/org-api-keys

Body：

{
  "id": 1,
  "org_id": 1,
  "is_active": false
}

将 is_active 设为 false 以撤销密钥，或设为 true 以重新激活。

Delete API Key

DELETE /api/org-api-keys?id=<id>&org_id=<id>

永久移除 API key 记录。

Error Responses

所有错误响应遵循此格式：

{
  "success": false,
  "error": "Description of what went wrong"
}

Status Codes

代码	含义
`200`	成功
`400`	错误请求 — 缺少或无效的参数
`401`	未授权 — 无效或已撤销的 API key / 缺少认证
`403`	禁止 — 密钥无权访问所请求的资源
`410`	已失效 — 会话令牌已被消费或已过期
`429`	请求过多 — 超过速率限制
`500`	内部服务器错误