Paginering en filters

Elk lijst-endpoint deelt één envelop, één cursorpaginering en dezelfde conventies voor filters. Deze pagina behandelt ze één keer; de endpoint-referentie zegt welke parameters elk endpoint aanvaardt.

De lijstenvelop

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

Eén bron (/v1/me, /v1/events/{id}, een POST-antwoord...) komt terug als het object zelf, zonder data-omhulsel en zonder pagination. Een paar kleine vaste lijsten (tickettypes, de dagen van een evenement) zitten in { "data": [...] } zonder pagination.

Cursorpaginering

Cursors zijn ondoorzichtig: ontleed of bouw ze niet zelf.

1. Vraag de eerste pagina op zonder cursor.
2. Zolang has_more true is, vraag de volgende pagina op met ?cursor={next_cursor}.
3. Stop wanneer has_more false is.

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"

Een misvormde of verouderde cursor antwoordt 400 invalid_cursor: begin opnieuw bij de eerste pagina. Er zijn geen paginanummers en geen totalen, en cursors blijven kloppen als gegevens veranderen tussen twee verzoeken.

Een pagina van meer dan 25 items kost meer van je werkbudget (één eenheid per 25): vraag wat je toont.

Evenementen filteren

GET /v1/events en GET /v1/events/search aanvaarden deze filters, allemaal optioneel en te combineren:

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"

De andere feeds (/v1/promoters/{id}/events, /v1/artists/{id}/events, /v1/venues/{id}/events) aanvaarden status, en de promotor- en locatiefeed ook from en to. Aankomende evenementen komen eerst met de vroegste erbij, voorbije evenementen met de laatste erbij; er is geen parameter sort. Een ongeldige waarde antwoordt 400 validation_error, met de naam van de parameter.

Batchopvragingen

ids= op /v1/events, /v1/artists, /v1/promoters en /v1/venues haalt tot 50 bekende ids op in één verzoek, in plaats van 50 detailverzoeken. Het kost één werkeenheid per begonnen blok van tien ids.

Velden kiezen

fields= houdt alleen de velden over die je noemt, op de detail- en lijst-endpoints die het ondersteunen. id blijft altijd behouden, en één niveau nesting is toegestaan:

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" } ]
}

Op een lijst geldt fields voor elk item in data. Tot 40 namen; een onbekende naam antwoordt 400 validation_error. Kleinere antwoorden reizen sneller en tellen minder mee voor je dagelijkse databudget.

Talen

locale= bepaalt de taal van de tekst die de API zelf schrijft: labels, kalender- en structured-datatekst, de Stripe-checkoutpagina. Het aanvaardt en, fr, de, es, it, nl of uk (fr-BE wordt gelezen als fr). Wat organisatoren en artiesten zelf schreven, komt terug zoals zij het schreven.

Uitbreiding

Twee endpoints sluiten gerelateerde bronnen in op verzoek met ?expand= (één niveau diep):

• GET /v1/events/{id}: de locatie en de line-up zijn er altijd bij; expand=ticket_tiers voegt de tickettypes toe.
• GET /v1/promoters/{id}/events: evenementen dragen een lichte locatie ({ id, name }) en geen line-up; expand=venue geeft de volledige locatie, expand=lineup en expand=ticket_tiers voegen die arrays toe.

Elke waarde kost één werkeenheid extra op een ongecachet verzoek, en bespaart een verzoek per evenement. Andere endpoints antwoorden 400 validation_error op expand.

HEAD en voorwaardelijke verzoeken

Elk detailendpoint antwoordt op HEAD met de headers van de GET en zonder body. Elke cachebare read draagt een ETag: stuur hem terug als If-None-Match en een ongewijzigde bron antwoordt 304 Not Modified, gratis. Zie Caching.

Waarom een bron 404 geeft

De API onderscheidt beheerde bronnen (de pagina's van je crew en hun evenementen) van publieke bronnen die je via je evenementen bereikt (een gastartiest, een locatie die je niet beheert); zie het overzicht.

• Publieke bronnen verschijnen alleen binnenin de bronnen die ernaar verwijzen, met "managed": false en publieke velden.
• Hem rechtstreeks opvragen (GET /v1/artists/{id} voor een gastartiest) geeft 404.
• Alles buiten het bereik van je crew geeft 404, nooit 403.
• Je roster-artiesten komen terug, ook ongepubliceerd. Elke andere bron geeft 404 (of ontbreekt in line-ups) tot ze gepubliceerd is.

Behandel elke 404 op dezelfde manier: de bron bestaat niet voor jouw sleutel.