API Reference

Authentication

Every endpoint except Register and Login authenticates with an API key sent in the X-API-Key header. There are two ways to get one:

• Open Settings, go to API Settings and turn on Enable API Access. The key is shown once, so copy it before you leave the page. See Account Settings.
• Call the Register or Login endpoints, which return a key in the response body (useful for AI agents and scripted setup).

A key belongs to a user account, not to one schedule. It can reach every schedule where you are the owner or an admin, and nothing else. Followers and members cannot be used to authorise API calls.

Plan requirement

On the hosted service, a schedule must be on a Pro or Enterprise plan for the API to see it. The schedule, event, sale and feedback lists leave out anything that belongs only to free schedules, and single-record reads and writes on a free schedule return 403 API usage is limited to Pro accounts. A few endpoints carry no plan check at all: Create Schedule, so a new account can bootstrap; Delete Schedule, so an owner can always retire one; Create Sale, so a free schedule can still record a sale within its ticket allowance; both List Categories routes; and List Fan Content. A new schedule starts on the Free plan with no trial. Selfhosted installs resolve to Enterprise, so every endpoint is available there.

Key lifetime and rotation

• A key expires one year after it is issued. After that every request returns 401 API key expired.
• Keys are stored hashed, so a lost key cannot be recovered. To rotate one, turn Enable API Access off and back on in Settings. That revokes the old key immediately and issues a new one.
• Ten consecutive requests with the same invalid key block that key for 15 minutes with 423 API key temporarily blocked.

Rate Limits

Authenticated requests are counted per IP address, in separate read and write buckets. Every key calling from the same address shares the same two buckets, and a request that fails authentication is not counted:

Each bucket counts in a fixed one-minute window that opens with its first counted request. When that minute is up the count starts again from zero, so a client that makes no more than 300 reads and 30 writes in any one window is never refused, however long it runs.

Create Event carries a second throttle of 30 requests per minute on top of the write bucket, so a bulk import should pace itself well below that.

Unauthenticated endpoints

The auth endpoints are limited separately, because they run before any key exists:

The read and write buckets and the three endpoints above all answer 429 with an error message when the limit is hit. A 429 from a read or write bucket also carries a Retry-After header with the number of seconds until that bucket's window resets. The three auth endpoints send no rate limit headers, so back off on the status code there.

Response Format

Every response is JSON. Successful responses wrap the result in a data property: an object for single-record endpoints, an array for list endpoints. List endpoints add a meta object with the pagination counters. Event and sale writes and Upload Flyer put a confirmation in meta.message, while the delete endpoints return theirs as data.message.

Failures return an error string. A validation failure adds an errors object keyed by field name, each holding an array of messages.

Pagination

Every list endpoint takes the same two query parameters:

The meta object

Every list response returns the same seven counters. Keep requesting page + 1 until it equals last_page.

Register

Registration takes two steps: send a verification code to the email address, then register with the code.

Step 1: Send Verification Code

No authentication required. Takes a single email parameter and emails a 6-digit code that is valid for 10 minutes. Rate limited to 5 codes per email per hour. An address that already belongs to a full account is rejected with a 422.

Step 2: Register

No authentication required. Rate limited to 3 registrations per IP per hour. On success it returns 201 with an API key that is valid for one year, and the account's email is treated as verified.

The endpoint also watches a hidden website honeypot field. Leave it out entirely: sending any value in it returns a 422.

Login

No authentication required. Exchanges an email and password for an API key valid for one year.

Two other refusals to handle: an account with two-factor authentication enabled returns 403 and must generate its key from Settings instead, and a wrong email or password returns 401 and counts toward the 5-per-15-minute limit.

List Schedules

Returns a paginated list of the schedules where you are the owner or an admin. Deleted schedules are excluded, and on the hosted service so are schedules that are not on a Pro or Enterprise plan. Each row carries the schedule's sub-schedules in a groups array.

Show Schedule

Returns a single schedule by subdomain, including its sub-schedules in a groups array. You must be the owner or an admin of it, otherwise the response is 404. A schedule that is not on a Pro or Enterprise plan returns 403.

Create Schedule

Create a new schedule. There is no plan gate here, so a new account can bootstrap itself, but the schedule starts on the Free plan with no trial and most other endpoints need it on Pro or Enterprise, so on the hosted service subscribe before you start pushing events. You are attached to the new schedule as its owner, and it becomes your default schedule if you had none.

On the hosted service one account may own up to 50 schedules. Beyond that the endpoint returns a 422.

On the hosted service a schedule stays out of search engines until its contact email or phone number is verified. Send your account's own email address and the schedule shares your account's verification; any other address is sent a verification link.

Update Schedule

