List events

GET /rest/v1/events

Returns the events in the API key's organization, including drafts, private events, and invite-only events.

Requires the events:read scope. See Authentication for headers, rate limits, and the shared error format.

Query parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number. Must be ≥ 1.
limit	integer	No	50	Events per page. Must be from 1 to 100.
status	string	No	—	draft, published, or completed. cancelled is rejected.
branch_id	integer	No	—	Numeric id of a branch in this organization.
from	ISO 8601 datetime	No	—	Events whose start is greater than or equal to this value.
to	ISO 8601 datetime	No	—	Events whose start is less than or equal to this value.
updated_since	ISO 8601 datetime	No	—	Events updated at or after this timestamp.
search	string	No	—	Case-insensitive match on the event title. Maximum 200 characters.
sort	string	No	start_at	start_at, created_at, updated_at, or title.
order	string	No	asc	asc or desc.

status is derived from the event record:

Value	Meaning
draft	The event is still a draft.
published	The event is not a draft and its end date is still in the future.
completed	The event is not a draft and its end date is in the past.

Datetimes must include a time and a timezone, for example 2026-09-15T09:00:00Z.

Response 200

{
  "data": [
    {
      "id": "7f4c1b2e-8e9b-4e31-9c1d-123456789abc",
      "slug": "annual-conference-2026",
      "title": "Annual Conference 2026",
      "description": "Our annual organization conference.",
      "coverImage": "org-id/branch-id/event-id/cover.jpg",
      "coverImageUrl": "https://example.supabase.co/storage/v1/object/sign/event-covers/...",
      "type": "in-person",
      "visibility": "public",
      "isDraft": false,
      "startDate": "2026-09-15T09:00:00.000Z",
      "endDate": "2026-09-15T18:00:00.000Z",
      "timezone": "America/Monterrey",
      "meetingUrl": null,
      "allowGuestsToInvite": true,
      "showGuestList": true,
      "enableChat": true,
      "sendReminders": true,
      "generateWalletPass": true,
      "createdAt": "2026-06-01T14:30:00.000Z",
      "updatedAt": "2026-08-20T18:42:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

Field	Type	Nullable	Description
id	string	No	Event id.
slug	string	No	URL slug, unique inside the organization.
title	string	No	Event title.
description	string	Yes	Event description.
coverImage	string	No	Storage path of the cover image.
coverImageUrl	string	Yes	Signed URL for the cover. It expires after one hour. null when the URL cannot be created.
type	string	No	in-person, online, or hybrid.
visibility	string	No	public, private, or invite-only.
isDraft	boolean	No	Whether the event is still a draft.
startDate	string	No	Start time in ISO 8601.
endDate	string	No	End time in ISO 8601.
timezone	string	No	IANA timezone, for example America/Monterrey.
meetingUrl	string	Yes	Online meeting URL.
allowGuestsToInvite	boolean	No	Whether registered guests can invite others.
showGuestList	boolean	No	Whether attendees can see the guest list.
enableChat	boolean	No	Whether event chat is enabled.
sendReminders	boolean	No	Whether reminders are enabled.
generateWalletPass	boolean	No	Whether wallet passes are generated.
createdAt	string	No	Creation time in ISO 8601.
updatedAt	string	No	Last update time in ISO 8601.

pagination.total is the number of events that match the filters, not just the current page.

Errors

Shared codes are documented in Authentication. These are specific to this route:

400 invalid query

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "One or more query parameters are invalid.",
    "details": {
      "page": "Must be greater than or equal to 1.",
      "limit": "Must be between 1 and 100."
    }
  }
}

403 missing scope

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The API key does not have permission to access events."
  }
}

404 unknown branch

GET /rest/v1/events?branch_id=999999

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested branch was not found."
  }
}

branch_id is the numeric branch id, not a UUID. A branch that belongs to another organization is also not found.

405 other methods

POST /rest/v1/events

{
  "error": {
    "code": "METHOD_NOT_ALLOWED",
    "message": "Only GET requests are allowed for this resource."
  }
}

The response includes Allow: GET.