> ## 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.

# Festival schedule feed

> A recommended JSON format for sending festival schedule and venue data to Broadcast.

We can work with schedule data in a range of formats. If you are setting up a new feed, the structure below is the easiest for us to process and keep updated.

The main thing we need is one record for each booked programme item, together with stable IDs, set times, and venue details.

<Info>
  Already have a feed in another format? Get in touch at
  [support@broadcast.events](mailto:support@broadcast.events). We can often map
  an existing feed without asking you to rebuild it.
</Info>

## Feed options

The preferred option is a stable HTTPS endpoint that returns a UTF-8 JSON response. This allows us to keep the schedule in sync automatically.

A one-time JSON file is also fine while we set up and test the import. If your endpoint needs authentication, let us know and we can agree on the best approach.

We recommend returning the complete current schedule on every request. This makes it easier to handle updates, cancellations, and removed items safely.

## Example format

```json title="festival-schedule.json" lines wrap theme={null}
{
  "schemaVersion": "1.0",
  "festival": {
    "id": "festival-2026",
    "timezone": "Europe/Stockholm"
  },
  "generatedAt": "2026-08-20T10:00:00Z",
  "events": [
    {
      "id": "source-event-id",
      "title": "Artist or programme title",
      "artistId": "source-artist-id",
      "startAt": "2026-09-02T18:00:00Z",
      "endAt": "2026-09-02T18:30:00Z",
      "status": "published",
      "venueId": "source-venue-id",
      "venueName": "Main Stage",
      "broadcastVenueId": "optional-id-provided-by-broadcast",
      "description": "Public programme description.",
      "imageUrl": "https://festival.example/images/artist.jpg",
      "tags": ["Indie", "Rock"],
      "socialLinks": [
        {
          "type": "instagram",
          "url": "https://instagram.com/example"
        }
      ],
      "updatedAt": "2026-08-20T09:45:00Z"
    }
  ],
  "venues": [
    {
      "id": "source-venue-id",
      "name": "Main Stage",
      "broadcastVenueId": "optional-id-provided-by-broadcast",
      "address": {
        "line1": "Example Street 1",
        "postalCode": "701 10",
        "city": "Example City",
        "countryCode": "SE"
      },
      "location": {
        "latitude": 59.2741,
        "longitude": 15.2066
      }
    }
  ]
}
```

## Festival details

* `schemaVersion`: The version of your feed structure. Start with `1.0`.
* `festival.id`: Your stable ID for this edition of the festival.
* `festival.timezone`: The festival's IANA timezone, for example `Europe/Stockholm`.
* `generatedAt`: The time the response was generated, in full ISO 8601 UTC format.

## Event details

Each item in `events` represents one performance or programme slot.

The following fields provide everything we need for a basic schedule item:

* `id`: Your stable ID for this particular performance.
* `title`: The artist, act, or programme title as it should appear publicly.
* `startAt`: The scheduled start time in full ISO 8601 format.
* `endAt`: The scheduled end time in full ISO 8601 format.
* `status`: `draft`, `published`, or `cancelled`.
* `venueId`: Your stable ID for the venue or stage.
* `venueName`: The public name of the venue or stage.

You can also include:

* `artistId`: Your stable artist ID.
* `broadcastVenueId`: A venue ID supplied by Broadcast.
* `description`: Public programme copy in plain text or Markdown.
* `imageUrl`: A public HTTPS URL for the schedule image.
* `tags`: An array of public genres or programme labels.
* `socialLinks`: An array of public artist links.
* `updatedAt`: The time this item was last changed.

Supported social link types include `spotify`, `instagram`, `facebook`, `tidal`, `bandcamp`, `soundcloud`, `tiktok`, `youtube`, `twitter`, `vimeo`, `twitch`, `applemusic`, `qobuz`, and `deezer`.

If a programme item features several artists, send it as one event and use the combined public title in `title`.

<Warning>
  Published schedule items need an image in Broadcast. You can provide an
  `imageUrl` for each item, or we can agree on a default festival image.
</Warning>

## Venue details

The `venues` section is optional if the event records already contain everything we need. It is useful when you want to include addresses and coordinates.

Each venue can include:

* `id`: Your stable venue ID. This should match `events[].venueId`.
* `name`: The public venue or stage name.
* `broadcastVenueId`: An ID supplied by Broadcast, when available.
* `address.line1`: The street address.
* `address.postalCode`: The postal code.
* `address.city`: The postal area or city.
* `address.countryCode`: The two-letter ISO country code.
* `location.latitude`: Latitude in WGS 84 decimal degrees.
* `location.longitude`: Longitude in WGS 84 decimal degrees.

Your own `venueId` remains the main source ID. If we provide a `broadcastVenueId`, include it as a separate value and return it unchanged.

## Dates and times

All timestamps should use full ISO 8601 format in UTC with a `Z` suffix:

```json theme={null}
{
  "startAt": "2026-09-02T18:00:00Z",
  "endAt": "2026-09-02T18:30:00Z"
}
```

Please make sure that:

* `endAt` is later than `startAt`.
* Every timestamp includes a timezone.
* The festival timezone uses an IANA name such as `Europe/Stockholm`.
* You provide the real end time where possible.

## Updates and cancellations

Use `published` for programme items that are ready to display and `draft` for items that should remain hidden.

Keep cancelled items in the feed with `status: "cancelled"`. This lets us process the cancellation instead of treating it as a temporary feed problem.

If an event disappears from a later full feed, we may treat it as removed and unpublish it.

## IDs and matching

Stable IDs make updates much more reliable:

* Use an event ID for a performance, not for an artist.
* Give two performances by the same artist different event IDs.
* Keep artist, event, and venue IDs separate.
* Match artists and venues by ID rather than by display name.
* Keep the same event ID when a time, title, description, or venue changes.
* Send numeric and UUID-like IDs as JSON strings.

## Personal data

The schedule feed should only contain information that is approved for public display. A small, purpose-built export is safer and easier to work with than a complete database dump.

Please leave out:

* Email addresses, phone numbers, and private contact names
* Applicant records that are not part of the schedule
* GDPR, check-in, application status, and availability data
* Internal comments and administrative metadata
* Technical riders, backline requirements, and private files
* Database authors, audit records, and authentication identifiers

Descriptions, images, and social links should all be approved for public use.

## Before sending the feed

It is helpful to check that:

* Every event has a unique and stable ID.
* Every end time is later than its start time.
* Every `venueId` matches one venue.
* Every `artistId`, when included, matches one artist.
* Relationships use IDs rather than names.
* Images and links use public HTTPS URLs.
* Coordinates use the correct latitude and longitude order.
* The feed only includes booked programme items.
* The feed does not contain personal contact or operational information.

If this format does not fit your system, contact [support@broadcast.events](mailto:support@broadcast.events). We are happy to discuss a format that works for both sides.