Events

Create and manage events, RSVPs, hosts, and invites from the browser

The events module covers the full events surface: creating and editing events (with inline cover/gallery image upload), the RSVP lifecycle, host and invite management, and the guest list. It maps directly to the Events API.

Because the JS SDK authenticates as an end user (bearer token), you never pass an actor userId — the server derives who is acting from the token. The only userId arguments are targets: the host or invitee on the host/invite functions.

Requires the events bundle. Space-scoping needs the spaces bundle; images need files-images; notifications need notifications.

---

createEvent

Creates an event. The logged-in user becomes the creator and first host. Pass cover and/or gallery to upload images inline (the request is sent as multipart/form-data).

const event = await sublay.events.createEvent({
  title: "Launch Party",
  type: "physical",
  startTime: "2026-09-01T18:00:00.000Z",
  venueName: "The Loft",
  address: "123 Main St, New York, NY",
  capacity: 100,
  cover: {
    file: coverBlob,
    options: { mode: "original-aspect", sizes: { full: 1600 }, format: "webp" },
  },
});

title · string · required

Event title. 1–300 characters.

startTime · string · required

ISO datetime when the event starts.

type · "online" | "physical" | "hybrid" · required

online requires url; physical requires address or location; hybrid requires both.

description · string

Optional description.

endTime · string

Optional ISO end datetime.

timezone · string

Optional IANA timezone.

url · string

Join/stream URL.

venueName · string

Venue name.

address · string

Street address.

location · { latitude: number; longitude: number }

Coordinates for proximity search.

spaceId · string

Scope to a space. Required when visibility is "members".

visibility · "public" | "members" | "invite"

Defaults to "public".

capacity · number

Max going RSVPs. Omit for unlimited.

allowMaybe · boolean

Allow "maybe" RSVPs. Defaults to true.

guestListVisible · boolean

Expose the named guest list. Defaults to true.

hostIds · string[]

Additional host user IDs (the logged-in user is auto-added).

metadata · object

Arbitrary key-value data. Up to 1 MB.

cover · { file: Blob | File; options: ImageOptions }

Single cover image plus its processing options. Requires the files-images bundle.

gallery · { files: (Blob | File)[]; options: ImageOptions }

Gallery image set (up to 10) plus shared processing options. Requires the files-images bundle.

Returns — Promise<Event>

---

fetchEvent

Fetches a single event by ID. Visibility and userRsvp are resolved from the logged-in user’s token.

const event = await sublay.events.fetchEvent({
  eventId: "evt_abc123",
  include: "user,space,files,userRsvp",
});

eventId · string · required

The event ID.

include · string

Comma-separated associations: "user", "space", "files", "userRsvp".

Returns — Promise<Event>

---

fetchManyEvents

Lists events with visibility enforced, plus filtering, sorting, geo, and free-text search. The myRsvp filter and userRsvp enrichment use the logged-in user.

const { data, pagination } = await sublay.events.fetchManyEvents({
  timeWindow: "upcoming",
  sortBy: "startTime",
  myRsvp: "going,maybe",
  include: "userRsvp",
  page: 1,
  limit: 20,
});

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Capped at 100.

sortBy · "startTime" | "going"

Sort field. Defaults to "startTime".

sortDir · "asc" | "desc"

Sort direction. Defaults to "asc".

timeWindow · "upcoming" | "ongoing" | "past"

Derived time window.

startsAfter · string

ISO datetime lower bound on startTime.

startsBefore · string

ISO datetime upper bound on startTime.

spaceId · string

Restrict to one space.

hostId · string

Only events this user hosts.

type · "online" | "physical" | "hybrid"

Filter by type.

status · "active" | "cancelled"

Defaults to "active".

myRsvp · string

Comma-separated statuses the logged-in user RSVP’d with, e.g. "going,maybe".

locationFilters · { latitude: string; longitude: string; radius: string }

Proximity filter (radius in meters).

titleFilters · { hasTitle?; includes?; doesNotInclude? }

Free-text filter on title.

descriptionFilters · { hasDescription?; includes?; doesNotInclude? }

Free-text filter on description.

include · string

Comma-separated associations.

Returns — Promise<PaginatedResponse<Event>>

---

updateEvent

Edits an event’s mutable fields. Host-only. hostIds, status, and spaceId are not editable here.

