Paginación y filtros

Todos los endpoints de lista comparten un sobre, una paginación por cursor y las mismas convenciones de filtros. Esta página los explica una sola vez; la referencia de endpoints dice qué parámetros acepta cada endpoint.

El sobre de las listas

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

Un solo recurso (/v1/me, /v1/events/{id}, la respuesta de un POST...) vuelve como el propio objeto, sin envoltorio data y sin pagination. Unas pocas listas pequeñas y fijas (tipos de entrada, los días de un evento) van envueltas en { "data": [...] } sin pagination.

Paginación por cursor

Los cursores son opacos: no los analices ni los construyas.

1. Pide la primera página sin cursor.
2. Mientras has_more sea true, pide la página siguiente con ?cursor={next_cursor}.
3. Para cuando has_more sea 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 cursor mal formado o caducado responde 400 invalid_cursor: vuelve a empezar desde la primera página. No hay números de página ni totales, y los cursores siguen siendo correctos aunque los datos cambien entre dos peticiones.

Una página de más de 25 elementos cuesta más de tu presupuesto de trabajo (una unidad por cada 25): pide lo que muestras.

Filtrar eventos

GET /v1/events y GET /v1/events/search aceptan estos filtros, todos opcionales y 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_YOUR_KEY"

Los demás feeds (/v1/promoters/{id}/events, /v1/artists/{id}/events, /v1/venues/{id}/events) aceptan status, y los feeds de promotor y de sala también from y to. Los eventos futuros llegan del más próximo al más lejano, los pasados del más reciente al más antiguo; no hay parámetro sort. Un valor no válido responde 400 validation_error, nombrando el parámetro.

Consultas por lotes

ids= en /v1/events, /v1/artists, /v1/promoters y /v1/venues trae hasta 50 ids conocidos en una sola petición, en vez de 50 peticiones de detalle. Cuesta una unidad de trabajo por cada bloque empezado de diez ids.

Elegir campos

fields= conserva solo los campos que nombras, en los endpoints de detalle y de lista que lo admiten. id se conserva siempre, y se permite un nivel de anidamiento:

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

En una lista, fields se aplica a cada elemento de data. Hasta 40 nombres; un nombre desconocido responde 400 validation_error. Las respuestas más pequeñas viajan más rápido y cuentan menos contra tu cuota diaria de datos.

Idiomas

locale= fija el idioma del texto que escribe la propia API: etiquetas, el texto del calendario y de los datos estructurados, la página de checkout de Stripe. Acepta en, fr, de, es, it, nl o uk (fr-BE se lee como fr). Lo que escribieron organizadores y artistas vuelve tal cual lo escribieron.

Expansión

Dos endpoints incluyen recursos relacionados a petición con ?expand= (un nivel de profundidad):

• GET /v1/events/{id}: la sala y el line-up siempre están; expand=ticket_tiers añade los tipos de entrada.
• GET /v1/promoters/{id}/events: los eventos llevan una sala ligera ({ id, name }) y ningún line-up; expand=venue da la sala completa, expand=lineup y expand=ticket_tiers añaden esos arrays.

Cada valor cuesta una unidad de trabajo más en una petición sin caché, y ahorra una petición por evento. Los demás endpoints responden 400 validation_error a expand.

HEAD y peticiones condicionales

Todo endpoint de detalle responde a HEAD con las cabeceras del GET y sin cuerpo. Toda lectura cacheable lleva un ETag: devuélvelo como If-None-Match y un recurso sin cambios responde 304 Not Modified, gratis. Ver Caché.

Por qué un recurso responde 404

La API distingue los recursos gestionados (las páginas de tu crew y sus eventos) de los públicos a los que llegas a través de tus eventos (un artista invitado, una sala que no gestionas); ver el resumen.

• Los recursos públicos aparecen solo dentro de los recursos que los referencian, con "managed": false y campos públicos.
• Pedir uno directamente (GET /v1/artists/{id} para un artista invitado) responde 404.
• Todo lo que está fuera del alcance de tu crew responde 404, nunca 403.
• Tus artistas del roster se devuelven aunque no estén publicados. Cualquier otro recurso responde 404 (o queda fuera de los line-ups) hasta que se publica.

Trata todos los 404 igual: el recurso no existe para tu clave.