# API Reference

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

:::note[需要 Business 层级]
API 仅适用于 **Business 层级**或更高的组织。
:::

## Authentication

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

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

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

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

---

## Public Stream Status

公开 streams 的轻量可用性检查（无需 API key）。在挂载嵌入或浮层前使用。完整指南：[Stream Status API](/zh/api/stream-status/)。

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

**响应 `200`（摘录）：**

```json
{
  "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：**

```json
{
  "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`：**

```json
{
  "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`：**

```json
{
  "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：**

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

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

**响应 `200`：**

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

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

```json
{
  "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：**

```json
{
  "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`：**

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

:::caution
`key` 字段仅包含在创建响应中。无法再次检索。
:::
---

### Update / Revoke API Key

```
PATCH /api/org-api-keys
```

**Body：**

```json
{
  "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

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

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

### Status Codes

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