# Calendar API

Base path: `/api/v1/calendar`

All endpoints require `Authorization: Bearer <jwt>`.

Related: [[02 - Videos API]], [[04 - Database Schema]]

---

## GET /calendar

Get calendar entries for the current team. Returns scheduled and published videos within the requested date range.

**Query parameters:**

| Param | Values | Description |
|---|---|---|
| `view` | `month\|week\|agenda` | Calendar view mode |
| `date` | `YYYY-MM` | Reference month or date |

**Date ranges by view mode:**

| View | Range returned |
|---|---|
| `month` | Full calendar month for the given `YYYY-MM` |
| `week` | The week containing day 1 of the given month. Because `date` is `YYYY-MM` with no day component, the week always anchors to the 1st — arbitrary week navigation is not supported. **Not used by the frontend.** |
| `agenda` | Next 30 days from the given date |

**Response:**

```json
[
  {
    "videoId": "cuid",
    "title": "Video Title",
    "date": "ISO datetime",
    "templateName": "Template Name",
    "collaborators": [
      {
        "id": "cuid",
        "name": "Collaborator Name",
        "youtubeLink": "https://www.youtube.com/@handle"
      }
    ],
    "lintStatus": "OK",
    "channelId": "cuid",
    "privacyStatus": "PRIVATE"
  }
]
```

**Response field notes:**

| Field | Notes |
|---|---|
| `date` | The video's `scheduledAt` or `publishedAt` datetime used to place it on the calendar. |
| `templateName` | Name of the template applied to this video, if any. |
| `collaborators` | Collaborators assigned via `Video.collaboratorIds`, resolved to name and YouTube link. |
| `lintStatus` | Current lint status: `OK`, `WARNING`, or `ERROR`. |
| `privacyStatus` | `PUBLIC`, `PRIVATE`, or `UNLISTED`. |