> ## Documentation Index
> Fetch the complete documentation index at: https://docs.broadcast.events/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace festival info

> Read workspace-scoped festivals and schedules through api.broadcast.events.

## Overview

Use this endpoint to read festivals data in a workspace.

* Endpoint: `GET https://api.broadcast.events/workspace/festivals`
* Auth: `Authorization: Bearer <api-key>`

The feed returns festival projects available to the API key. Each festival includes core festival details and a `schedule` array for published schedule items.

For a history of API and documentation changes, see the [API changelog](/api-changelog).

## How to read the festival response

The response has three related concepts: **festival**, **schedule item**, and **event**.

### Festival

A `festival` is the top-level project. It describes the whole festival, such as its name, dates, region, website, ticketing link, images, and Broadcast profile.

When lineup groups are configured, `lineupGroups` lists all available group names in display order.

Each object in `data[]` is one festival:

```json theme={null}
{
    "id": "festival_123",
    "type": "festival",
    "name": "Broadcast Festival",
    "lineupGroups": ["Headliners", "Support"],
    "schedule": []
}
```

Use the festival object when you need festival-level details, branding, or links.

### Schedule item

A schedule item is one row in the festival program. It describes what appears on the festival schedule, such as the title shown in the lineup, stage name, schedule tags, media, and timing.

Schedule items live inside `festival.schedule[]`:

```json theme={null}
{
    "id": "schedule_123",
    "type": "festivalScheduleItem",
    "title": "Main stage opening",
    "stage": "Main Stage",
    "timing": {
        "day": "2026-08-14",
        "time": "18:00",
        "timezone": "Europe/Oslo"
    }
}
```

Use the schedule item when you are rendering a festival lineup, timetable, stage schedule, or artist list.

### Linked event

All schedule items are connected to a Broadcast event. That linked event appears as `schedule[].event`.

The linked event gives you event-level context, such as the related Broadcast event id, venue, event image, classification, age guidance, and price or attendance information.

```json theme={null}
{
    "id": "schedule_123",
    "type": "festivalScheduleItem",
    "title": "Main stage opening",
    "event": {
        "id": "evt_123",
        "type": "event",
        "title": "Broadcast Festival day 1"
    }
}
```

Use the linked event when you need venue details, event classification, event-level images, or a stable event id that also appears in other Broadcast event APIs.

### Relationship summary

* `data[]` contains festivals.
* Each festival has `schedule[]`.
* Each schedule item may have `event`.
* `schedule[].title`, `stage`, `timing`, and `media` describe the lineup entry.
* `schedule[].event` describes the connected Broadcast event when one exists.

## Approach

This endpoint is designed for **authenticated workspace integrations** that need a structured list of festivals and their schedule data.

The workspace route uses the API key itself as the boundary:

* The key decides which **workspace** is queried.
* The key can optionally restrict results to a subset of **allowed projects**.
* The response includes only festival projects in that workspace.

Schedule timing is included only when the festival lineup is published. If the lineup is not published, schedule items are still returned without `timing`.

## Caching

Responses may be cached on our side for about **15 seconds** to keep the feed fast and protect the data layer.

## Access and authentication

<Info>
  This API is currently available on request. Contact
  [support@broadcast.events](mailto:support@broadcast.events) to enable access
  for your workspace.
</Info>

Send your workspace API key as a bearer token:

```http Raw HTTP theme={null}
Authorization: Bearer YOUR_API_KEY
```

The key must include the `workspace.events.read` scope.

## Query parameters

| Name              | Type    | Required | Description                                                              |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------ |
| `disableUtmLinks` | Boolean | No       | UTM links are disabled by default. Set to `false` to add Broadcast UTMs. |

Notes:

