Pagination & filtering

All list endpoints share the same envelope, cursor pagination, filter parameters and expansion mechanism.

Response envelope

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

Single-resource endpoints (/v1/me, /v1/crew, /v1/artists/{id}, /v1/promoters/{id}, /v1/events/{id}, /v1/venues/{id}, and POST /v1/booking-requests) return the resource object directly — no data wrapper and no pagination. GET /v1/events/{id}/ticket-tiers is the one hybrid: a small fixed list wrapped in { "data": [ … ] } but with no pagination and no cursor.

Cursor pagination

Pagination is cursor-based. Cursors are opaque strings — do not parse or build them yourself.

1. Make the first request without a cursor.
2. If has_more is true, request the next page with ?cursor={next_cursor}.
3. Repeat until has_more is 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"

A malformed or stale cursor returns 400 invalid_cursor — restart from the first page.

Filtering

Event feeds accept a status filter; the two dated feeds also accept from / to:

from / to apply to GET /v1/events and GET /v1/promoters/{id}/events. GET /v1/artists/{id}/events accepts status only. Ordering is fixed (upcoming → start date ascending; past / all → descending) — there is no sort parameter.

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

Invalid filter values return 400 validation_error.

Expansion

Two event endpoints accept ?expand= to embed related resources inline (depth 1):

• GET /v1/events/{id} — venue and lineup are always embedded; add ?expand=ticket_tiers to also include the tiers.
• GET /v1/promoters/{id}/events — events carry a light venue reference ({ id, name }) by default and no lineup/tiers. ?expand=venue upgrades the venue to the full public tier; ?expand=lineup and ?expand=ticket_tiers add those arrays.

GET /v1/events (the union feed) does not support expand — passing it returns 400 validation_error. GET /v1/artists/{id}/events does not accept expand either.

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

Embedded objects are always serialized at the public tier unless the resource is also managed by your crew.

Visibility: why some resources return 404

The API distinguishes managed resources (your crew's pages and events) from foreign resources reachable through your events (lineup guests, venues) — see the overview.

• Foreign resources are embedded only. They appear inline in event payloads with "managed": false and a reduced public field set.
• Fetching a foreign artist or promoter directly (GET /v1/artists/{id}) returns 404 — they are not directly addressable.
• Resources entirely outside your crew's graph also return 404, never 403. The API does not confirm the existence of data you cannot access.
• Your roster artists are returned even while unpublished (they are your own data). For every other resource — promoters, events, venues and any embedded/foreign resource — unpublished (draft) records return 404 or are omitted from lineups.

In practice: treat every 404 the same way — the resource does not exist for your key.