Pagination & filtres

Tous les endpoints de liste partagent la même enveloppe, la même pagination par curseur, les mêmes paramètres de filtre et le même mécanisme d'expansion.

Enveloppe de réponse

{
  "data": [ … ],
  "pagination": {
    "next_cursor": "eyJzb3J0X2tleSI6IjIwMjYtMDktMTIiLCJpZCI6NDUyMX0",
    "has_more": true,
    "limit": 25
  }
}

Les endpoints de ressource unique (/v1/me, /v1/crew, /v1/artists/{id}, /v1/promoters/{id}, /v1/events/{id}, /v1/venues/{id}, et POST /v1/booking-requests) renvoient l'objet directement — sans enveloppe data ni pagination. GET /v1/events/{id}/ticket-tiers est le seul cas hybride : une petite liste fixe enveloppée dans { "data": [ … ] } mais sans pagination ni curseur.

Pagination par curseur

La pagination est basée sur des curseurs. Les curseurs sont des chaînes opaques — ne les analysez pas et ne les construisez pas vous-même.

1. Faites la première requête sans cursor.
2. Si has_more vaut true, demandez la page suivante avec ?cursor={next_cursor}.
3. Répétez jusqu'à ce que has_more vaille 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é renvoie 400 invalid_cursor — repartez de la première page.

Filtres

Les flux d'événements acceptent un filtre status ; les deux flux datés acceptent aussi from / to :

from / to s'appliquent à GET /v1/events et GET /v1/promoters/{id}/events. GET /v1/artists/{id}/events n'accepte que status. L'ordre est fixe (upcoming → date de début croissante ; past / all → décroissante) — il n'y a pas de paramètre sort.

curl "https://www.sway.events/api/v1/promoters/697/events?status=upcoming" \
  -H "Authorization: Bearer sway_sk_VOTRE_CLE"

Les valeurs de filtre invalides renvoient 400 validation_error.

Expansion

Deux endpoints d'événements acceptent ?expand= pour intégrer directement les ressources liées (profondeur 1) :

• GET /v1/events/{id} — venue et lineup sont toujours intégrés ; ajoutez ?expand=ticket_tiers pour inclure aussi les catégories.
• GET /v1/promoters/{id}/events — les événements portent par défaut une référence venue légère ({ id, name }) et pas de lineup/catégories. ?expand=venue fait passer la salle au niveau public complet ; ?expand=lineup et ?expand=ticket_tiers ajoutent ces tableaux.

GET /v1/events (le flux combiné) ne supporte pas expand — le passer renvoie 400 validation_error. GET /v1/artists/{id}/events n'accepte pas non plus expand.

curl "https://www.sway.events/api/v1/promoters/697/events?expand=venue,lineup,ticket_tiers" \
  -H "Authorization: Bearer sway_sk_VOTRE_CLE"

Les objets intégrés sont toujours sérialisés au niveau public, sauf si la ressource est aussi gérée par votre crew.

Visibilité : pourquoi certaines ressources renvoient 404

L'API distingue les ressources gérées (les pages et événements de votre crew) des ressources étrangères accessibles à travers vos événements (invités du lineup, salles) — voir l'aperçu.

• Les ressources étrangères sont intégrées uniquement. Elles apparaissent dans les réponses d'événements avec "managed": false et un jeu de champs public réduit.
• Récupérer directement un artiste ou promoteur étranger (GET /v1/artists/{id}) renvoie 404 — ils ne sont pas adressables directement.
• Les ressources entièrement en dehors du graphe de votre crew renvoient aussi 404, jamais 403. L'API ne confirme pas l'existence de données auxquelles vous n'avez pas accès.
• Les artistes de votre roster sont renvoyés même s'ils ne sont pas publiés (ce sont vos propres données). Pour toute autre ressource — promoteurs, événements, salles et toute ressource intégrée/étrangère — les brouillons (non publiés) renvoient 404 ou sont omis des lineups.

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