Zeige deine Buchungen mit der öffentlichen API auf deiner Website

Viele Agenturen und Künstler zeigen ihre kommenden Termine auf der eigenen Website: eine Tour-Seite, einen Gig-Kalender oder eine einfache Liste von Shows. Die öffentliche Artistu-API liefert dir einen schreibgeschützten Feed deiner angekündigten Buchungen, sodass deine Website immer dieselben Termine zeigt, die du in Artistu verwaltest. Kein manuelles Kopieren, keine veralteten Tour-Seiten.

Die API ist schreibgeschützt und gibt ausschließlich Informationen heraus, die du explizit als öffentlich markiert hast. Gagen, Deals, Kontakte, interne Notizen und nicht angekündigte Shows sind niemals enthalten.

So funktioniert es

Drei Teile arbeiten zusammen:

1. Ein API-Schlüssel, den du in deinen Artistu-Einstellungen erstellst und auf die gewählten Künstler beschränkst, mit dem sich deine Website authentifiziert.
2. Online-Einstellungen pro Buchung, die steuern, ob eine Buchung angekündigt ist und welche öffentlichen Details sie enthält.
3. Ein einzelner Endpunkt, der die angekündigten Buchungen eines Künstlers als JSON zurückgibt.

Erstelle einen API-Schlüssel

Gehe zu Einstellungen → Integrationen und öffne den Bereich Öffentliche API-Schlüssel. Klicke auf Schlüssel erstellen, gib dem Schlüssel einen Namen (zum Beispiel die Website, für die er gedacht ist) und wähle die Künstler, die er lesen darf, oder setze den Haken bei Alle Künstler. Dafür musst du Admin deiner Organisation sein.

Der Schlüssel wird einmal angezeigt, direkt nach dem Erstellen. Kopiere ihn sofort: Artistu speichert nur einen Fingerabdruck des Schlüssels, niemand kann ihn später nachschlagen, auch wir nicht. Schlüssel verloren? Widerrufe ihn und erstelle einen neuen.

Schlüssel sind auf ihre Künstler beschränkt. Ein Schlüssel für die Website eines Künstlers liefert nur dessen Buchungen, ein geleakter Schlüssel betrifft also diesen Künstler und nicht dein ganzes Roster. Erstelle pro Website einen eigenen Schlüssel.

Jeder Schlüssel in der Liste zeigt seine Künstler, wann er erstellt und wann er zuletzt verwendet wurde. Widerrufen stoppt einen Schlüssel sofort. Jede Website oder Integration, die ihn noch verwendet, funktioniert ab diesem Moment nicht mehr.

Hast du ein Token erstellt, bevor es Schlüssel gab? Es funktioniert vorerst weiter und hat Zugriff auf alle Künstler. Erstelle einen neuen Schlüssel, passe deine Website an und widerrufe dann das alte Token.

Steuere, welche Buchungen erscheinen

Nicht jede Buchung gehört auf deine Website. Eine Buchung erscheint nur dann in der API, wenn alle folgenden Bedingungen erfüllt sind:

1. Der Buchungsstatus ist Option oder Bestätigt. Ausstehende und abgesagte Buchungen erscheinen nie.
2. Die Buchung ist angekündigt: Entweder ist der Schalter Angekündigt aktiviert, oder das Datum Ankündigen am liegt in der Vergangenheit.
3. Der Schalter Von öffentlicher API verbergen ist deaktiviert.

Das steuerst du pro Buchung. Öffne eine Buchung, gehe zum Tab Details und scrolle zum Bereich Öffentlich. Dort findest du:

Feld	Zweck
Ankündigen am	Datum, ab dem die Buchung automatisch als angekündigt gilt
Angekündigt	Markiere die Buchung sofort manuell als angekündigt
Von öffentlicher API verbergen	Halte die Buchung aus der API heraus, auch wenn sie angekündigt ist
Webseite	Öffentliche Event- oder Venue-Website, in der API-Antwort enthalten
Ticket-Link	Link zum Ticketverkauf, in der API-Antwort enthalten
Line-up	Öffentlicher Line-up-Text, in der API-Antwort enthalten
Öffentliche Notizen	Beliebiger zusätzlicher öffentlicher Text, in der API-Antwort enthalten