Update a schedule. Include only the fields you want to change; anything you omit is left alone. Takes the same fields as Create Schedule apart from type: neither the schedule type nor the subdomain can be changed through the API. Requires owner or admin access and a Pro or Enterprise plan.

Branding, images, layout and integrations are not exposed here. Edit those in the admin panel, under the Style, Settings and Integrations sections of the schedule editor.

Delete Schedule

Retire a schedule. Requires owner access but no plan: an admin gets a 404. There is no undo through the API.

The schedule is flagged as deleted and stops appearing anywhere, and the call also:

• Deletes its profile, header and background images from storage
• Deletes its analytics history (page views, referrers and appearances)
• Tears down its Google Calendar and Outlook sync subscriptions
• Cancels any running boost campaign and refunds it where money is owed
• Emails the schedule's members to tell them it was deleted
• Frees its subdomain for anyone to register, keeping the old name on record so a platform admin can restore the schedule

Events are not swept up automatically. The exception is a talent schedule: an event whose only member was that schedule is deleted with it, so nothing is left orphaned.

List Sub-Schedules

List every sub-schedule on a schedule, returning id, name, slug and color for each. Requires owner or admin access and a Pro or Enterprise plan. The response is not paginated.

Sub-schedules group and colour-code events so visitors can filter your calendar. They do not control who can see an event: use the visibility flags on Create Event for that.

Create Sub-Schedule

Create a sub-schedule on a schedule. Requires owner or admin access and a Pro or Enterprise plan. The slug is generated from the name and is what you pass as the schedule parameter when creating an event.

If the schedule has a translation language set that differs from its own language, the name is machine-translated into it and the slug is built from the translated name, so read the slug back from the response rather than deriving it yourself.

Update Sub-Schedule

Update a sub-schedule's name or colour; send only the one you want to change. Requires owner or admin access and a Pro or Enterprise plan. Changing the name regenerates the slug, which changes the value events must pass in schedule, so re-read it from the response.

Delete Sub-Schedule

Delete a sub-schedule. Events assigned to it are kept and simply lose the assignment. Requires owner or admin access and a Pro or Enterprise plan. Pass the encoded sub-schedule id from List Sub-Schedules.

List Events

Returns a paginated list of events on the schedules where you are the owner or an admin, newest start date first. On the hosted service an event is only listed if at least one of its schedules is on a Pro or Enterprise plan. Appointment bookings are never returned here; they are not calendar events.

Drafts, internal and unlisted events are all included, so check is_draft, is_internal and is_private before republishing a row on a public site.

Show Event

Returns a single event by its encoded ID, including its ticket types, add-ons, members, agenda parts, venue, recurring configuration and visibility flags. Requires owner or admin access on one of the event's schedules, and a Pro or Enterprise plan.

Create Event

Create an event on the schedule identified by {subdomain}. Requires owner or admin access on that schedule and a Pro or Enterprise plan. This endpoint carries its own throttle of 30 requests per minute in addition to the write bucket.

Core fields

Visibility

Send no visibility flag at all and the event inherits the schedule's default for new events. Unlisted and Internal need an Enterprise plan Enterprise - Requires the Enterprise plan ; on any lower plan they are stripped and the event is saved as a Draft so it never publishes by accident.

The draft default is applied even to a partial request that omits is_draft, so on a drafts-by-default schedule you must send is_draft: false to publish straight away.

Recurrence

Tickets, RSVP and add-ons

Agenda, venue and performers

The hosted service also applies a generous daily cap on how many events one schedule or one account may create, as an anti-abuse measure. A bulk import that trips it gets a 422 and can resume the next day. Selfhosted installs have no cap.

Update Event

Update an event by its encoded ID. Takes the same parameters as Create Event, and supports partial updates: send only the fields you want to change. Requires owner or admin access on one of the event's schedules and a Pro or Enterprise plan.

Omitting a collection leaves it alone. The start time, recurring configuration, ticket types, add-ons and agenda parts are all carried over from the stored event when the request does not mention them.

Delete Event

Permanently delete an event. Requires owner or admin access on one of its schedules and a Pro or Enterprise plan. There is no undo, so hide the event with is_draft instead if you may want it back.

Deleting also removes the synced copy from any connected Google Calendar, Outlook calendar and CalDAV calendar, cancels any running boost campaign, and deletes its sponsor logo files. Unless the event was a draft, an event.deleted webhook is sent with the event's final state.

Upload Flyer

Set the flyer image for an event. Send it as multipart/form-data in a flyer_image field, not as JSON. Requires owner or admin access on one of the event's schedules and a Pro or Enterprise plan.

The response is the full event record, so you can read the new flyer_image_url straight back from data. There is no endpoint for removing a flyer.

List Categories

Returns the built-in event categories with their integer IDs and English names. Pass an id as category_id when creating or updating an event. The list is not paginated.

