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 in the admin panel and choose the Developers tab. Under API Settings, switch on Enable API Access and press Save. The key is shown once, beside a copy button, 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 schedule can record a sale it took elsewhere; 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. API Settings shows the expiry date under the key, and says so once the key has expired.
• Keys are stored hashed, so a lost key cannot be recovered. To rotate one, switch Enable API Access off and press Save, then switch it on and save again. The first save deletes the old key at once, after asking you to confirm, and the second issues a new one.
• Ten consecutive requests with the same invalid key block that key for 15 minutes with 423 API key temporarily blocked.
• A request with no X-API-Key header returns 401 API key is required, and an unknown key 401 Invalid API key.

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. It is counted per account and per schedule rather than per address, 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.

The Create Event throttle answers differently, because it is the framework's own: its 429 carries Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining headers, and its body holds a message in place of error. See Response Format for why that request needs an Accept header.

Response Format

Every endpoint answers in 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.

Ask for JSON

Send Accept: application/json with every request. A failure raised outside an endpoint is rendered by the framework, which picks its format from that header. Without it, the Create Event throttle, an unknown URL, an unknown venue_id and a server error come back as HTML pages, and the daily cap on new events comes back as a redirect. With it they are JSON, though the framework's own replies name the reason message, not error.

Record IDs

Schedules, events, sub-schedules, tickets and sales are all identified by an opaque encoded string such as "w4K8xU", never by the raw database number. Pass the same string back exactly as you received it. The examples on this page use readable stand-ins such as "evt123". Category IDs are the one exception: they are plain integers.

Dates and times

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, answering 200 with a confirmation in data.message. Rate limited to 5 codes per email per hour. An address that already belongs to a full account is rejected with a 422.

A new code replaces the one before it, and a code can be tried once: registering with a wrong verification_code uses it up, so request another.

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.

Both steps watch a hidden website honeypot field. Leave it out entirely: sending any value in it returns 422 Invalid request.

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. A successful login clears that count.

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.

The schedule object

List, Show, Create and Update Schedule return this shape. A field with nothing stored is null.

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.

What comes back

The reply is 201, and data holds the schedule object, generated subdomain included. This is the one place the object is returned for a schedule on the Free plan, so you can read what you made. Show Schedule answers 403 for it and List Schedules leaves it out until it is on Pro or Enterprise.

Hosted limits and verification

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 is not public until its contact email or phone number is verified: until then its pages answer visitors with a 404, so search engines never see them. Leave email out, or send your account's own address, and the schedule shares your account's verification; any other address is sent a verification link. A selfhosted install treats every new schedule as verified.

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, and any other field in the request is ignored. Requires owner or admin access and a Pro or Enterprise plan. Returns the schedule object.

On the hosted service, changing email clears the schedule's email verification and sends a verification link to the new address. Unless its phone number is verified, the schedule's pages stop being public until that link is followed.

Branding, images, layout and integrations are not exposed here. Edit those in the admin panel, on the Style, Settings and Integrations tabs of the schedule form.

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.

A schedule with a paid plan has its subscription cancelled first, at once and not at the end of the billing period. If that cancellation fails the reply is 502 and nothing is deleted, so the call is safe to repeat.

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. Each row is the event object.

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. An appointment booking, which List Events leaves out, can be read here by its ID.

The event object

List, Show, Create and Update Event and Upload Flyer return this shape, and so do the event.* webhooks. A field with nothing stored is null, except the few marked as present only in some cases.

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. On success it returns 201 with the event object. The schedule you post to becomes the event's owner, the one that sells its tickets and sees its sales, and no later request can change that.

Only the parameters listed here are read. Anything else at the top level of the body is dropped before the event is saved, so settings the API has no field for (sponsors, custom fields, promo codes, ticket options, seating) are made in the admin panel.

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

The recurrence fields only take effect in a request that also carries schedule_type: "recurring". Without it a new event is a single one, whatever else is sent.

Tickets, RSVP and add-ons

Every row you send in tickets, addons or event_parts is a new row on a new event. An id copied from a read of another event is ignored. On Update Event the same id is what addresses an existing row.

Payment method

The API stores any method from the list without checking that it is connected on the account or can settle the event's currency, so check both yourself: payfast only settles events priced in ZAR, and paypal only the currencies listed under Connecting PayPal, which is PayPal's own list minus the Hungarian forint, Japanese yen and New Taiwan dollar.

On create, omitting the field uses the installation's DEFAULT_PAYMENT_METHOD if one is set and is usable for the event's currency, falling back to cash; send null to mean cash explicitly. On update, omitting it leaves the stored value alone.

Agenda, venue and performers

What the schedule's type decides

The schedule you post to is always on the event, in the place its type gives it:

• Venue. It is the event's venue. venue_id and the name and address pair are overridden.
• Talent. It is the event's one performer. members is overridden, so other performers cannot be added through a talent schedule.
• Curator. The event is listed on it, and takes its venue and performers from the request.

Daily cap

The hosted service caps how many events one schedule, and one account across its schedules, may create in a day, as an anti-abuse measure. The shipped defaults are 500 a day per schedule on Pro, 1,000 on Enterprise and 100 during a trial, and three times that per account. A bulk import that trips the cap gets a 422 whose body carries "code": "event_create_limit" beside error, so it can stop at the first refusal and 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. Returns 200 with the event object.