* Festival website and ticketing links are returned without Broadcast UTM parameters by default.
* Pass `disableUtmLinks=false` to opt into Broadcast UTM parameters.
* Unsupported query parameters return a `400` response.

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.broadcast.events/workspace/festivals" \
    --header "Authorization: Bearer YOUR_API_KEY"
  ```

  ```http Raw HTTP theme={null}
  GET /workspace/festivals HTTP/1.1
  Host: api.broadcast.events
  Authorization: Bearer YOUR_API_KEY
  ```
</CodeGroup>

## Example response

Use the copy control on the code block to grab the full JSON.

```json title="Example response" lines wrap theme={null}
{
    "data": [
        {
            "id": "festival_123",
            "type": "festival",
            "name": "Broadcast Festival",
            "description": "A weekend of live music and talks.",
            "region": "Oslo",
            "country": "NO",
            "dates": {
                "start": "2026-08-14T00:00:00.000Z",
                "end": "2026-08-16T00:00:00.000Z",
                "startTimestamp": 1786665600,
                "endTimestamp": 1786838400
            },
            "links": {
                "website": "https://festival.example.com",
                "ticketing": "https://tickets.example.com/festival"
            },
            "media": {
                "image": {
                    "url": "https://img.broadcastapp.no/example/tr:w-375",
                    "alt": "Broadcast Festival",
                    "variants": {
                        "micro": "https://img.broadcastapp.no/example/tr:w-100",
                        "small": "https://img.broadcastapp.no/example/tr:w-178",
                        "medium": "https://img.broadcastapp.no/example/tr:w-375",
                        "large": "https://img.broadcastapp.no/example/tr:w-750"
                    }
                },
                "profileImage": {
                    "url": "https://img.broadcastapp.no/profile/tr:w-375",
                    "alt": "Broadcast Festival",
                    "variants": {
                        "micro": "https://img.broadcastapp.no/profile/tr:w-100",
                        "small": "https://img.broadcastapp.no/profile/tr:w-178",
                        "medium": "https://img.broadcastapp.no/profile/tr:w-375",
                        "large": "https://img.broadcastapp.no/profile/tr:w-750"
                    }
                }
            },
            "profile": {
                "handle": "@broadcast-festival",
                "canonicalUrl": "https://www.broadcast.events/@broadcast-festival"
            },
            "dateDisplayMode": "date_time",
            "lineupGroups": ["Headliners", "Support"],
            "schedule": [
                {
                    "id": "schedule_123",
                    "type": "festivalScheduleItem",
                    "title": "Main stage opening",
                    "description": "Opening set on the main stage.",
                    "stage": "Main Stage",
                    "tags": ["live", "electronic"],
                    "isMainSchedule": true,
                    "lineupGroup": {
                        "id": "headliners",
                        "label": "Headliners",
                        "order": 0
                    },
                    "lineupOrder": 1,
                    "timing": {
                        "day": "2026-08-14",
                        "time": "20:00",
                        "startTime": "2026-08-14T18:00:00.000Z",
                        "startTimestamp": 1786720800,
                        "timezone": "Europe/Oslo"
                    },
                    "event": {
                        "id": "evt_123",
                        "type": "event",
                        "title": "Broadcast Festival day 1",
                        "classification": {
                            "tags": ["live", "electronic"],
                            "categories": ["concert"],
                            "ageRestrictionText": "18+",
                            "isAllAges": false
                        },
                        "attendance": {
                            "isFree": false,
                            "soldOut": false,
                            "price": {
                                "text": "NOK 250"
                            }
                        },
                        "media": {
                            "image": {
                                "url": "https://img.broadcastapp.no/event/tr:w-375",
                                "alt": "Broadcast Festival day 1",
                                "variants": {
                                    "micro": "https://img.broadcastapp.no/event/tr:w-100",
                                    "small": "https://img.broadcastapp.no/event/tr:w-178",
                                    "medium": "https://img.broadcastapp.no/event/tr:w-375",
                                    "large": "https://img.broadcastapp.no/event/tr:w-750"
                                }
                            }
                        },
                        "location": {
                            "type": "venue",
                            "venue": {
                                "id": "venue_123",
                                "type": "venue",
                                "name": "Main Festival Venue",
                                "address": {
                                    "city": "Oslo",
                                    "country": "NO"
                                },
                                "links": {
                                    "self": "https://www.broadcast.events/v/venue_123",
                                    "entity": "https://www.broadcast.events/v/venue_123",
                                    "profile": "https://www.broadcast.events/@main-festival-venue"
                                },
                                "profile": {
                                    "handle": "@main-festival-venue",
                                    "canonicalUrl": "https://www.broadcast.events/@main-festival-venue"
                                }
                            }
                        }
                    },
                    "media": {
                        "youtube": "https://youtube.com/watch?v=abc123"
                    },
                    "createdAt": "2026-07-01T12:00:00.000Z",
                    "updatedAt": "2026-07-05T09:30:00.000Z"
                }
            ]
        }
    ],
    "meta": {
        "projects": [
            {
                "id": "project_festival_123",
                "name": "Broadcast Festival"
            }
        ],
        "count": 1,
        "itemCount": 1,
        "generatedAt": "2026-06-18T10:00:00.000Z"
    }
}
```

## Response fields

Empty values are omitted from the response, so some optional fields may be missing.

### At a glance

| Field  | Type   | Description                          |
| ------ | ------ | ------------------------------------ |
| `data` | Array  | List of matching workspace festivals |
| `meta` | Object | Metadata about the response          |

### Response `meta`

| Field         | Type             | Description                                               |
| ------------- | ---------------- | --------------------------------------------------------- |
| `projects`    | Array of objects | Workspace festival projects included in this response     |
| `count`       | Number           | Number of festivals returned in this response             |
| `itemCount`   | Number           | Same as `count`. Included for consistency with other APIs |
| `generatedAt` | String           | ISO timestamp for when the response payload was generated |

#### `meta.projects[]`

| Field  | Type   | Description                   |
| ------ | ------ | ----------------------------- |
| `id`   | String | Workspace festival project id |
| `name` | String | Current festival project name |

### Festival object

| Field             | Type             | Description                                                           |
| ----------------- | ---------------- | --------------------------------------------------------------------- |
| `id`              | String           | Broadcast festival id                                                 |
| `type`            | String           | Always `festival`                                                     |
| `name`            | String           | Festival name                                                         |
| `description`     | String           | Festival description when available                                   |
| `region`          | String           | Festival region                                                       |
| `country`         | String           | Festival country                                                      |
| `dates`           | Object           | Festival start and end dates                                          |
| `links`           | Object           | Festival links                                                        |
| `media`           | Object           | Festival image assets                                                 |
| `profile`         | Object           | Linked Broadcast profile metadata                                     |
| `dateDisplayMode` | String           | Date display mode: `date_time`, `date_tbc`, `tbc_tbc`, or `time_only` |
| `lineupGroups`    | Array of strings | Available lineup group names in display order                         |
| `schedule`        | Array            | Published schedule items for the festival                             |

#### Date display modes

`dateDisplayMode` controls which schedule timing values are exposed. Hidden values are omitted instead of being returned as raw ISO or Unix fields.

| Mode        | Meaning                  | Schedule `timing` behavior                                                                                                                  |
| ----------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `date_time` | Date and time confirmed  | Returns `day`, `time`, `startTime`, `startTimestamp`, and `timezone`. Also returns `endTime` and `endTimestamp` when end times are enabled. |
| `date_tbc`  | Date confirmed, time TBC | Returns `day`, `time: "TBC"`, and `timezone`. Hidden clock fields are omitted.                                                              |
| `tbc_tbc`   | Date and time TBC        | Returns `day: "TBC"`, `time: "TBC"`, and `timezone`. Hidden date/time fields are omitted.                                                   |
| `time_only` | Time-focused display     | Returns the same machine-readable fields as `date_time`, while clients may choose to display only the time.                                 |

#### `dates`

| Field            | Type   | Description                           |
| ---------------- | ------ | ------------------------------------- |
| `start`          | String | Festival start datetime in ISO format |
| `end`            | String | Festival end datetime in ISO format   |
| `startTimestamp` | Number | Festival start timestamp in seconds   |
| `endTimestamp`   | Number | Festival end timestamp in seconds     |

#### `links`

| Field       | Type   | Description          |
| ----------- | ------ | -------------------- |
| `website`   | String | Festival website URL |
| `ticketing` | String | Festival ticket URL  |

#### `media`

| Field           | Type   | Description                         |
| --------------- | ------ | ----------------------------------- |
| `image`         | Object | Primary festival image asset        |
| `profileImage`  | Object | Festival profile image asset        |
| `appScreenshot` | Object | Festival app screenshot image asset |

Image assets use the same `url`, `alt`, and `variants` shape as event images. See [workspace event media fields](/workspace-events-api#image-asset).

#### `profile`

| Field          | Type   | Description                             |
| -------------- | ------ | --------------------------------------- |
| `handle`       | String | Broadcast profile handle, including `@` |
| `canonicalUrl` | String | Canonical Broadcast profile URL         |

### Schedule item object

| Field            | Type    | Description                                                                              |
| ---------------- | ------- | ---------------------------------------------------------------------------------------- |
| `id`             | String  | Broadcast festival schedule item id                                                      |
| `type`           | String  | Always `festivalScheduleItem`                                                            |
| `title`          | String  | Schedule item title                                                                      |
| `description`    | String  | Schedule item description when available                                                 |
| `stage`          | String  | Stage or external venue name                                                             |
| `tags`           | Array   | Normalized schedule item tags                                                            |
| `isMainSchedule` | Boolean | true when the item belongs to the main schedule                                          |
| `lineupGroup`    | Object  | Manual lineup group for festival lineup displays                                         |
| `lineupOrder`    | Number  | Manual order within `lineupGroup`                                                        |
| `timing`         | Object  | Schedule timing values allowed by `dateDisplayMode`. Included only for published lineups |
| `event`          | Object  | Linked Broadcast event when available                                                    |
| `media`          | Object  | Schedule item media                                                                      |
| `socialLinks`    | Array   | Social links from the schedule item                                                      |
| `createdAt`      | String  | Schedule item created timestamp in ISO format                                            |
| `updatedAt`      | String  | Schedule item updated timestamp in ISO format                                            |

#### Schedule `lineupGroup`

`lineupGroup` is optional. It appears when a festival has manually grouped a schedule item for a lineup-style display, such as headliners and support acts.

Use festival-level `lineupGroups` when you need the complete list of available group names. Use `lineupGroup.order` to order groups for assigned schedule items. Use `lineupOrder` to order items inside the same group.

| Field   | Type   | Description                        |
| ------- | ------ | ---------------------------------- |
| `id`    | String | Stable lineup group id             |
| `label` | String | Display label for the lineup group |
| `order` | Number | Manual order for the lineup group  |

#### Schedule `timing`

The `timing` object only includes values allowed by the festival's `dateDisplayMode` and app settings. For `date_time` and `time_only`, machine-readable ISO and Unix start values are included. End values are included only when end times are enabled. For restricted modes such as `date_tbc` and `tbc_tbc`, hidden clock/date fields are omitted.

| Field            | Type   | Description                                                           |
| ---------------- | ------ | --------------------------------------------------------------------- |
| `day`            | String | Schedule day as `YYYY-MM-DD`, or `TBC` when hidden                    |
| `time`           | String | Schedule start time as `HH:mm`, or `TBC` when hidden                  |
| `startTime`      | String | Start time in ISO format, included for unrestricted time modes        |
| `endTime`        | String | End time in ISO format, only when end times are enabled and allowed   |
| `startTimestamp` | Number | Start timestamp in seconds, included for unrestricted time modes      |
| `endTimestamp`   | Number | End timestamp in seconds, only when end times are enabled and allowed |
| `timezone`       | String | Time zone. Currently `Europe/Oslo`                                    |

Examples:

```json title="date_time" theme={null}
{
    "day": "2026-08-14",
    "time": "20:00",
    "startTime": "2026-08-14T18:00:00.000Z",
    "startTimestamp": 1786720800,
    "timezone": "Europe/Oslo"
}
```

```json title="date_tbc" theme={null}
{
    "day": "2026-08-14",
    "time": "TBC",
    "timezone": "Europe/Oslo"
}
```

```json title="tbc_tbc" theme={null}
{
    "day": "TBC",
    "time": "TBC",
    "timezone": "Europe/Oslo"
}
```

#### `event`

| Field            | Type   | Description                                 |
| ---------------- | ------ | ------------------------------------------- |
| `id`             | String | Linked Broadcast event id                   |
| `type`           | String | Always `event`                              |
| `title`          | String | Linked event title when available           |
| `classification` | Object | Linked event tags, categories, and age info |
| `attendance`     | Object | Linked event free, sold out, and price info |
| `media`          | Object | Linked event media assets                   |
| `location`       | Object | Linked event location when available        |

`event` is a subset of the event object used by the public and workspace event endpoints. When venue data is available, `event.location.venue` uses the same venue shape as event `location.venue`. See [workspace event venue fields](/workspace-events-api#locationvenue).

#### Event `classification`

| Field                | Type             | Description                            |
| -------------------- | ---------------- | -------------------------------------- |
| `tags`               | Array of strings | Normalized linked event tags           |
| `categories`         | Array of strings | Linked event categories                |
| `ageRestrictionText` | String           | Age restriction label such as `18+`    |
| `isAllAges`          | Boolean          | true when the linked event is all ages |

#### Event `attendance`

| Field     | Type    | Description                            |
| --------- | ------- | -------------------------------------- |
| `isFree`  | Boolean | true when the linked event is free     |
| `soldOut` | Boolean | true when the linked event is sold out |
| `price`   | Object  | Linked event price details             |

#### Event `attendance.price`

| Field  | Type   | Description                                  |
| ------ | ------ | -------------------------------------------- |
| `text` | String | Human-readable price label such as `NOK 250` |

#### Event `media`

| Field   | Type   | Description              |
| ------- | ------ | ------------------------ |
| `image` | Object | Linked event image asset |

Linked event image assets use the same `url`, `alt`, and `variants` shape as event images. See [workspace event image fields](/workspace-events-api#image-asset).

#### Schedule `media`

| Field     | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| `image`   | Object | Schedule item image asset         |
| `youtube` | String | Schedule item YouTube URL or link |

## Error responses

| Status | Meaning                                     |
| ------ | ------------------------------------------- |
| `400`  | Unsupported query parameter                 |
| `401`  | Missing, invalid, or expired API key        |
| `403`  | API key does not include the required scope |
| `429`  | Too many requests                           |
| `500`  | Internal server error                       |

## Notes

* This endpoint returns only festival projects in the workspace.
* Allowed project restrictions on the API key are applied before festivals are returned.
* Schedule timing is omitted until the festival lineup is published.
* `lineupGroups` lists all configured lineup group names for the festival in display order.
* `lineupGroup` and `lineupOrder` are manual lineup display metadata. They do not change schedule timing or stage values.
* Empty optional fields are omitted from both festival and schedule objects.