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. Free schedules are filtered out of the list endpoints and return 403 API usage is limited to Pro accounts on the single-record endpoints. There are two deliberate exceptions, so a new account can bootstrap and a free schedule can still take a door sale: Create Schedule and Create Sale. 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, over a rolling minute:

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:

Every one of these returns 429 with an error message when the limit is hit. There are no rate limit headers on the response, so back off on the status code.

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, and the write endpoints put their confirmation message in meta.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

Create a new account and receive an API key. No verification code is involved on a selfhosted install, and /api/register/send-code returns a 400 there.

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. This is the one write endpoint with no plan gate, so a new account can bootstrap itself. Every other endpoint then needs that schedule to be on a Pro or Enterprise plan, 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.

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: 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

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. 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. This is one of the two endpoints with no Pro gate, so a free schedule can use it within its monthly paid-ticket allowance; the resulting sale will not appear in List Sales until the schedule is on a paid plan.

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.
• 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. Which actions are available depends on where the sale is now; an action the current status does not allow returns a 422 naming both.

Cancelling or refunding releases the seats back into stock and notifies anyone on the waitlist for that date. For a multi-event order, act on the primary sale: a non-primary row returns 403, and the change cascades to the rest of the order for you.

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 primary sale of a multi-event order deletes the whole order. A non-primary 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.