Developer quick start

Track A — Embed widgets

A "Buy tickets" button or "Upcoming events" grid that you paste into any website. Async, Shadow-DOM-isolated, no API keys.

1. Copy a snippet from the dashboard

   Open the event's detail page (for a Buy button) or the events list page (for organizer listings) in the dashboard. Find the "Embed" card and click the copy button. The snippet includes your real event ID, brand color, and loader URL.

2. Paste into your website

   Use a plain HTML/embed block. Never use a rich-text block — it will mangle the <script> tag.

   Example snippet

   <div
     class="tickets-widget"
     data-widget-type="listings"
     data-organizer="acme-theatre"
     data-limit="6"
     data-primary-color="#F2CC5D"
   ></div>
   <script async src="https://gigshack-tickets-staging.up.railway.app/v1/loader.js"></script>

   See Widget docs for step-by-step guides for WordPress, Squarespace, Webflow, Wix, and plain HTML.

3. Publish and verify

   Open the page in a browser. The widget should render inline. Click the button or a card — it should open the hosted event page in a new tab. If it doesn't, check the troubleshooting matrix.

4. Customize (optional)

   Change data-primary-color to your brand color, adjust data-limit on listings, or set data-label on a Buy button. The full attribute reference lists every option.

Before going live: Verify the event is published, the organizer is active, the data-event-id is a real dashboard ID (not evt_DEMO), and clicking through lands on the correct hosted event page.

Track B — Use the API

Read your organization's published events and ticket types with a Bearer-authenticated REST API.

1. Create an API key

   Sign in to the dashboard as an org admin. Go to API keys in the dashboard sidebar. Click Create API key, enter a name, choose permissions, and click Create.

   Important: The raw key is shown once on the confirmation page. Copy it immediately and store it in your secret manager. You will not be able to see it again.

2. Make your first request

   Pass the key in the Authorization header on every request:

   curl

   curl -H "Authorization: Bearer gsk_YOUR_KEY" \
     https://your-domain.example/api/v1/events

   A successful response returns a 200 with a JSON body. Events are in data, pagination in pagination.

3. Get a single event

   curl

   curl -H "Authorization: Bearer gsk_YOUR_KEY" \
     https://your-domain.example/api/v1/events/friday-sessions

   Returns a single event object with the same shape as one element of the list data array.

4. Handle pagination

   The list endpoint is paginated. Use has_more to walk all pages:

   JavaScript

   let page = 1
   while (true) {
     const res = await fetch(
       `https://your-domain.example/api/v1/events?page=${page}&limit=100`,
       { headers: { Authorization: `Bearer ${process.env.API_KEY}` } },
     )
     const json = await res.json()
     await processEvents(json.data)
     if (!json.pagination.has_more) break
     page++
   }

5. Use the public widget API for unauthenticated reads

   If you need to read public event data from a browser without exposing a key, use the public widget API:

   curl

   curl https://your-domain.example/api/public/widgets/events?organizer=acme-theatre&limit=6

   No auth, CORS *, rate-limited at 240/min/IP. This is the same data the listings widget uses.

6. Set up error handling

   400 = bad request (e.g. missing query param). 401 = missing/invalid API key. 404 = event/organizer not found. 429 = rate limit exceeded (check Retry-After). 5xx = server error, retry with backoff.

   See the error response reference for full examples.