Das Datum Ankündigen am ist praktisch, wenn eine Show bestätigt ist, aber bis zum offiziellen Ankündigungstermin unter Embargo steht. Setze das Datum, und die Buchung erscheint ab diesem Tag automatisch in der API.

Von öffentlicher API verbergen ist der Override für Shows, die zwar anderswo angekündigt sind, aber nicht auf deiner Website erscheinen sollen, zum Beispiel private Veranstaltungen.

Finde deine Künstler-ID

Die API gibt Buchungen für jeweils einen Künstler zurück. Die Künstler-ID findest du in der Adresszeile, wenn du den Künstler in deinem Dashboard öffnest:

https://artistu.io/dashboard/artists/{artistId}

Der letzte Teil der URL ist die ID, die du an die API übergibst. Zeigt deine Website mehrere Künstler, stelle eine Anfrage pro Künstler.

Buchungen abrufen

GET https://artistu.io/api/public/bookings/{artistId}

Authentifiziere dich mit deinem Token im Authorization-Header:

Authorization: Bearer YOUR_API_TOKEN

Query-Parameter

Parameter	Format	Standard	Beschreibung
startDate	YYYY-MM-DD	heute	Erstes enthaltenes Datum
endDate	YYYY-MM-DD	startDate + 1 Monat	Letztes enthaltenes Datum

Der Datumsbereich darf höchstens 366 Tage umfassen, und startDate muss auf oder vor endDate liegen.

Beispiel-Anfrage

curl -X GET 'https://artistu.io/api/public/bookings/{artistId}?startDate=2026-08-01&endDate=2026-12-31' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Beispiel-Antwort

{
  "bookings": [
    {
      "bookingId": "uq1ye3nqnb4m5f234auf69gk",
      "artistName": "DJ Example",
      "name": "Summer Festival 2026",
      "date": "2026-08-15T00:00:00.000Z",
      "time": "22:00",
      "duration": 90,
      "venue": "Festival Grounds",
      "capacity": 15000,
      "status": "confirmed",
      "address": {
        "description": "Festival Grounds, Amsterdam, Netherlands",
        "geometry": { "lat": 52.3676, "lng": 4.9041 },
        "components": {
          "city": "Amsterdam",
          "country": "Netherlands",
          "countryCode": "NL"
        }
      },
      "website": "https://summerfestival.example",
      "ticketLink": "https://tickets.example/summer-festival",
      "lineUp": "DJ Example, Support Act",
      "publicNotes": "Main stage closing set"
    }
  ],
  "truncated": false
}

Buchungen sind aufsteigend nach Datum sortiert. duration ist in Minuten. status ist entweder option oder confirmed. Felder ohne Wert sind null.

Eine Antwort enthält höchstens 500 Buchungen. Passen mehr in deinen Datumsbereich, ist truncated gleich true und ein Feld maxResults ist enthalten. Verkleinere den Datumsbereich, um den Rest abzurufen.

Rate-Limits

• 60 Anfragen pro Minute pro Token
• 120 Anfragen pro Minute pro IP-Adresse

Jede Antwort enthält die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Überschreitest du ein Limit, antwortet die API mit Status 429 und teilt dir mit, wie viele Sekunden du warten musst.

Für eine typische Website solltest du die API-Antwort einige Minuten auf deinem eigenen Server cachen, statt die API bei jedem Seitenaufruf zu rufen. Deine Tour-Seite bleibt schnell und du bleibst weit von den Limits entfernt.

Fehlerbehebung

• 401 Unauthorized: Der Schlüssel fehlt, ist fehlerhaft oder wurde widerrufen. Prüfe den Authorization: Bearer-Header und vergleiche den Anfang des Schlüssels mit der Liste unter Einstellungen → Integrationen.
• 404 Artist not found: Die Künstler-ID existiert nicht, gehört zu einer anderen Organisation oder gehört nicht zu den Künstlern des Schlüssels.
• 400 Bad request: Ein Datum ist nicht im Format YYYY-MM-DD, startDate liegt nach endDate, oder der Bereich überschreitet 366 Tage.
• Eine Buchung fehlt: Prüfe die drei Sichtbarkeitsbedingungen oben. Meistens ist die Buchung noch nicht angekündigt oder ihr Status ist noch ausstehend.