# Club Calendar API Documentation

This API allows third-party applications to retrieve a club's event calendar in JSON format.

## Authentication
This is a public API. Access is controlled via a unique **Public Token** assigned to each club.
No HTTP headers or OAuth flows are required.

## Endpoint

### Get Club Calendar

`GET /api/calendar/{token}`

Retrieves a list of events for the specified club.

#### Parameters

| Parameter | Type | Position | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| `token` | string | Path | Yes | The unique public token for the club. |
| `year` | integer | Query | No | Filter events by year. Defaults to the current year. |

#### Request Example

```http
GET https://clubsapp.brightfive.com/api/calendar/abc123xyz789?year=2026
```

#### Response Example

```json
{
  "club": {
    "name": "Karate Club A",
    "logo_url": "https://clubs.example.com/storage/logos/logo.png"
  },
  "events": [
    {
      "id": 101,
      "title": "Grading",
      "start": "2026-03-15T10:00:00+00:00",
      "end": "2026-03-15T11:00:00+00:00",
      "location": "Main Hall",
      "type": "Grading",
      "description": "Quarterly grading for all belts.",
      "color": "purple"
    },
    {
      "id": 102,
      "title": "Weekly Training",
      "start": "2026-03-16T18:00:00+00:00",
      "end": "2026-03-16T19:00:00+00:00",
      "location": "Dojo B",
      "type": "Course",
      "description": "",
      "color": "blue"
    }
  ]
}
```

#### Event Colors
Events include a `color` property that maps to potential UI styling:
- `blue`: Course
- `purple`: Grading
- `red`: Competition
- `amber`: Visiting Instructor
- `green`: Social
- `gray`: Other