Muzeek Events API

A REST API for reading and managing events in your Muzeek account from any server-side application.

The Events API is the first of several resource APIs available to developers. Additional APIs for bookings, venues, tours and settlements will be published here as they become available. If you have a use case that isn't covered yet, we'd love to hear from you at.

Base URL

All endpoints are served from:

https://muzeek.ai/api

Requests and responses are JSON. All timestamps are ISO 8601 in UTC. All resource identifiers exposed through the external API are UUIDs.

Authentication

Every request to the Muzeek API is authenticated with an API key, passed as the X-API-Key HTTP header.

curl https://muzeek.ai/api/events \
  -H "X-API-Key: mzk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Generating a key. In your Muzeek workspace, open Settings → API, create an API client, and generate a key. We recommend granting each key the minimum set of scopes it needs.

One-time display. Your key is shown only once at the moment it is created. Copy it to your secret manager straight away — for your security, Muzeek cannot display or recover it again.

Rotation & revocation. You can rotate or revoke keys at any time from the same screen. Revoked keys stop working immediately.

Never send keys in the URL. Always pass keys in the X-API-Key header. Keys sent as query-string parameters can leak through server logs, browser history, caches, and Referer headers, so the API rejects them.

Permission scopes

Each API key is granted one or more scopes. Events endpoints require one of:

read:eventsscope

Required for GET /api/events and GET /api/events/:id.

write:eventsscope

Required for POST, PUT and DELETE against /api/events. Covers delete — there is no separate delete:events scope.

A key with the wildcard * scope has full access to every endpoint. We recommend issuing narrowly-scoped keys per integration.

Pagination

List endpoints accept page and limit query parameters. The default page size is 10; the maximum is 100. Responses return both the requested slice and pagination metadata:

{
  "data": [ /* array of events */ ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 247,
    "totalPages": 25
  }
}

Including related data

By default, event responses contain only the event record itself. Use the include query parameter to embed related resources in the response.

venueinclude

Basic venue information (id, name).

venue.fullinclude

Full venue details including address, city, state, country.

tourinclude

Basic tour information (id, name).

tour.fullinclude

Full tour details including type and status.

accountinclude

Basic account information (id, name).

account.fullinclude

Full account details (id, name, slug, imageUrl).

Combine values with commas, e.g. ?include=venue.full,tour,account.

Event type and status

Create and update payloads use the JSON fields eventType and status.

Defaults on create

If you omit eventType, the event is created as type show.
If you omit status, the event is created with status private (the initial lifecycle state before public on-sale messaging).

Setting `status` values

Use a lowercase string. Allowed status values are:

private
off_sale
announced
pre_sale
on_sale
sold_out
allocation_full
event_ended
cancelled

Set status on create or update when you need a lifecycle state other than the default (for example announced or on_sale).

Setting `eventType` values

Use a lowercase string. Allowed type values are:

show
travel
day_off

Custom event types: You can configure custom event type keys. Currently creating or editing custom event types for your account is only available in the Muzeek web application (Settings), not through the API.

Errors

All errors use a consistent JSON envelope and the HTTP status code reflects the error class.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key"
  }
}

MISSING_API_KEY401

The X-API-Key header was not present.

INVALID_API_KEY401

The supplied key was unknown, expired, or revoked.

FORBIDDEN403

The key is valid but does not have the scope required for this endpoint.

VALIDATION_ERROR400

Request body or query parameters failed schema validation.

NOT_FOUND404

The requested resource does not exist in your account.

RATE_LIMIT_EXCEEDED429

You have sent too many requests in a short period. Respect the X-RateLimit-Reset header.

Rate limits

Every API key is rate limited on a rolling hourly window:

1,000 requests per hour across read endpoints (GET)
200 requests per hour across write endpoints (POST, PUT, DELETE)

These are our current limits. If you have a use case that needs more headroom, get in touch.

Every response includes the following headers so your client can pace itself:

X-RateLimit-Limitinteger

The maximum number of requests allowed in the current window.

X-RateLimit-Remaininginteger

The number of requests remaining in the current window.

X-RateLimit-Resetunix timestamp

The time at which the current window resets.

Events API

Events are the core unit of the Muzeek data model — a scheduled occurrence (show, travel day, day off, etc.) that optionally lives on a tour and at a venue. The Events API lets you list, retrieve, create, update and delete events.

If your account manages other accounts via a roster (for example, an agent or manager with an artist roster), you can also create events for a roster member by passing their account UUID as forAccountId on create. See Create an event.

GET

/api/events

read:events

List events in the authenticated account.

Query parameters

pageinteger

Page number. Defaults to 1.

limitinteger

Items per page. Defaults to 10, max 100.

sortBystring

One of startDate, title, createdAt. Defaults to startDate.

sortOrderstring

asc or desc. Defaults to desc.

searchstring

Free-text search across event title.

typesstring[]

Filter by event type (repeatable). Example: ?types=show&types=travel.

statusesstring[]

Filter by status (repeatable). Example: ?statuses=private&statuses=announced.

startDateISO 8601

