Panoramica dell'API

L'API pubblica di Sway permette a una crew (un'agenzia, un collettivo di promoter, un team di un locale) di far girare il proprio sito sui propri dati Sway. Il tuo sito resta indipendente e parla con Sway solo tramite l'API:

• Mostra il tuo roster, i tuoi eventi, le line-up e gli orari, i locali, le notizie, i partner, le gallerie e i press kit.
• Vendi biglietti: apri un checkout Sway dal tuo sito, verifica prima un coupon o un codice di accesso, segui l'ordine.
• Vendi merch dallo shop delle tue pagine: il catalogo, un carrello calcolato da Sway, un checkout Stripe sull'account della pagina.
• Raccogli: richieste di booking, iscrizioni alla newsletter, risposte ai tuoi moduli.
• Gestisci il tuo programma ambassador sulle tue pagine: iscrizione, accesso via link email, area membro, classifica, premi.
• Vieni a sapere dei cambiamenti appena succedono con i webhook, invece di chiedere ogni pochi minuti.
• Chiedi a un assistente IA dei tuoi dati tramite il server MCP.

URL di base

https://www.sway.events/api/v1

Ogni endpoint è versionato sotto /v1. Le risposte sono JSON con chiavi in snake_case, tranne i feed di calendario (text/calendar) e gli export (NDJSON). GET /v1/openapi.json descrive ogni endpoint in OpenAPI 3.1, e GET /v1/changelog elenca cosa è cambiato e quando.

Chi ha accesso

L'API è inclusa nei piani Studio e Roster. Le chiavi si creano in Admin della crew → API da parte di qualcuno con il permesso Gestire API sulla crew.

Ogni chiave appartiene a esattamente una crew: è solo la chiave a decidere quali dati vedi, mai un parametro della richiesta. Se l'abbonamento della crew scade, le sue chiavi smettono di funzionare finché non torna attivo.

Cosa può vedere la tua chiave

Ogni risorsa che l'API restituisce è gestita o pubblica:

Esempio: l'artista ospite. L'evento del tuo promoter ha in line-up un artista che non fa parte della tua crew. L'artista compare dentro la line-up dell'evento solo con i campi pubblici (nome, immagine, generi) e "managed": false. Richiesto direttamente, GET /v1/artists/{id} risponde 404.

Tutto ciò che sta fuori dalle pagine della tua crew risponde 404, mai 403, così l'API non rivela nulla su quello che non puoi raggiungere.

Avvio rapido

Verifica la tua chiave e cosa può fare:

curl https://www.sway.events/api/v1/me \
  -H "Authorization: Bearer sway_sk_YOUR_KEY"

{
  "key": {
    "id": "3f9a1c02-7b45-4c8e-9d21-0a1b2c3d4e5f",
    "type": "secret",
    "scopes": ["read:profile", "read:artists", "read:promoters", "read:events", "read:venues", "read:content"],
    "rate_limit": { "per_minute": 120, "per_day": 20000 },
    "limits": {
      "requests_per_minute": 2400,
      "crew_work_per_minute": 600,
      "crew_work_per_day": 120000,
      "bytes_per_day": 5368709120
    },
    "websites": []
  },
  "crew": { "id": "a2628d53-4f21-4c1e-9b7d-1a2b3c4d5e6f", "name": "Insomnia", "slug": "insomnia" }
}

Poi elenca i tuoi eventi in arrivo:

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

Una singola risorsa torna come l'oggetto stesso; un elenco arriva avvolto in { "data": [...], "pagination": {...} }.

Per saperne di più