---
name: ballbuddy-balltermin
description: Einen konkreten Maturaball bei Ballbuddy nachschlagen – Detail per Slug (Beschreibung, Location mit Adresse, Links, Tanzschule/Disco/Band, Ticketkategorien), die Ball-Seite für Menschen und der ICS-Kalendereintrag. Use when a user asks about one specific Austrian Maturaball (details, address, tickets, add to calendar).
license: Daten © Ballbuddy/Framed – Nutzung in Agent-Antworten mit Quellenangabe (Link auf die Ball-Seite) erwünscht
---

# Ballbuddy-Balltermin: ein konkreter Ball

Jeder Ball hat einen Slug (z. B. `htl-weiz-2027`). Du findest ihn über den Skill
`ballbuddy-ballkalender` (`GET https://ballbuddy.at/api/public/v1/balls?q=…`) oder aus der Adresse
einer Ball-Seite `https://ballbuddy.at/ball/<slug>`. Die API ist öffentlich, nur lesend, ohne
Schlüssel; Beschreibung: https://ballbuddy.at/openapi.json, Doku: https://ballbuddy.at/docs/agents.

## Detail per Slug

```
GET https://ballbuddy.at/api/public/v1/balls/{slug}
```

```
curl -s "https://ballbuddy.at/api/public/v1/balls/htl-weiz-2027"
```

Die Antwort enthält alles aus der Liste (`title`, `starts_at`, `ends_at`, `doors_at`, `season`,
`status`, `city`, `state`, `school`, `venue { name, slug, address, zip, city }`, `venue_text`,
`instagram`, `tickets`, `cover`, `has_motto`, `time_known`, `schools`, `url`) und zusätzlich:

- `description` – Text des Komitees („Über den Ball“), sonst `null`.
- `links` – `[{ type, label?, url }]` mit `type` `instagram` | `youtube` | `tiktok` | `website` | `other`.
- `tanzschule`, `disco`, `band` – je Text oder `null`.
- `ticket_types` – `[{ id, name, price_presale_cents, price_door_cents, sort }]`, nur öffentliche
  Kategorien; Preise in Cent (`price_presale_cents` Vorverkauf, `price_door_cents` Abendkassa,
  `null` = nicht angegeben).

`404 { "error": "not_found" }` bei unbekanntem oder nicht veröffentlichtem Slug.

## Alte Adressen

Slugs sind stabil. Wurde ein Ball dennoch umbenannt, antwortet die alte Adresse mit `301` und
`Location` auf die aktuelle (`curl -L` folgt) – auch die Ball-Seite leitet permanent weiter. Der
ICS-Endpunkt kennt nur den aktuellen Slug: nimm `slug` aus dem Detail.

## Ball-Seite für Menschen

`https://ballbuddy.at/ball/<slug>` – das ist `url` im Detail. Dort stehen alle Angaben, Tickets,
Kalender-Buttons und die Erinnerung. Verlinke sie in Antworten als Quelle.

## Kalendereintrag (ICS)

```
GET https://ballbuddy.at/api/ics/{slug}
```

```
curl -s -o htl-weiz-2027.ics "https://ballbuddy.at/api/ics/htl-weiz-2027"
```

Antwort `text/calendar`: ein VEVENT mit zwei Erinnerungen (7 Tage und 1 Tag vorher), eine Stunde
cachebar, `404` bei unbekanntem Slug. Bei `has_motto: false` heißt der Eintrag „Maturaball <Schule>“,
bei `time_known: false` ist er ganztägig.

## Anzeige-Regeln

- `has_motto: false` – `title` ist generisch, kein Motto: Schule nennen (`schools[0].name`, bei
  mehreren „A × B“) und „Motto folgt“ sagen.
- `time_known: false` – Uhrzeit unbekannt: nur das Datum von `starts_at` in Europe/Vienna,
  keine Uhrzeit, `ends_at` und `doors_at` ignorieren.
- Zeiten sind ISO-8601 in UTC – für die Anzeige nach Europe/Vienna umrechnen.
- `status` `cancelled` oder `postponed`: nicht als fixen Termin ausgeben.
- `tickets.mode` `link` – Tickets unter `tickets.url`; `instagram` oder `info` – auf die Ball-Seite
  verweisen, dort steht der Hinweis des Komitees.

## Über MCP

Dieselbe Aufgabe, bequemerer Weg: Ballbuddy spricht auch MCP (Model Context Protocol) unter
`https://ballbuddy.at/api/mcp` (Streamable HTTP, kein Token). `get_ball` liefert für einen Slug dieselbe
Detailform wie `GET /api/public/v1/balls/{slug}` und nennt bei einem alten Slug den aktuellen, statt
umzuleiten; `get_ball_calendar` liefert die Adresse der `.ics`-Datei und den Kalendertext gleich mit.
Den Slug findest du über `search_balls`. Konfiguration:
`{"mcpServers": {"ballbuddy": {"url": "https://ballbuddy.at/api/mcp"}}}`; Server-Card:
https://ballbuddy.at/.well-known/mcp/server-card.json. Die Anzeige-Regeln oben gelten dort genauso.

## Was diese API nicht kann

- Nichts schreiben: keine Änderungen am Ball, keine Erinnerungen anlegen, keine Anfragen ans Komitee.
- Keine Ticketkäufe und keine Reservierungen – `ticket_types` und `tickets` sind Information.
- Keine personenbezogenen Daten: keine Komitee-Mitglieder, keine Kontaktdaten von Personen.
- Keine internen Prüf- oder Importfelder (Quelle, Referenzen, Prüf-Flags).
- Keine unveröffentlichten Bälle – sie antworten mit `404`.