Ctrlk

Events

Event management endpoints for creating, updating, and querying events. Events can be one-time or recurring, and can take place in Genesis City or Worlds.

List events

get
/events

Retrieves a list of events based on various filters. By default returns active events (current and future) sorted by start date ascending. Supports filtering by location, creator, categories, schedules, and more.

When called with the service bearer token (Authorization: Bearer ...), the response includes pending and rejected rows and the approved / rejected query parameters are honored as explicit state filters.

Authorizations
AuthorizationstringOptional
Bearer authentication header of the form Bearer <token>.
Query parameters
approvedbooleanOptional

Admin-only. Filter by approval state (only applied with bearer auth).

rejectedbooleanOptional

Admin-only. Filter by rejection state (only applied with bearer auth).

limitinteger · min: 1 · max: 1000Optional

Maximum number of events to return

Default: 100
offsetintegerOptional

Number of events to skip (for pagination)

Default: 0
liststring · enumOptional

Filter events by time range.

  • active (default): current and future events
  • all: every event without time restriction
  • live: events currently running
  • upcoming: future events only
  • highlight: deprecated alias for list=active&highlighted=true
Default: activePossible values:
highlightedbooleanOptional

When true, return only events flagged as highlighted. Combine with list to scope by time range.

ownerbooleanOptional

Return events authored by the authenticated user across all statuses (approved, pending, and rejected). Requires signed-fetch authentication; unauthenticated callers receive 401. Overrides the creator filter when set.

positionstringOptional

Filter events at a specific Genesis City position (format "x,y")

Example: 20,30Pattern: ^-?\d{1,3},-?\d{1,3}$
positionsstring[] · max: 1000Optional

Filter events at multiple positions

estate_idstringOptional

Filter events by Genesis City estate ID

creatorstringOptional

Filter events by creator's Ethereum address

Example: 0x1234567890123456789012345678901234567890Pattern: ^0x[a-fA-F0-9]{40}$
only_attendeebooleanOptional

Show only events the authenticated user is attending (requires authentication)

searchstring · min: 3Optional

Full-text search in event name and description (minimum 3 characters)

schedulestring · uuidOptional

Filter events by schedule ID

worldbooleanOptional

Filter events by location type (true=Worlds, false=Genesis City, null=all)

world_namesstring[] · min: 1Optional

Filter events by World names (format "name.dcl.eth")

places_idsstring · uuid[] · max: 100Optional

Filter events by place IDs

community_idstring · uuidOptional

Filter events by community ID

orderstring · enumOptional

Sort order by start date

Default: ascPossible values:
fromstring · date-timeOptional

Start of date range filter (ISO 8601 format). Returns events with next_start_at >= from. Use with 'to' to filter events within a specific date range.

Example: 2026-01-01T00:00:00Z
tostring · date-timeOptional

End of date range filter (ISO 8601 format). Returns events with next_start_at < to. Use with 'from' to filter events within a specific date range.

Example: 2026-01-31T23:59:59Z
with_connected_usersbooleanOptional

Include the list of connected user wallet addresses for each event location. When enabled, each event in the response will include a connected_addresses array containing wallet addresses of users currently at the event's location. Data is cached for 5 minutes.

Default: false
Responses
200

List of events

application/json
okbooleanOptionalExample: true
get
/events

Create a new event

post
/events

Creates a new event. Requires authentication. Events are created in pending status and require approval unless the user has special permissions.

Body

Schema for creating a new event

namestring · min: 1 · max: 150Required

Event name

descriptionstring · max: 5000 · nullableOptional

Event description in Markdown

imagestring · uri · nullableOptional

URL to event poster (horizontal format)

image_verticalstring · uri · nullableOptional

URL to event poster image in vertical/portrait format

start_atstring · date-timeRequired

Event start date and time

durationinteger · max: 86400000Required

Event duration in milliseconds (max 24 hours)

all_daybooleanOptionalDefault: false
xinteger · min: -170 · max: 170Required

X coordinate in Genesis City

yinteger · min: -170 · max: 170Required

Y coordinate in Genesis City

serverstring · nullableOptional

Preferred realm/server

urlstring · uriOptional

Custom jump-in URL

contactstring · max: 100 · nullableOptional

Contact information

detailsstring · max: 5000 · nullableOptional

Additional details

categoriesstring[] · max: 1 · nullableOptional

Event categories (max 1)

schedulesstring · uuid[] · nullableOptional

Schedule IDs (admin only)

worldbooleanOptional

Whether event is in a World

Default: false
community_idstring · uuid · nullableOptional

Associated community ID

recurrentbooleanOptionalDefault: false
recurrent_frequencystring · enum · nullableOptionalPossible values:
recurrent_intervalintegerOptional
recurrent_countinteger · nullableOptional
recurrent_untilstring · date-time · nullableOptional
recurrent_weekday_maskintegerOptional
recurrent_month_maskintegerOptional
recurrent_setposinteger · min: -1 · nullableOptional
recurrent_monthdayinteger · nullableOptional
approvedbooleanOptional

Self-approve (requires permission)

rejectedbooleanOptional
highlightedbooleanOptional

Highlight event (admin only)

trendingbooleanOptional

Mark as trending (admin only)

Responses
200

Event created successfully

application/json
okbooleanOptionalExample: true
post
/events

Search events

post
/events/search

Alternative endpoint for searching events using POST method. Accepts the same parameters as GET /events but via request body.

Body
limitinteger · min: 1Optional
offsetintegerOptional
liststring · enumOptionalPossible values:
highlightedbooleanOptional
positionstringOptional
positionsstring[]Optional
creatorstringOptional
only_attendeebooleanOptional
searchstringOptional
schedulestringOptional
worldbooleanOptional
world_namesstring[]Optional
places_idsstring[]Optional
community_idstringOptional
orderstring · enumOptionalPossible values:
Responses
200

List of events

application/json
okbooleanOptionalExample: true
post
/events/search

Get events the user is attending

get
/events/attending

Returns all events that the authenticated user has marked as attending.

Responses
200

List of events user is attending

application/json
okbooleanOptionalExample: true
get
/events/attending

Get event by ID

get
/events/{event_id}

Retrieves detailed information about a specific event. If authenticated, includes whether the user is attending.

When called with the service bearer token (Authorization: Bearer ...), pending and rejected events are returned regardless of approval state.

Authorizations
AuthorizationstringOptional
Bearer authentication header of the form Bearer <token>.
Path parameters
event_idstring · uuidRequired

Event UUID

Responses
200

Event details

application/json
okbooleanOptionalExample: true
get
/events/{event_id}

Update an event

patch
/events/{event_id}

Updates an existing event. Users can only update their own events unless they have special permissions. Some fields require admin permissions.

When called with the service bearer token (Authorization: Bearer ...), permission checks are bypassed and the request body identifies the actor via the actor field. The body may alternatively contain only approval/rejection fields (approved, rejected, reason) to transition the event state without re-validating every editable attribute — see EventAdminActor and EventAdminReject.

Authorizations
AuthorizationstringOptional
Bearer authentication header of the form Bearer <token>.
Path parameters
event_idstring · uuidRequired

Event UUID

Body
or
or
or
Responses
200

Event updated successfully

application/json
okbooleanOptionalExample: true
patch
/events/{event_id}
PreviousOverviewNextEvent Attendees

Last updated