The JS SDK updateEvent accepts a flat JSON body. To curate images on update (replace the cover, append gallery photos, or remove images via removeImageIds), use the React SDK’s useUpdateEvent which supports inline multipart upload, or the underlying Update Event API directly.

const event = await sublay.events.updateEvent({
  eventId: "evt_abc123",
  capacity: 150,
  description: "Now with more space!",
});

eventId · string · required

The event ID.

title · string

New title.

description · string

New description.

startTime · string

New ISO start datetime.

endTime · string

New ISO end datetime.

timezone · string

New timezone.

type · "online" | "physical" | "hybrid"

New type.

url · string

New URL.

venueName · string

New venue name.

address · string

New address.

location · { latitude: number; longitude: number }

New coordinates.

visibility · "public" | "members" | "invite"

New visibility.

capacity · number

New capacity.

allowMaybe · boolean

Allow "maybe" RSVPs.

guestListVisible · boolean

Expose the guest list.

metadata · object

New metadata.

Returns — Promise<Event>

---

cancelEvent

Cancels an event (sets status: "cancelled"). Host-only. The event stays fetchable but rejects new RSVPs.

const event = await sublay.events.cancelEvent({ eventId: "evt_abc123" });

eventId · string · required

The event ID.

Returns — Promise<Event>

---

deleteEvent

Deletes an event (soft or hard per the project’s eventDeletion settings). Host-only.

await sublay.events.deleteEvent({ eventId: "evt_abc123" });

eventId · string · required

The event ID.

Returns — Promise<void>

---

setRsvp

Sets or changes the logged-in user’s RSVP. Transitions into going are capacity-checked.

const event = await sublay.events.setRsvp({
  eventId: "evt_abc123",
  status: "going",
});

eventId · string · required

The event ID.

status · "going" | "maybe" | "not_going" · required

The RSVP response.

Returns — Promise<Event> (with refreshed rsvpCounts)

---

withdrawRsvp

Removes the logged-in user’s RSVP. Idempotent.

const event = await sublay.events.withdrawRsvp({ eventId: "evt_abc123" });

eventId · string · required

The event ID.

Returns — Promise<Event>

---

addHost

Grants a user host privileges. Host-only. The userId is the target host.

const event = await sublay.events.addHost({
  eventId: "evt_abc123",
  userId: "usr_cohost",
});

eventId · string · required

The event ID.

userId · string · required

The user to grant host on the event.

Returns — Promise<Event>

---

removeHost

Revokes a user’s host privileges. Host-only. Rejected if it would leave the event with no hosts.

const event = await sublay.events.removeHost({
  eventId: "evt_abc123",
  userId: "usr_cohost",
});

eventId · string · required

The event ID.

userId · string · required

The host to remove.

Returns — Promise<Event>

---

addInvite

Invites a user to the event. Host-only. Idempotent. The userId is the target invitee.

const event = await sublay.events.addInvite({
  eventId: "evt_abc123",
  userId: "usr_guest",
});

eventId · string · required

The event ID.

userId · string · required

The user to invite (userId only — never a foreign ID).

Returns — Promise<Event>

---

removeInvite

Removes a user’s invite, revoking their access and dropping their RSVP. Host-only.

const event = await sublay.events.removeInvite({
  eventId: "evt_abc123",
  userId: "usr_guest",
});

eventId · string · required

The event ID.

userId · string · required

The invitee to remove.

Returns — Promise<Event>

---

fetchInvitees

Host-only invitee (guest) list. Returns paginated EventInvite records with the invited user populated.

const { data, pagination } = await sublay.events.fetchInvitees({
  eventId: "evt_abc123",
  page: 1,
  limit: 20,
});

eventId · string · required

The event ID.

page · number

Page number (1-indexed).

limit · number

Results per page. Capped at 100.

Returns — Promise<PaginatedResponse<EventInvite>>

---

fetchEventRsvps

Named RSVP (guest) list. Returns paginated EventRsvp records with the user populated. Visible to hosts always, to any viewer when guestListVisible is true. RSVP counts themselves are public via the event’s rsvpCounts.

const { data, pagination } = await sublay.events.fetchEventRsvps({
  eventId: "evt_abc123",
  status: "going,maybe",
  page: 1,
  limit: 20,
});

eventId · string · required

The event ID.

status · string

Comma-separated statuses to filter by, e.g. "going,maybe". Omit for all.

page · number

Page number (1-indexed).

limit · number

Results per page. Capped at 100.

Returns — Promise<PaginatedResponse<EventRsvp>>