Content API Requirements

Content API / Event Data – Request for Technical Details

We'd like to integrate your event and content data into our app. To minimize the effort needed on your side, our preferred approach is to consume a structured data source you may already have.

This document serves two purposes:

1. If you have an existing API/feed → just send us access details (Section 1)

2. If you need to build a feed → use Section 2 as a reference for the data we need

We're also happy to schedule a brief technical alignment call to discuss your specific setup.

1. Do you already have a data source? (Preferred approach)

Our preferred workflow is to consume whatever structured data source you already have. This typically requires no work on your side. Please let us know if any of the following already exist that we can access:

• Public or authenticated HTTP API (REST/JSON, GraphQL, etc.)

• XML / JSON feed (e.g. URL exporting all events)

For any existing source, please send:

• Endpoint/URL

• Authentication method (key, basic auth, IP allowlist, etc.)

• Security: Please confirm whether authentication credentials can be rotated/regenerated if needed

• Format (JSON/XML/other)

• Brief field description or example payload

→ If you have ANY existing source, skip to Section 4. We'll handle the rest.

If you already have any of these options readily available, you usually don't need to change anything – we will adapt to your structure.

2. We don't have a data source. What do we do next?

For development teams: If you're building a new integration from scratch, we have complete OpenAPI/Swagger documentation with detailed schemas for all supported fields. If you need to create an export or endpoint, the kind of data we need for each event is as follows.

Core event fields

• Unique ID (from CMS) AND Event ID (from ticketing system) – we need to know how these two connect

• Title

• Subtitle (if applicable)

• Short description (for listing)

• Full description / body text

• Language code (e.g. de, en)

• Available translations (if content exists in multiple languages)

• Default/fallback language

• Event type / category (e.g. opera, concert, musical)

• Venue name

• Venue ID (if available)

• Hall/room name (if applicable)

• Publication status (draft/published/archived)

• Last updated timestamp

Performance / date-time information

For each performance / showtime:

• Performance ID

• Event ID (reference)

• Performance date and time (ideally ISO 8601 format with timezone, e.g. 2026-05-10T19:30:00+02:00)

• Duration (if available)

Ticketing / pricing metadata

We do not need full price tables here (those usually come from the ticketing system), but we need:

• Basic pricing hints (e.g. "from €X", "dynamic pricing yes/no") if you have them as content

• Any special flags (e.g. premiere, gala, family performance, etc.)

Content & media

• Main image URL (poster/hero)

• Additional image URLs (if available)

• Image type (poster, production photo, etc.) if you distinguish them

• Attributions / copyright text (for each image)

• Trailer / video URL (if applicable)

• Music clip URL (if applicable)

Cast & production info (if available)

• Cast list (name + role)

• Creative team (e.g. director, conductor, choreographer)

• Presenter / promoter (if relevant)

• Season / production year

Miscellaneous / custom fields

Please also include any additional fields you consider important (e.g. genre tags, age recommendation, runtime, subtitles, language of performance, internal codes). We can usually map these on our side.

3. Example JSON structure (illustrative)

You do not have to follow this exact format. It's just an example to show the level of detail that works well for us:

{
  "events": [
    {
      "id": "EVT-12345",
      "title": "La Traviata",
      "subtitle": "Giuseppe Verdi",
      "shortDescription": "Classic opera in three acts.",
      "description": "<p>Full HTML description...</p>",
      "language": "de",
      "availableLanguages": ["de", "en"],
      "category": "opera",
      "publicationStatus": "published",
      "lastUpdated": "2026-02-15T14:30:00+01:00",
      "venue": {
        "id": "VEN-01",
        "name": "Schmidts Tivoli",
        "hall": "Gro\u00dfer Saal"
      },
      "season": "2025/26",
      "ageRecommendation": "12+",
      "runtimeMinutes": 160,
      "performances": [
        {
          "id": "PERF-98765",
          "dateTime": "2026-05-10T19:30:00+02:00",
          "status": "on_sale",
          "onSaleFrom": "2026-03-01T10:00:00+01:00",
          "flags": ["premiere", "dolby"]
        }
      ],
      "media": {
        "mainImage": {
          "url": "https://example.com/images/traviata-main.jpg",
          "copyright": "\u00a9 Photographer / House"
        },
        "gallery": [
          {
            "url": "https://example.com/images/traviata-1.jpg",
            "type": "stage"
          }
        ],
        "trailerUrl": "https://youtube.com/..."
      },
      "links": {
        "eventUrl": "https://example.com/events/la-traviata",
        "bookingUrl": "https://example.com/events/la-traviata/tickets"
      },
      "tags": ["verdi", "opera", "romantic"]
    }
  ]
}

If you prefer XML or another structure, that is fine – we will adapt to it.

4. Technical constraints & cadence

Please tell us:

• Maximum page size / rate limits

• How often data is updated (real-time, hourly, nightly, etc.)

5. Error Handling & Support

• Technical contact for API issues

• Expected response format for errors (if API)

• Maintenance windows or known downtime periods

6. Next steps

• If you already have an existing feed/API: Please share the access details and one or two sample responses.

• If you need to set something up: We're happy to briefly align on what's easiest in your CMS to make the build as straightforward as possible.

• Do you have a staging/test environment we can use for integration testing?