Pagination et filtres

Chaque endpoint de liste partage une même enveloppe, une même pagination par curseur et les mêmes conventions de filtres. Cette page les couvre une fois pour toutes ; la référence des endpoints dit quels paramètres chaque endpoint accepte.

L'enveloppe de liste

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

Une ressource unique (/v1/me, /v1/events/{id}, une réponse POST...) revient comme l'objet lui-même, sans enveloppe data ni pagination. Quelques petites listes fixes (catégories de billets, jours d'un événement) sont enveloppées dans { "data": [...] } sans pagination.

Pagination par curseur

Les curseurs sont opaques : ne les analysez pas et ne les construisez pas vous-même.

1. Demandez la première page sans cursor.
2. Tant que has_more vaut true, demandez la page suivante avec ?cursor={next_cursor}.
3. Arrêtez quand has_more vaut false.

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

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

Un curseur malformé ou périmé répond 400 invalid_cursor : repartez de la première page. Il n'y a ni numéros de page ni totaux, et les curseurs restent corrects quand les données changent entre deux requêtes.

Une page de plus de 25 éléments coûte davantage de votre budget de travail (une unité par tranche de 25) : demandez ce que vous affichez.

Filtrer les événements

GET /v1/events et GET /v1/events/search acceptent ces filtres, tous facultatifs et combinables :

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_VOTRE_CLE"

Les autres flux (/v1/promoters/{id}/events, /v1/artists/{id}/events, /v1/venues/{id}/events) acceptent status, et les flux promoteur et salle acceptent aussi from et to. Les événements à venir arrivent du plus proche au plus lointain, les événements passés du plus récent au plus ancien ; il n'y a pas de paramètre sort. Une valeur invalide répond 400 validation_error, en nommant le paramètre.

Recherches par lot

ids= sur /v1/events, /v1/artists, /v1/promoters et /v1/venues récupère jusqu'à 50 ids connus en une seule requête, au lieu de 50 requêtes de détail. Cela coûte une unité de travail par tranche entamée de dix ids.

Choisir les champs

fields= ne garde que les champs que vous nommez, sur les endpoints de détail et de liste qui le prennent en charge. id est toujours gardé, et un niveau d'imbrication est permis :

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

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

Sur une liste, fields s'applique à chaque élément de data. Jusqu'à 40 noms ; un nom inconnu répond 400 validation_error. Des réponses plus petites voyagent plus vite et comptent moins contre votre allocation de données quotidienne.

Langues

locale= règle la langue du texte que l'API écrit elle-même : libellés, texte du calendrier et des données structurées, page de paiement Stripe. Elle accepte en, fr, de, es, it, nl ou uk (fr-BE se lit comme fr). Ce que les organisateurs et les artistes ont écrit revient tel quel.

Expansion

Deux endpoints intègrent des ressources liées sur demande avec ?expand= (un niveau de profondeur) :

• GET /v1/events/{id} : la salle et le lineup sont toujours là ; expand=ticket_tiers ajoute les catégories.
• GET /v1/promoters/{id}/events : les événements portent une salle légère ({ id, name }) et pas de lineup ; expand=venue donne la salle complète, expand=lineup et expand=ticket_tiers ajoutent ces tableaux.

Chaque valeur coûte une unité de travail de plus sur une requête non mise en cache, et économise une requête par événement. Les autres endpoints répondent 400 validation_error à expand.

Requêtes HEAD et conditionnelles

Chaque endpoint de détail répond à HEAD avec les en-têtes du GET et sans corps. Chaque lecture pouvant être mise en cache porte un ETag : renvoyez-le en If-None-Match et une ressource inchangée répond 304 Not Modified, gratuitement. Voir Mise en cache.

Pourquoi une ressource répond 404

L'API distingue les ressources gérées (les pages de votre crew et leurs événements) des ressources publiques atteintes à travers vos événements (un artiste invité, une salle que vous ne gérez pas) ; voir l'aperçu.

• Les ressources publiques apparaissent uniquement à l'intérieur des ressources qui les référencent, avec "managed": false et des champs publics.
• Les récupérer directement (GET /v1/artists/{id} pour un artiste invité) répond 404.
• Tout ce qui est hors de portée de votre crew répond 404, jamais 403.
• Les artistes de votre roster sont renvoyés même non publiés. Toute autre ressource répond 404 (ou est omise des lineups) tant qu'elle n'est pas publiée.

Traitez chaque 404 de la même façon : la ressource n'existe pas pour votre clé.