The update runs through one of the event's schedules that you own or administer. If your account created the event but is neither owner nor admin of any of its schedules, the reply is 422 No schedule found for this event that you have access to.

What an update leaves alone

A field the request does not carry keeps its stored value. That covers the start time, the visibility flags, the recurrence, the payment method, the lists of ticket types, add-ons and agenda parts, the venue, the performers and the other schedules the event is listed on. The schedule that owns the event never changes.

What the API has no field for stays as the admin panel left it: promo codes, a ticket type's Max Per Order, custom fields and pass settings, the dates added to or skipped from a series, sponsors and the event's custom fields. An update that only renames an event changes its name.

A venue, performer or listing the request does not name also keeps its answer. One that had not yet accepted the event, or had turned it down, is still in that state afterwards: an update does not accept an event on a schedule's behalf. venue_id, venue_name and venue_address1 sent as null name no venue, so the event stays where it is.

• To change the recurrence, send schedule_type with the full set of recurrence fields, since one left out goes back to its default. Without schedule_type the stored frequency, interval and end rule are kept and those fields in the request are ignored; only days_of_week is still applied. schedule_type: "single" turns a recurring event into a single one.
• schedule moves the event to another sub-schedule. There is no way to take an event out of a sub-schedule through the API.
• A visibility flag takes effect as on create: Unlisted and Internal need Enterprise, and is_internal: true also makes the event a Draft.

What an update replaces or removes

Some schedules always stay on the event: the one the update runs through, the one that created it, and any that sit outside your account. The schedules an event is listed on cannot be named in a request, so the API neither adds nor removes one.

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.

An event that has sales is not deleted. The reply is 422 and nothing changes, whether those sales are paid, refunded or cancelled, because the sale records would go with the event. Cancel it in the admin panel instead, which keeps the records and lets you tell the buyers.

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

An appointment booking is the exception. It is cancelled, not deleted: the slot is freed, the booking and its sale are kept, the guest of a booking that was still live is emailed, and no webhook is sent. That reply is a bare {"message": "Appointment cancelled"} with no data wrapper.

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, remove 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. It returns the same id and name pairs, and 404 for a subdomain that does not exist.

List Sales

Returns a paginated list of sales, newest order first, each as the sale object. 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.

The list covers events your account created, events one of your schedules created, and events another schedule created that your venue or talent schedule has accepted. A curator schedule that only lists somebody else's event does not open that event's sales, here or on the other sale endpoints.

Show Sale

Returns a single sale by its encoded ID. Requires owner or admin access on the event's schedule and a Pro or Enterprise plan. A sale that exists but is not yours to read returns 403; a deleted or unknown one returns 404.

The sale object

Every sale endpoint except Delete Sale returns this shape, and so do the sale.* webhooks. There is no currency field: read the event's ticket_currency_code.

Guests, orders and amounts

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, and each ticket is checked individually, exactly as guest checkout does: a priced row needs the schedule to be on Pro or Enterprise, while a zero-price row sells on any plan. 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 reply is 201 with the sale object, secret included, since your key placed the sale.
• 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. A change that goes through returns 200 with the sale object in its new state.

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.

Refunds

For a Stripe or PayPal sale, refund sends the money back through the provider and then updates the status. Send an optional amount to return part of it; omit it and the whole remaining balance goes back. A partial refund leaves the sale paid, fires no webhook, and returns 200 with the message Partial refund sent.

Every other method - Invoice Ninja, Payfast, a payment link, cash, or a sale marked paid by hand - only records the refund and backs the amount out of your revenue figures, and it ignores amount: the whole sale is recorded as refunded. Issue the money in your payment provider, then call this to keep the two in step.

It does not work the other way round. A refund issued from the Stripe or PayPal dashboard is not reported back to Event Schedule, so the sale stays paid and its tickets keep scanning. Refund through this endpoint or the Sales page instead.

A refund the gateway refuses returns 422 and leaves the sale paid. A refund whose outcome could not be confirmed returns 409: nothing is retried automatically, because retrying a refund that may already have gone through is how one refund becomes two. Check it against your provider before acting.

Send an idempotency_key of your own, up to 64 letters, digits, _, ., : or -, to make retrying safe. A repeat carrying the same key returns the first attempt's outcome instead of issuing a second refund, and a repeat sent while the first is still running returns 409. Without a key, a retried request is a second refund.

A payment plan is refunded in full only: sending amount for one returns 422. Each collected payment goes back separately, and an attempt that stops partway can be repeated to return the rest.

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.

Deleting moves no money and sends no webhook, not even sale.cancelled. To give a buyer their money back, refund the sale first.

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.

Every row carries the fields in the example. What follows them depends on the type: a comment has comment, a photo has photo_url, and a video has youtube_url and embed_url. event_part_id is the agenda part the submission was made on, or null.

Error Handling

The API uses standard HTTP status codes, and every endpoint returns the reason as a JSON error string. The few failures raised outside an endpoint carry message in its place, and need an Accept header to be JSON at all: see Ask for JSON.

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.