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-Token, das du einmalig in deinen Artistu-Einstellungen generierst und 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.

Generiere dein API-Token

Gehe zu Einstellungen → Integrationen und öffne den Bereich Öffentliche API. Klicke auf Token generieren. Dafür musst du Admin deiner Organisation sein.

Das Token ist eine Zeichenkette mit 64 Zeichen. Behandle es wie ein Passwort: Jeder, der es besitzt, kann deine öffentlichen Buchungsdaten lesen. Nach der Generierung wird es in der Oberfläche maskiert, mit Anzeigen kannst du es wieder einblenden.

Sobald ein Token existiert, stehen zwei weitere Aktionen zur Verfügung:

• Token neu generieren erstellt ein neues Token und macht das alte sofort ungültig. Jede Website oder Integration, die noch das alte Token verwendet, funktioniert ab diesem Moment nicht mehr.
• Token widerrufen löscht das Token, ohne ein neues zu erstellen. Der gesamte API-Zugriff stoppt, bis du ein neues Token generierst.

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 Einstellungen und scrolle zum Bereich Online. 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: Das Token fehlt, ist fehlerhaft oder wurde neu generiert oder widerrufen. Prüfe den Authorization: Bearer-Header und vergleiche das Token mit dem unter Einstellungen → Integrationen.
• 404 Artist not found: Die Künstler-ID existiert nicht oder gehört zu einer anderen Organisation als das Token.
• 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.