Website Integration
Website integration
This page is the recommended recipe for connecting an agency or promoter website to the Sway Public API: your site keeps its own design and hosting, and Sway becomes its data source for roster, events and tickets.
1. Call the API server-side only
The API key is a secret. All API calls must go through your server (API routes, server-side rendering, edge functions) — never from the visitor's browser.
- Store the key in an environment variable or secret store (
SWAY_API_KEY), never in the repository or client bundle. - Expose your own internal routes (e.g.
/api/site-data) to your frontend; those routes call Sway with the key and return only what the page needs. - Rotate the key by creating a new one in Crew admin → API, deploying it, then revoking the old one.
2. Cache aggressively
A website does not need live data on every page view. Cache API responses on your server with TTLs matched to how fast each resource changes:
| Data | Endpoint(s) | Recommended TTL |
|---|---|---|
| Crew profile & roster | /v1/crew, /v1/artists | 1 hour |
| Events | /v1/events, /v1/promoters/{id}/events | 5 minutes |
| Ticket tiers | /v1/events/{id}/ticket-tiers | 60 seconds |
| Checkout | checkout_url deep link | Never cache — it is just a link |
With these TTLs a typical partner site makes a handful of API requests per minute regardless of traffic — far below the default rate limits — and survives short API outages by serving from cache.
?expand=venue,lineup,ticket_tiers on the events feed: one cached response covers an entire events page.3. Sell tickets through Sway — deep links only
Ticket sales always happen on Sway. Never rebuild a checkout on the partner site.
- Each ticket tier includes a
checkout_url(e.g.https://www.sway.events/event/4521?ref=api). - Render your own "Get tickets" button and link it straight to
checkout_url. - Use the tier
status(on_sale,scheduled,sold_out,off_sale) and prices to display availability — the API intentionally exposes no stock counts and no buyer data.
4. Forward booking requests
If your site has a booking form (with a key that has the write:bookings scope):
- The visitor fills the form on your site.
- Your server validates the input, then calls
POST /v1/booking-requests. - The request lands in your crew's booking pipeline on Sway and the crew is notified.
Keep your own spam protection (captcha, honeypot) in front of the form — the endpoint is rate-limited tighter than the read endpoints (10 requests / minute).
5. Keep placeholders as a fallback
Keep your site's static content (placeholder artists, sample events) as a fallback layer rather than deleting it:
- If the API is unreachable and the cache is empty, render the placeholders instead of an empty page.
- If the API returns fewer items than the design needs, pad the grid with placeholders.
- Merge order: API data → your site's selection/config → placeholders to fill the gaps.
This keeps the site presentable at all times, including during initial setup before the first key is configured.
Checklist
-
SWAY_API_KEYstored as a server-side secret - All Sway calls proxied through your own server routes
- Cache TTLs: roster/profile 1 h, events 5 min, ticket tiers 60 s
- Ticket buttons link to
checkout_url— no custom checkout - Booking form posts server-side to
/v1/booking-requests - Placeholder content kept as fallback
-
GET /v1/meused as a health/config check