# API Reference

Nakalista sa page na ito ang lahat ng available na API endpoints para sa third-party integrations.

:::note[Business Tier Required]
Available lang ang API para sa mga organisasyon sa **Business tier**
o mas mataas.
:::

## Authentication

Nag-a-authenticate ang third-party integrations gamit ang **API key** na ipinapasa sa `x-api-key` header:

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

Gumagamit naman ang dashboard management endpoints ng **Clerk bearer token**:

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

---

## Public Stream Status

Lightweight availability check para sa public streams (walang API key). Gamitin ito bago i-mount ang embed o
overlay. Buong gabay: [Stream Status API](/fil/api/stream-status/).

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

**Response `200` (excerpt):**

```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" }
  }
}
```

Kapag `false` ang `available`, ang `reason` ay isa sa: `not_public`, `stream_inactive`,
`stream_not_started`, `stream_ended`, `no_games`.

---

## Session Endpoints

Ginagamit ng third-party integrations ang mga endpoint na ito para gumawa at pamahalaan ang one-time session tokens.

### Create Session

Gumagawa ng one-time session token para sa game o stream.

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

**Headers:**

| Header         | Value                    |
| -------------- | ------------------------ |
| `Content-Type` | `application/json`       |
| `x-api-key`    | Ang iyong API key (`dpk_...`) |

**Body:**

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

| Field                | Type   | Required | Paglalarawan                 |
| -------------------- | ------ | -------- | --------------------------- |
| `game_id`            | number | \*       | Target game ID              |
| `stream_id`          | number | \*       | Target stream ID            |
| `external_ref`       | string | No       | Ang iyong tracking reference     |
| `metadata`           | object | No       | Arbitrary JSON data         |
| `expires_in_minutes` | number | No       | Expiry time (default: 1440) |

\* Kailangan ang hindi bababa sa isa sa `game_id` o `stream_id`.

**Response `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

Sinusuri kung valid pa ang session token nang hindi ito kinokonsumo.

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

**Query Parameters:**

| Parameter | Type          | Required | Paglalarawan                   |
| --------- | ------------- | -------- | ----------------------------- |
| `token`   | string (UUID) | Yes      | Ang session token na beberipikahin |

**Response `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

Atomically kinokonsumo ang session token para hindi ito muling magamit.

```
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"
}
```

| Field         | Type          | Required | Paglalarawan                  |
| ------------- | ------------- | -------- | ---------------------------- |
| `token`       | string (UUID) | Yes      | Ang session token na kokonsumin |
| `player_uuid` | string        | No       | UUID na nagpapakilala sa manlalaro  |

**Response `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" }
  }
}
```

**Response `410` (already consumed/expired):**

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

---

## API Key Management Endpoints

Nangangailangan ang mga endpoint na ito ng **Clerk bearer token** at ginagamit ng DailyPlay dashboard para pamahalaan ang
API keys.

### List API Keys

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

Ibinabalik ang lahat ng API keys para sa tinukoy na organisasyon.

---

### 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"
}
```

**Response `200`:**

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

:::caution
Kasama lang ang `key` field sa creation response. Hindi na ito mababawi muli.
:::
---

### Update / Revoke API Key

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

**Body:**

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

Itakda ang `is_active` sa `false` para i-revoke ang key, o `true` para i-reactivate ito.

---

### Delete API Key

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

Permanenteng tinatanggal ang API key record.

---

## Error Responses

Sumusunod ang lahat ng error responses sa format na ito:

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

### Status Codes

| Code  | Kahulugan                                                        |
| ----- | -------------------------------------------------------------- |
| `200` | Success                                                        |
| `400` | Bad request — missing o invalid parameters                    |
| `401` | Unauthorized — invalid o revoked API key / missing auth       |
| `403` | Forbidden — walang access ang key sa requested resource |
| `410` | Gone — na-consume na o nag-expire na ang session token               |
| `429` | Too Many Requests — nalampasan ang rate limit                        |
| `500` | Internal server error                                          |