Only return events whose startDate is on or after this value.

endDateISO 8601

Only return events whose startDate is on or before this value.

includestring

Comma-separated list. See the Includes section above.

Example

curl "https://muzeek.ai/api/events?limit=5&include=venue,tour" \
  -H "X-API-Key: $MUZEEK_API_KEY"

GET

/api/events/:id

read:events

Retrieve a single event by its UUID.

Path parameters

iduuid

required

The event UUID.

Query parameters

includestring

Comma-separated list. See Includes.

Example request

curl "https://muzeek.ai/api/events/123e4567-e89b-12d3-a456-426614174000?include=venue,tour" \
  -H "X-API-Key: $MUZEEK_API_KEY"

Example response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Summer Showcase",
  "description": null,
  "eventType": "show",
  "startDate": "2026-08-15T20:00:00.000Z",
  "endDate": "2026-08-15T23:00:00.000Z",
  "timezone": "Europe/London",
  "isAllDay": false,
  "isPublished": true,
  "status": "announced",
  "capacity": 500,
  "imageUrl": null,
  "venueId": "6a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "tourId": null,
  "createdAt": "2026-04-01T10:15:30.000Z",
  "updatedAt": "2026-04-02T09:00:00.000Z",
  "venue": {
    "id": "6a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
    "name": "The Lexington"
  },
  "tour": null
}

Fields omitted above that you may also see: description, capacity, imageUrl, status, currencyCode, and location fields (locationName, locationAddress, …). Fields that are unset come back as null; optional objects like venue and tour are only present when requested via include.

POST

/api/events

write:events

Create a new event in the authenticated account.

Request body

titlestring

required

Event title.

startDateISO 8601

required

Event start in UTC.

endDateISO 8601

required

Event end in UTC.

timezoneIANA timezone

required

E.g. "Europe/London", "America/Los_Angeles".

isAllDayboolean

required

Whether this is an all-day event.

eventTypestring

Event type. Defaults to show. See Event type and status.

venueIduuid

Venue UUID. Mutually exclusive with venueContactId.

tourIduuid

Tour UUID.

capacityinteger

Positive integer capacity.

imageUrlhttps url

Hero image. Pass null or empty string to clear.

isPublishedboolean

Whether the event is publicly visible.

statusstring

Event lifecycle status. Defaults to private. See Event type and status.

forAccountIduuid

Optional. Beneficiary roster account — create the event for a member of your roster. The caller must be an active roster owner of this account, otherwise the request returns 403 FORBIDDEN. Omit or pass your own account UUID to create on your own account.

Example

curl -X POST https://muzeek.ai/api/events \
  -H "X-API-Key: $MUZEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer Showcase",
    "eventType": "show",
    "startDate": "2026-08-15T20:00:00Z",
    "endDate":   "2026-08-15T23:00:00Z",
    "timezone":  "Europe/London",
    "isAllDay":  false,
    "venueId":   "123e4567-e89b-12d3-a456-426614174000"
  }'

Creating for a roster member

If your account manages other accounts via a roster (e.g. an agent or manager with an artist roster), pass the member's account UUID as forAccountId. The event is created on the member's account and attributed to you as the creator. The scope required is still write:events; the roster relationship itself is the authorisation boundary.

curl -X POST https://muzeek.ai/api/events \
  -H "X-API-Key: $MUZEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Roster Member Show",
    "eventType": "show",
    "startDate": "2026-08-15T20:00:00Z",
    "endDate":   "2026-08-15T23:00:00Z",
    "timezone":  "Europe/London",
    "isAllDay":  false,
    "forAccountId": "9f8e7d6c-5b4a-3210-fedc-ba9876543210"
  }'

Note:the member's account UUID is not currently listable via the API — retrieve it from the Muzeek app and pass it through your integration as configuration.

PUT

/api/events/:id

write:events

Partial update. Only the fields you send are changed.

Example

curl -X PUT https://muzeek.ai/api/events/123e4567-e89b-12d3-a456-426614174000 \
  -H "X-API-Key: $MUZEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer Showcase (rescheduled)",
    "startDate": "2026-08-16T20:00:00Z",
    "endDate":   "2026-08-16T23:00:00Z"
  }'

DELETE

/api/events/:id

write:events

Permanently remove an event from the account.

Example

curl -X DELETE https://muzeek.ai/api/events/123e4567-e89b-12d3-a456-426614174000 \
  -H "X-API-Key: $MUZEEK_API_KEY"

DELETE is covered by the write:events scope. There is no separate delete:events scope.

Building something with Muzeek?

We love hearing what developers are building on top of Muzeek, and we prioritise new endpoints based on real customer demand. Contact us and tell us what you have in mind.

Muzeek Events API

Base URL

Authentication

Permission scopes

Pagination

Including related data

Event type and status

Defaults on create

Setting status values

Setting eventType values

Errors

Rate limits

Events API

Query parameters

Example

Path parameters

Query parameters

Example request

Example response

Request body

Example

Creating for a roster member

Example

Example

Setting `status` values

Setting `eventType` values