Workspace festival info - Broadcast Docs

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.

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:

{
    "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[]:

{
    "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.

{
    "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

This API is currently available on request. Contact support@broadcast.events to enable access for your workspace.

Send your workspace API key as a bearer token:

Raw HTTP

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

curl --request GET \
  --url "https://api.broadcast.events/workspace/festivals" \
  --header "Authorization: Bearer YOUR_API_KEY"

GET /workspace/festivals HTTP/1.1
Host: api.broadcast.events
Authorization: Bearer YOUR_API_KEY

Example response

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

Example response

{
    "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.

`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:

date_time

{
    "day": "2026-08-14",
    "time": "20:00",
    "startTime": "2026-08-14T18:00:00.000Z",
    "startTimestamp": 1786720800,
    "timezone": "Europe/Oslo"
}

date_tbc

{
    "day": "2026-08-14",
    "time": "TBC",
    "timezone": "Europe/Oslo"
}

tbc_tbc

{
    "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.

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.

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.

​Overview

​How to read the festival response

​Festival

​Schedule item

​Linked event

​Relationship summary

​Approach

​Caching

​Access and authentication

​Query parameters

​Example request

​Example response

​Response fields

​At a glance

​Response meta

​meta.projects[]

​Festival object

​Date display modes

​dates

​links

​media

​profile

​Schedule item object

​Schedule lineupGroup

​Schedule timing

​event

​Event classification

​Event attendance

​Event attendance.price

​Event media

​Schedule media

​Error responses

​Notes

Overview

How to read the festival response

Festival

Schedule item

Linked event

Relationship summary

Approach

Caching

Access and authentication

Query parameters

Example request

Example response

Response fields

At a glance

Response `meta`

`meta.projects[]`

Festival object

Date display modes

`dates`

`links`

`media`

`profile`

Schedule item object

Schedule `lineupGroup`

Schedule `timing`

`event`

Event `classification`

Event `attendance`

Event `attendance.price`

Event `media`

Schedule `media`

Error responses

Notes