Paginazione e filtri

Ogni endpoint di elenco condivide una busta, una paginazione a cursore e le stesse convenzioni per i filtri. Questa pagina le tratta una sola volta; il riferimento degli endpoint dice quali parametri accetta ciascun endpoint.

La busta dell'elenco

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

Una singola risorsa (/v1/me, /v1/events/{id}, una risposta a un POST...) torna come l'oggetto stesso, senza involucro data e senza pagination. Poche piccole liste fisse (tipi di biglietto, i giorni di un evento) sono avvolte in { "data": [...] } senza pagination.

Paginazione a cursore

I cursori sono opachi: non analizzarli né costruirli da solo.

1. Chiedi la prima pagina senza cursor.
2. Finché has_more è true, chiedi la pagina successiva con ?cursor={next_cursor}.
3. Fermati quando has_more è false.

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"

Un cursore malformato o scaduto risponde 400 invalid_cursor: riparti dalla prima pagina. Non ci sono numeri di pagina né totali, e i cursori restano corretti quando i dati cambiano tra due richieste.

Una pagina di più di 25 elementi costa di più del tuo budget di lavoro (un'unità ogni 25): chiedi quello che mostri.

Filtri sugli eventi

GET /v1/events e GET /v1/events/search accettano questi filtri, tutti opzionali e combinabili:

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"

Gli altri feed (/v1/promoters/{id}/events, /v1/artists/{id}/events, /v1/venues/{id}/events) accettano status, e i feed di promoter e locale anche from e to. Gli eventi in arrivo vengono prima i più vicini, gli eventi passati prima i più recenti; non esiste un parametro sort. Un valore non valido risponde 400 validation_error, nominando il parametro.

Ricerche in blocco

ids= su /v1/events, /v1/artists, /v1/promoters e /v1/venues recupera fino a 50 id noti in una sola richiesta, invece di 50 richieste di dettaglio. Costa un'unità di lavoro per ogni blocco iniziato di dieci id.

Selezione dei campi

fields= mantiene solo i campi che nomini, sugli endpoint di dettaglio e di elenco che lo supportano. id viene sempre mantenuto, ed è permesso un livello di annidamento:

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

Su un elenco, fields si applica a ogni elemento in data. Fino a 40 nomi; un nome sconosciuto risponde 400 validation_error. Risposte più piccole viaggiano più veloci e contano meno sulla tua quota giornaliera di dati.

Lingue

locale= imposta la lingua del testo che l'API scrive da sola: etichette, testo di calendario e dati strutturati, la pagina di checkout Stripe. Accetta en, fr, de, es, it, nl o uk (fr-BE viene letto come fr). Quello che organizzatori e artisti hanno scritto torna come l'hanno scritto.

Espansione

Due endpoint includono risorse collegate su richiesta con ?expand= (un livello di profondità):

• GET /v1/events/{id}: il locale e la line-up ci sono sempre; expand=ticket_tiers aggiunge i tipi di biglietto.
• GET /v1/promoters/{id}/events: gli eventi portano un locale leggero ({ id, name }) e nessuna line-up; expand=venue dà il locale completo, expand=lineup e expand=ticket_tiers aggiungono quegli array.

Ogni valore costa un'unità di lavoro in più su una richiesta non in cache, e risparmia una richiesta per evento. Gli altri endpoint rispondono 400 validation_error a expand.

HEAD e richieste condizionali

Ogni endpoint di dettaglio risponde a HEAD con gli header del GET e senza corpo. Ogni lettura in cache porta un ETag: rimandalo indietro come If-None-Match e una risorsa non cambiata risponde 304 Not Modified, gratis. Vedi Cache.

Perché una risorsa risponde 404

L'API distingue le risorse gestite (le pagine della tua crew e i loro eventi) da quelle pubbliche raggiunte tramite i tuoi eventi (un artista ospite, un locale che non gestisci); vedi la panoramica.

• Le risorse pubbliche compaiono solo dentro le risorse che le referenziano, con "managed": false e campi pubblici.
• Richiederne una direttamente (GET /v1/artists/{id} per un artista ospite) risponde 404.
• Tutto ciò che sta fuori dalla portata della tua crew risponde 404, mai 403.
• I tuoi artisti del roster vengono restituiti anche se non pubblicati. Ogni altra risorsa risponde 404 (o manca dalle line-up) finché non è pubblicata.

Tratta ogni 404 allo stesso modo: la risorsa non esiste per la tua chiave.