Categories for one schedule

A schedule can rename, hide or add categories of its own, and category_id is validated against that effective list rather than the global one. Call this variant to get the exact set a given schedule will accept, and use it whenever the schedule has customised its categories.

List Sales

Returns a paginated list of sales on events you own or administer, newest order first. Deleted sales are excluded, and on the hosted service so are sales on schedules that are not Pro or Enterprise. RSVP registrations appear here too, as zero-value paid sales.

Show Sale

Returns a single sale by its encoded ID, including a row per ticket type and add-on with ticket_id, type, quantity, price and the is_addon and is_pass flags. On an event with allocated seating each row also carries seats, the labels of the seats the sale holds. The sale's secret, the token that opens the buyer's ticket page and QR code, is included only when the key belongs to the account that created the event or placed the sale. Requires owner or admin access on the event's schedule and a Pro or Enterprise plan.

An order bought for several named guests is stored as one row per guest, all sharing a group_id. The row with is_primary set to true holds the totals for the whole order; the other rows report zero so you do not double-count when you add them up. Every row in a group belongs to the same event.

A purchase that covered several events shares an order_id instead, one row per event, with is_order_primary on the anchoring row. The two nest: a leg of an order can itself be split across named guests, so a row may carry both.

payment_amount is what the buyer agreed to pay, not what has been collected. The two differ for a sale bought on an installment plan: the sale reads paid with the full total from the first payment onwards, because the ticket is issued then, while the rest arrives over the following months. Reconcile against Stripe rather than against this field if you are counting money in the bank.

Create Sale

Record a sale against an event, for example when someone paid you at the door or through a channel Event Schedule does not handle. The event must have ticketing enabled and still be selling. There is no Pro gate here: on a free schedule the sale is held to the same monthly paid-ticket allowance as checkout, which never refuses an event paid in cash or one starting within 48 hours. Until the schedule is on a paid plan, though, the sale does not appear in List Sales, and Show Sale and Update Sale Status return 403 for it, so mark it paid from the Sales page instead.

What happens on success

• The sale is created as unpaid. You cannot set the status from the request; use Update Sale Status once you have the money.
• A sale whose total comes to zero is marked paid immediately.
• Any volume discount configured on the ticket type is applied to the total.
• On an event with allocated seating, the best available seats are assigned, since this path has no seat picker.
• A sale.created webhook fires, plus sale.paid for a zero-total sale.

Inventory is checked under a lock, so you cannot oversell through this endpoint. Common 422 replies are a past event or occurrence, a ticket whose sales window has not opened or has closed, and a quantity larger than the remaining stock, which reports how many are left.

Update Sale Status

Move a sale to a new status by sending an action. Requires owner or admin access on the event's schedule and a Pro or Enterprise plan. Which actions are available depends on where the sale is now; an action the current status does not allow returns a 422 naming both. refund asks one thing more, because the money leaves the event creator's account: the schedule you act through must have created the event or accepted its place on it, or the reply is 403.

Cancelling or fully refunding releases the seats back into stock and notifies anyone on the waitlist for that date; a partial refund does neither. A named guest's row inside a group_id returns 403: act on the group's primary row (is_primary), which carries the change to every guest. On a multi-event order the row with is_order_primary carries it to every leg, while acting on any other leg changes only that leg and its own guests.

Delete Sale

Remove a sale from your records. It is cancelled first, so its seats return to stock, and then flagged as deleted: it stops appearing in List Sales and in the admin panel, and Show Sale returns 404 for it. Requires owner or admin access on the event's schedule and a Pro or Enterprise plan.

Deleting the row with is_order_primary deletes the whole multi-event order, and deleting a group's primary row deletes its guests with it. A named guest's row returns 403.

List Feedback

Returns a paginated list of post-event feedback, meaning the star ratings and comments attendees leave after an event, for schedules you own or administer. Newest first. Read only: there is no endpoint for creating or deleting feedback.

Only feedback attached to a paid, undeleted sale is returned, which is the same rule the guest page applies, so a cancelled or refunded order's rating never shows up here. On the hosted service the schedule must be on a Pro or Enterprise plan, since collecting feedback is itself a Pro feature.

List Fan Content

Returns fan comments, photos and videos submitted on events for schedules you own or administer, all three kinds merged into one feed, newest first. Approved items only by default, which is what you want when displaying them on an external site. Submitter email addresses are never included. Read only: approve and reject submissions in the admin panel.

Each kind of submission has its own id sequence, so an id is only unique within a type. Key on the two together when storing rows from this feed.

Error Handling

The API uses standard HTTP status codes and always returns the reason as a JSON error string.

A 422 covers two different things. A schema problem carries an errors object and is worth surfacing field by field; a business refusal carries only error and reads as a sentence. Check for errors before assuming its shape.