Paginierung & Filter

Jeder Listen-Endpunkt teilt sich einen Umschlag, eine Cursor-Paginierung und dieselben Konventionen für Filter. Diese Seite behandelt sie einmal; die Endpunkt-Referenz sagt, welche Parameter jeder Endpunkt nimmt.

Der Listen-Umschlag

{
  "data": [ { "id": 4521, "title": "Insomnia Night: Autumn Opening" } ],
  "pagination": {
    "next_cursor": "eyJzb3J0X2tleSI6IjIwMjYtMTAtMDMiLCJpZCI6NDUyMX0",
    "has_more": true,
    "limit": 25
  }
}

Eine einzelne Ressource (/v1/me, /v1/events/{id}, eine POST-Antwort...) kommt als das Objekt selbst zurück, ohne data-Hülle und ohne pagination. Ein paar kleine feste Listen (Tickettypen, die Tage einer Veranstaltung) sind in { "data": [...] } verpackt, ohne pagination.

Cursor-Paginierung

Cursor sind undurchsichtig: Zerleg oder bau sie nicht selbst.

1. Frag die erste Seite ohne cursor an.
2. Solang has_more true ist, frag die nächste Seite mit ?cursor={next_cursor} an.
3. Hör auf, wenn has_more false ist.

curl "https://www.sway.events/api/v1/events?limit=50" \
  -H "Authorization: Bearer sway_sk_YOUR_KEY"

curl "https://www.sway.events/api/v1/events?limit=50&cursor=eyJzb3J0X2tleSI6..." \
  -H "Authorization: Bearer sway_sk_YOUR_KEY"

Ein fehlerhafter oder veralteter Cursor antwortet mit 400 invalid_cursor: Fang wieder bei der ersten Seite an. Es gibt keine Seitenzahlen und keine Gesamtzahlen, und Cursor bleiben korrekt, auch wenn sich Daten zwischen zwei Anfragen ändern.

Eine Seite mit mehr als 25 Einträgen kostet mehr von deinem Arbeitsbudget (eine Einheit pro 25): Frag nach dem, was du anzeigst.

Veranstaltungen filtern

GET /v1/events und GET /v1/events/search nehmen diese Filter, alle optional und kombinierbar:

curl "https://www.sway.events/api/v1/events?country=BE&from=2026-10-01&to=2026-10-31&genre=12,31" \
  -H "Authorization: Bearer sway_sk_YOUR_KEY"

Die anderen Feeds (/v1/promoters/{id}/events, /v1/artists/{id}/events, /v1/venues/{id}/events) nehmen status, und die Veranstalter- und Venue-Feeds zusätzlich from und to. Kommende Veranstaltungen kommen mit der nächsten zuerst, vergangene mit der letzten zuerst; einen Parameter sort gibt es nicht. Ein ungültiger Wert antwortet mit 400 validation_error und nennt den Parameter.

Batch-Abfragen

ids= auf /v1/events, /v1/artists, /v1/promoters und /v1/venues holt bis zu 50 bekannte IDs in einer Anfrage, statt 50 Detailanfragen. Es kostet eine Arbeitseinheit pro begonnenem Block von zehn IDs.

Felder auswählen

fields= behält nur die Felder, die du nennst, bei den Detail- und Listen-Endpunkten, die das unterstützen. id bleibt immer erhalten, und eine Verschachtelungsebene ist erlaubt:

curl "https://www.sway.events/api/v1/events/4521?fields=title,starts_at,venue.name,lineup.name" \
  -H "Authorization: Bearer sway_sk_YOUR_KEY"

{
  "id": 4521,
  "title": "Insomnia Night: Autumn Opening",
  "starts_at": "2026-10-03T20:00:00+00:00",
  "venue": { "id": 77, "name": "Fuse" },
  "lineup": [ { "id": 501, "name": "Lucia Vega" } ]
}

Bei einer Liste gilt fields für jeden Eintrag in data. Bis zu 40 Namen; ein unbekannter Name antwortet mit 400 validation_error. Kleinere Antworten reisen schneller und zählen weniger gegen dein tägliches Datenkontingent.

Sprachen

locale= legt die Sprache des Texts fest, den die API selbst schreibt: Labels, Kalender- und Structured-Data-Text, die Stripe-Checkout-Seite. Sie nimmt en, fr, de, es, it, nl oder uk (fr-BE wird als fr gelesen). Was Organisatoren und Künstler geschrieben haben, kommt so zurück, wie sie es geschrieben haben.

Erweiterung

Zwei Endpunkte betten auf Anfrage verwandte Ressourcen mit ?expand= ein (eine Ebene tief):

• GET /v1/events/{id}: der Veranstaltungsort und das Lineup sind immer dabei; expand=ticket_tiers fügt die Tickettypen hinzu.
• GET /v1/promoters/{id}/events: Veranstaltungen tragen einen leichten Veranstaltungsort ({ id, name }) und kein Lineup; expand=venue liefert den vollen Veranstaltungsort, expand=lineup und expand=ticket_tiers fügen diese Arrays hinzu.

Jeder Wert kostet bei einer ungecachten Anfrage eine weitere Arbeitseinheit, und spart eine Anfrage pro Veranstaltung. Andere Endpunkte antworten auf expand mit 400 validation_error.

HEAD und bedingte Anfragen

Jeder Detail-Endpunkt antwortet auf HEAD mit den Headern des GET und ohne Body. Jeder cachebare Lesezugriff trägt ein ETag: Schick es als If-None-Match zurück, und eine unveränderte Ressource antwortet mit 304 Not Modified, gratis. Siehe Caching.

Warum eine Ressource 404 liefert

Die API unterscheidet verwaltete Ressourcen (die Seiten deiner Crew und ihre Veranstaltungen) von öffentlichen, die über deine Veranstaltungen erreicht werden (ein Gastkünstler, ein Veranstaltungsort, den du nicht verwaltest); siehe den Überblick.

• Öffentliche Ressourcen erscheinen nur innerhalb der Ressourcen, die auf sie verweisen, mit "managed": false und öffentlichen Feldern.
• Eine direkt abzurufen (GET /v1/artists/{id} für einen Gastkünstler) antwortet mit 404.
• Alles außerhalb der Reichweite deiner Crew antwortet mit 404, nie mit 403.
• Deine Roster-Künstler kommen auch unveröffentlicht zurück. Jede andere Ressource antwortet mit 404 (oder fehlt im Lineup), bis sie veröffentlicht ist.

Behandle jede 404 gleich: Die Ressource existiert nicht für deinen Schlüssel.