# Stream Status API

Gamitin ang **Stream Status** endpoint para tanungin ang DailyPlay kung dapat ipakita ang stream ngayon —
bago mo i-mount ang iframe, floating Play button, o custom overlay sa iyong site.

Ito ay **public GET** (walang API key). Dinisenyo ito para sa site at app owners na gusto:

- Magpakita ng stream overlay **habang active lang ang stream**
- Itago ang Play buttons kapag hindi pa nagsimula o natapos na ang campaign
- Iwasan ang pag-load ng full stream player kapag walang published games

:::tip[Lightweight by design]
Hindi tulad ng full stream player payload, **hindi** ibinabalik ng endpoint na ito ang game configs o prizes at
**hindi** nagrerecord ng analytics. Mas gusto ito para sa availability gating; i-load ang stream URL lang kapag
`available` ay `true`.
:::

## Endpoint

```
GET https://app.dailyplay.ai/api/stream-status?org_slug=<org-slug>&stream_slug=<stream-slug>
```

| Parameter     | Required | Paglalarawan                                      |
| ------------- | -------- | ------------------------------------------------ |
| `org_slug`    | Yes      | Organization slug (mula sa stream share URL)    |
| `stream_slug` | Yes      | Stream slug (mula sa stream share URL)          |

**Auth:** none  
**CORS:** `Access-Control-Allow-Origin: *` (ligtas na tawagin mula sa browser)  
**Cache:** `public, s-maxage=30, stale-while-revalidate=60` — maaaring mag-poll ang hosts tuwing ~30s

### Halimbawa

```
https://app.dailyplay.ai/api/stream-status?org_slug=your-org&stream_slug=summer-campaign
```

## Response

Ang HTTP `200` na may `success: true` ay nangangahulugang nahawakan ang request. Gamitin ang **`data.available`** para magdesisyon
kung ipapakita ang stream UI.

### Available

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

### Unavailable

```json
{
  "success": true,
  "data": {
    "available": false,
    "reason": "stream_inactive",
    "total_games": 0,
    "starts_at": null,
    "ends_at": null,
    "timezone": "UTC",
    "server_time": "2026-10-15T07:23:43.597Z",
    "stream": {
      "slug": "summer-campaign",
      "status": "draft"
    },
    "organization": {
      "slug": "your-org"
    }
  }
}
```

### Response fields

| Field                     | Type           | Paglalarawan |
| ------------------------- | -------------- | ----------- |
| `available`               | boolean        | `true` kapag maaaring laruin ng mga bisita ang stream |
| `reason`                  | string \| null | Bakit hindi available ang stream (`null` kapag available) |
| `total_games`             | number         | Bilang ng **published** games sa stream (`0` kapag hindi public) |
| `starts_at` / `ends_at`   | string \| null | Schedule bounds bilang ISO UTC (mula sa stream timezone) |
| `timezone`                | string         | Stream timezone na ginagamit para sa schedule checks |
| `server_time`             | string         | Server clock (ISO UTC) para sa desisyon |
| `stream.slug` / `status`  | string         | Stream identity at status |
| `organization.slug`       | string         | Organization slug |

### Unavailable reasons

| `reason`             | Kahulugan |
| -------------------- | ------- |
| `not_public`         | Hindi public ang stream (hindi nilalabas ang details) |
| `stream_inactive`    | Hindi `active` ang stream status (hal. draft / archived) |
| `stream_not_started` | Bago pa ang current time kaysa `starts_at` |
| `stream_ended`       | Lampas na ang current time sa `ends_at` |
| `no_games`           | Active/public ang stream pero walang published games |

### Error responses

| Code | Kailan |
| ---- | ---- |
| `400` | Nawawala ang `org_slug` o `stream_slug` |
| `404` | Hindi nahanap ang organization o stream |
| `405` | Method na hindi `GET` / `OPTIONS` |
| `500` | Server error |

```json
{
  "success": false,
  "error": "Stream not found"
}
```

---

## Kailan “available” ang stream?

Dapat totoo ang lahat ng sumusunod:

1. Umiiral ang stream sa ilalim ng ibinigay na org slug
2. **Public** ang stream
3. Ang stream status ay **`active`**
4. Kung may start time, nagsimula na ito (sa stream timezone)
5. Kung may end time, hindi pa ito natatapos
6. May hindi bababa sa isang **published** game na naka-attach sa stream

---

## Karaniwang integration: i-gate ang overlay

Karaniwang pinapanatili ng site owners ang floating Play button o modal sa labas ng DOM hanggang live ang stream.

```html
<script>
  async function shouldShowStreamOverlay(orgSlug, streamSlug) {
    const url =
      "https://app.dailyplay.ai/api/stream-status" +
      `?org_slug=${encodeURIComponent(orgSlug)}` +
      `&stream_slug=${encodeURIComponent(streamSlug)}`;

    const res = await fetch(url);
    const json = await res.json();
    return Boolean(json?.success && json?.data?.available);
  }

  async function maybeMountOverlay() {
    const available = await shouldShowStreamOverlay(
      "your-org",
      "summer-campaign"
    );

    if (!available) {
      // Do not inject iframe / floating button
      return;
    }

    // Mount your overlay or iframe:
    // https://app.dailyplay.ai/stream/your-org/summer-campaign/widget?origin=...
  }

  maybeMountOverlay();
  // Optional: re-check every ~30s to match CDN cache
  setInterval(maybeMountOverlay, 30000);
</script>
```

### Inirerekomendang stream URLs pagkatapos ng positive check

| Layunin | URL |
| ------- | --- |
| Full stream page | `https://app.dailyplay.ai/stream/<org-slug>/<stream-slug>` |
| Widget / floating overlay | `https://app.dailyplay.ai/stream/<org-slug>/<stream-slug>/widget?origin=<encoded-site-origin>` |

Tingnan ang [Floating Play Button](/fil/sharing/floating-play-button/) para sa hosted widget snippet. Ine-gate din ng
widget script ng DailyPlay ang stream launchers para lumabas lang sila kapag maaaring laruin ang stream.

:::note[Session tokens]
Kung nangangailangan ang stream ng API session token, maaaring `true` pa rin ang availability habang kailangan ng play ang
token. Mag-mint ng tokens gamit ang [Session Tokens](/fil/api/session-tokens/) API (Business+).
:::

---

## Mga Susunod na Hakbang

- [I-embed ang games at streams](/fil/sharing/embed/)
- [Floating Play button](/fil/sharing/floating-play-button/)
- [Session Tokens](/fil/api/session-tokens/) para sa controlled access
- [API Reference](/fil/api/reference/) para sa buong endpoint list