Overview

Read-only JSON endpoints served from your Basker site for use in themes and embedded widgets

The FrontStage API is the read-only JSON surface served from your Basker site. Themes use it for calendars, search-as-you-type, and widgets that need live data fetched from the browser. A request made from a theme uses the same origin as the site and needs no API key.

When to use it

Live data inside a theme. Examples: a calendar widget that paginates by month, an event search box, an upcoming-events feed that updates without a redeploy.
Public-data integrations where the Partners API is more than you need.

For server-to-server integrations, large data syncs, or anything that changes content, use the Partners API instead.

How it differs from the Partners API

	FrontStage API	Partners API
Host	Your Basker site (`{your-domain}/api/...`)	`https://api.basker.app/partners/...`
Auth	None: public content only	API key required
Methods	`GET` only	Authenticated integration endpoints
Tenant context	Inferred from the requested domain	Explicit in the URL path
Caching	Can be served from the edge cache	Per-request, not edge-cached
Filtering	Date range, relationship, and custom attribute filters on the list endpoints	The same filter syntax, plus write operations
Scope	Public content intended for site visitors	Depends on the API key and endpoint

Conventions

Base URL. Replace {your-domain} in examples with the primary domain of your Basker site. For example, use https://remarkable-theatre.example.
.json suffix. Content list endpoints accept both forms (/api/event-instances.json and /api/event-instances). Detail endpoints and custom-object routes use the bare path shown in their reference pages.
Response shape. List endpoints return paginated JSON: a docs array plus pagination metadata (totalDocs, page, limit, totalPages, hasNextPage, hasPrevPage, nextPage, prevPage, pagingCounter).
Pagination. Use ?page= and ?limit= query parameters. Defaults vary by endpoint. The maximum page is 1000 and the maximum limit is 500.
Filtering. The events, event instances, posts, organizations, and smart collection lists accept filters on dates, relationships, and custom attributes. See Filtering.
Field selection. Event and event-instance lists accept ?select= to narrow their fields.
Relationship expansion. Event and event-instance lists accept ?depth= from 0 to 5. Custom data settings can keep selected relationships as summaries or IDs.
Locale. Without a locale, translated fields come back in your site's default language. Add ?locale=<code> (for example ?locale=cy) to any /api/ endpoint to get another language the site offers. An unknown or unavailable code returns a 400.

Filtering at the edge

Basker caches a filtered request the same way it caches an unfiltered one. A theme can ask for one month, at one venue, in two categories, and still read the response from the edge cache:

/api/event-instances.json
  ?where[startDate][greater_than_equal]=2026-10-01T00:00:00.000Z
  &where[startDate][less_than]=2026-11-01T00:00:00.000Z
  &venueId=000000000000000000000003
  &attributeWhere[custom.category][in]=bookbug,family-fun

This matters for a headless site. The pages can live anywhere and query the filters they need. Basker narrows the list, so the browser does not have to. Filtering covers the parameters, the operators, and the limits that no filter can cross.

Reference

Content endpoints: list and fetch any content type: events, pages, posts, blogs, people, venues, organizations, seasons, series, works, and smart collections. Also covers the shared filter syntax.
Event instances: list and fetch upcoming or past performances, with date filtering and ticketing data.
Search: full-text query across all your published content at once.
Custom objects: read the custom object definitions on your site and their instances.

Search and single-record responses have their own response shapes. Follow the examples on each reference page rather than assuming that every route is paginated.