> **Design proposal** — REST API not yet implemented. Admin functions are
> currently handled by PHP pages under `admin/` and shell scripts.

# Admin API Specification
## Videos, Packages, Schedules, and Channel Diagnostics

## 1. Purpose

This API provides administrative control over:

- video records
- encoded media metadata
- content packages
- daily schedules
- channel diagnostics

Base path example:

```text
/api
```

## 2. Authentication

All admin endpoints should require authenticated access.

Recommended options:

- Azure AD integration
- app-level auth with roles
- editor/admin permission model

Public playback endpoints should remain separate from admin endpoints.

## 3. Video Endpoints

### Create Video Record

```text
POST /api/videos
```

Request:

```json
{
  "videoId": "sermon-2026-03-01",
  "title": "The Grace of God",
  "sourcePath": "/source/sermon-2026-03-01.mp4",
  "durationSec": 3120,
  "thumbnail": "/images/sermon-2026-03-01.jpg",
  "tags": ["sermon", "sunday"]
}
```

Response:

```json
{
  "ok": true,
  "videoId": "sermon-2026-03-01"
}
```

### Get One Video

```text
GET /api/videos/{videoId}
```

### List Videos

```text
GET /api/videos
```

Optional query parameters:

- `q`
- `limit`
- `offset`
- `tag`
- `status`

### Update Video

```text
PUT /api/videos/{videoId}
```

### Delete Video

```text
DELETE /api/videos/{videoId}
```

## 4. Package Endpoints

### Create Package

```text
POST /api/packages
```

Request:

```json
{
  "packageId": "PKG-SUNDAY-CURRENT",
  "label": "Current Sunday Package",
  "durationHours": 4,
  "items": [
    { "videoId": "worship-021", "order": 1 },
    { "videoId": "sermon-2026-03-01", "order": 2 },
    { "videoId": "teaching-018", "order": 3 }
  ]
}
```

### Get One Package

```text
GET /api/packages/{packageId}
```

### List Packages

```text
GET /api/packages
```

### Update Package

```text
PUT /api/packages/{packageId}
```

### Delete Package

```text
DELETE /api/packages/{packageId}
```

## 5. Schedule Endpoints

### Create Daily Schedule

```text
POST /api/schedules
```

Request:

```json
{
  "date": "2026-03-08",
  "blocks": [
    { "start": "00:00", "packageId": "PKG-NIGHT-01" },
    { "start": "04:00", "packageId": "PKG-MORNING-01" },
    { "start": "08:00", "packageId": "PKG-SUNDAY-CURRENT" },
    { "start": "12:00", "packageId": "PKG-SUNDAY-CURRENT" },
    { "start": "16:00", "packageId": "PKG-EVENING-01" },
    { "start": "20:00", "packageId": "PKG-SUNDAY-LAST" }
  ]
}
```

### Get Schedule by Date

```text
GET /api/schedules/{date}
```

### Update Schedule by Date

```text
PUT /api/schedules/{date}
```

### Delete Schedule by Date

```text
DELETE /api/schedules/{date}
```

## 6. Channel Diagnostics Endpoints

### Current Channel State

```text
GET /api/channel/now
```

Response:

```json
{
  "timestamp": "2026-03-08T09:17:25",
  "blockStart": "08:00",
  "packageId": "PKG-SUNDAY-CURRENT",
  "resolvedPackageId": "PKG-SUNDAY-CURRENT-2026-03-08",
  "videoId": "teaching-018",
  "segmentIndex": 54
}
```

### Debug Channel at Arbitrary Time

```text
GET /api/channel/debug?time=2026-03-08T09:17:25
```

This endpoint is highly valuable during development and troubleshooting.

## 7. Suggested JSON Shapes

### Video

```json
{
  "videoId": "string",
  "title": "string",
  "durationSec": 0,
  "sourcePath": "string",
  "hlsPath": "string",
  "thumbnail": "string",
  "tags": ["string"],
  "status": "ready"
}
```

### Package

```json
{
  "packageId": "string",
  "label": "string",
  "durationHours": 4,
  "items": [
    { "videoId": "string", "order": 1 }
  ]
}
```

### Schedule

```json
{
  "date": "YYYY-MM-DD",
  "blocks": [
    { "start": "HH:mm", "packageId": "string" }
  ]
}
```

## 8. Suggested Validation Rules

### Video Validation

- `videoId` must be unique
- `durationSec` must be positive
- `sourcePath` must exist
- tags should be optional

### Package Validation

- `packageId` must be unique
- all referenced videos must exist
- `order` must be unique within package
- durationHours should normally equal 4 for this channel model

### Schedule Validation

- exactly six blocks per day
- allowed block starts:
  - `00:00`
  - `04:00`
  - `08:00`
  - `12:00`
  - `16:00`
  - `20:00`
- referenced package IDs must exist

## 9. Error Response Pattern

Recommended standard error shape:

```json
{
  "ok": false,
  "error": {
    "code": "PACKAGE_NOT_FOUND",
    "message": "Package PKG-MORNING-01 was not found"
  }
}
```

## 10. Auditability

Recommended audit log fields:

- actor
- action
- entity type
- entity id
- timestamp
- before / after values if practical

Especially important for:

- schedule changes
- package edits
- video deletion

## 11. Recommended Internal Service Split

You may choose to separate services like this:

- media service: videos and encoding metadata
- programming service: packages and schedules
- playback service: channel diagnostics and playlist generation

For a small system, one app is fine. For growth, these boundaries are useful.

## 12. Summary

This API defines the control plane for the Roku channel.

It manages the objects that drive playback:

- videos
- packages
- schedules
- diagnostic state

The playback URL remains separate and is resolved from these backend resources.