Entwickler

Termine-API für eure Webseite

Bindet die öffentlichen Termine eures Ensembles in eure eigene Webseite ein — per einfachem HTTP-Request, ohne Account, ohne API-Key.

Das Wichtigste zuerst

•Öffentlich zugänglich, keine Authentifizierung nötig.
•CORS ist aktiviert, der Endpunkt funktioniert direkt aus dem Browser.
•Antworten werden 5 Minuten zwischengespeichert, Rate-Limit 60 Anfragen pro Minute.
•Es werden nur Daten ausgeliefert, die ihr in den Website-Einstellungen zur öffentlichen Anzeige freigegeben habt.
•Bei öffentlicher Nutzung ist ein 'Powered by Chorilo'-Hinweis mit Link auf unsere Webseite Pflicht.

Powered by Chorilo — Hinweis auf eurer Seite

Wenn ihr die API auf einer öffentlichen Seite einsetzt, fügt bitte sichtbar einen 'Powered by Chorilo'-Hinweis mit Link auf https://www.chorilo.com hinzu. Eine dezente Zeile im Footer reicht völlig.

Der Austausch ist fair: Ihr bindet eure Termine automatisch in andere Systeme ein und müsst sie nicht doppelt pflegen. Jede API-Anfrage verursacht bei uns aber auch Serverlast und Infrastrukturkosten — je mehr Besucher eure Seite hat, desto mehr Ressourcen bindet das. Chorilo bekommt im Gegenzug über den kleinen Hinweis etwas Aufmerksamkeit, die uns hilft, neue Chöre zu erreichen.

HTML

<a href="https://www.chorilo.com" target="_blank" rel="noopener">
  Powered by Chorilo
</a>

Vorschau

Endpunkt

Ein einziger GET-Endpunkt liefert die kommenden Termine eures Ensembles zurück. Ersetzt durch den URL-Slug eurer öffentlichen Chorilo-Website.

Wo finde ich meinen Slug?

Öffnet im Chorilo-Backend die Einstellungen eurer öffentlichen Website. Der Slug ist der eindeutige Teil der URL, zum Beispiel 'mein-chor' in https://chorilo.com/w/mein-chor.

GET

https://backend.chorilo.com/api/public-websites/{slug}/embed-events

Sichtbarkeit kontrollieren

Die API respektiert die Sichtbarkeits-Einstellungen eurer öffentlichen Website. Alles, was auf der Website versteckt ist, ist auch über die API gesperrt — selbst wenn es explizit angefragt wird.

Haupt-Schalter: Ist show_events deaktiviert, liefert die API eine leere Liste zurück.

Termin-Typen: Nur freigegebene Typen werden ausgeliefert. Eine Anfrage für gesperrte Typen (zum Beispiel types[]=concert bei deaktivierter Konzert-Anzeige) wird stillschweigend gefiltert.

Einstellung	Betrifft Typ
show_events	Haupt-Schalter (schaltet alles ab)
show_rehearsals	`rehearsal`
show_concerts	`concert`
show_other_events	`event`
show_event_descriptions	Steuert das Feld description in der Antwort

Query-Parameter

Alle Parameter sind optional. Ohne Parameter liefert der Endpunkt die nächsten Termine gemäß den Standard-Einstellungen eurer Website.

Name	Typ	Standard	Beschreibung
limit	integer	5	Anzahl zurückgegebener Termine. Minimum 1, Maximum 100.
from	ISO 8601	jetzt	Startzeitpunkt für den Zeitraum. Vergangene Termine werden standardmäßig nicht ausgeliefert.
to	ISO 8601	—	Endzeitpunkt für den Zeitraum.
types[]	array	alle erlaubten	Eine oder mehrere der Typen: rehearsal, concert, event. Gesperrte Typen werden still gefiltert.
lang	string (2)	—	Zwei-Buchstaben-Sprachcode (de, en, fr, nl, es, sv, it, sl). Wird aktuell als Echo im Response-Meta zurückgegeben.

Rate-Limit & Caching

Der Endpunkt ist auf 60 Anfragen pro Minute und IP-Adresse begrenzt. Wird das Limit überschritten, antwortet der Server mit HTTP 429.

Antworten werden 5 Minuten serverseitig gecacht (pro Parameter-Kombination). Neue Termine erscheinen gegebenenfalls mit kurzer Verzögerung.

Rate-Limit

60 / min

pro IP-Adresse

Server-Cache

5 min

pro Parameter-Kombination

Antwort-Format

Die Antwort ist ein JSON-Objekt. Jeder Termin enthält nur öffentliche Felder — interne Beschreibungen, Teilnehmer-Daten oder andere sensible Informationen werden nie ausgeliefert.

events[] — Liste der Termine mit id, title, type, location, start_time, end_time, has_ticket_sale, optional ticket_sale_url (bei aktivem Ticketverkauf) und optional description.
ensemble_name — Anzeigename eures Ensembles.
theme_color — Hex-Farbcode aus den Website-Einstellungen.
language — Sprachcode eurer Website.

Das Feld description enthält ausschließlich die öffentliche Beschreibung. Die interne Terminbeschreibung ist niemals Teil der Antwort.

JSON

{
  "events": [
    {
      "id": 42,
      "title": "Sommerkonzert",
      "type": "concert",
      "location": "Stadthalle Musterstadt",
      "start_time": "2026-06-14T19:30:00+02:00",
      "end_time": "2026-06-14T21:30:00+02:00",
      "description": "Jährliches Sommerkonzert im Garten des Bürgerhauses.",
      "has_ticket_sale": true,
      "ticket_sale_url": "https://www.chorilo.com/shop/tickets/42"
    }
  ],
  "ensemble_name": "Musterchor",
  "theme_color": "#6366f1",
  "language": "de"
}

Beispiele

So ruft ihr die API aus verschiedenen Sprachen auf. Das Beispiel lädt bis zu 10 kommende Konzerte und sonstige Termine.

curl "https://backend.chorilo.com/api/public-websites/mein-chor/embed-events?limit=10&types[]=concert&types[]=event"

Status-Codes

Code	Bedeutung
200	Erfolgreich, Termine im events-Array.
404	Website mit diesem Slug nicht gefunden.
422	Ungültige Query-Parameter (zum Beispiel unbekannter Typ oder to vor from).
429	Rate-Limit überschritten, in einer Minute erneut versuchen.

All public endpoints

These are the read-only public endpoints currently exposed. No authentication required. JSON responses only.

Method	Path	Description	Limit
GET	/api/tickets/events	List public concert events	90/min
GET	/api/tickets/events/{eventId}	Single event detail	90/min
GET	/api/public-websites/{slug}	Public ensemble website by slug	90/min
GET	/api/public-websites/{slug}/embed-events	Embeddable concert calendar	60/min
GET	/api/choir-associations/public	Public association directory	90/min

Rate-limit response headers

Every /api/* response carries rate-limit headers. They are exposed via Access-Control-Expose-Headers for cross-origin agents.

X-RateLimit-Limit — per-window quota
X-RateLimit-Remaining — remaining requests
Retry-After — seconds to wait (HTTP 429 only)

JSON error format (RFC 9457)

All /api/* errors return application/problem+json regardless of Accept header.

{
  "type":     "https://www.chorilo.com/api/errors/not-found",
  "title":    "Resource not found",
  "status":   404,
  "detail":   "...",
  "instance": "/api/tickets/events/99999999"
}

Validation errors (422) include an errors object mapping fields to messages.

Fragen?

Bei technischen Fragen zur API wendet euch an: support@chorilo.com