Skip to main content

​
Overview

The Events API allows users to create, manage, and RSVP to calendar events. Events can be scoped to global, space, group, or course contexts and support conflict detection.

​
Event Object

​
id
string
Unique event identifier
​
title
string
Event title
​
description
string
Event description
​
start
string
Event start time (ISO 8601 format)
​
end
string
Event end time (ISO 8601 format)
​
scopeType
string
Event scope: global, space, group, or course
​
scopeId
string
ID of the scope entity (space ID, group ID, etc.)
​
location
object
Event location information (JSON object)
​
reminderLeadMinutes
number
Minutes before event to send reminder (default: 30)
​
createdBy
string
User ID of event creator
​
icsUid
string
ICS calendar UID for calendar export
​
created
string
ISO 8601 timestamp of creation
​
updated
string
ISO 8601 timestamp of last update

​
List Events

Retrieve events with optional filtering.

​
Request

curl -X GET "https://your-domain.com/api/events?userId=USER_ID&from=2026-03-01&to=2026-03-31" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
​
userId
string
Filter events by user (shows events user created or is participating in)
​
scopeType
string
Filter by scope type: global, space, group, or course
​
scopeId
string
Filter by scope ID (e.g., specific space or group)
​
from
string
Start date filter (ISO 8601 format)
​
to
string
End date filter (ISO 8601 format)

​
Response

{
  "events": [
    {
      "id": "EVENT_ID",
      "collectionId": "events_collection_id",
      "collectionName": "events",
      "title": "Team Meeting",
      "description": "Weekly sync meeting",
      "start": "2026-03-05T14:00:00.000Z",
      "end": "2026-03-05T15:00:00.000Z",
      "scopeType": "group",
      "scopeId": "GROUP_ID",
      "location": {
        "name": "Room 101",
        "address": "123 Main St"
      },
      "reminderLeadMinutes": 30,
      "createdBy": "USER_ID",
      "icsUid": "unique-ics-id",
      "created": "2026-03-01 00:00:00.000Z",
      "updated": "2026-03-01 00:00:00.000Z"
    }
  ],
  "total": 1
}

​
Get Event

Retrieve a single event with participant details.

​
Request

curl -X GET "https://your-domain.com/api/events/{id}" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

​
Response

{
  "event": {
    "id": "EVENT_ID",
    "collectionId": "events_collection_id",
    "collectionName": "events",
    "title": "Team Meeting",
    "description": "Weekly sync meeting",
    "start": "2026-03-05T14:00:00.000Z",
    "end": "2026-03-05T15:00:00.000Z",
    "scopeType": "group",
    "scopeId": "GROUP_ID",
    "location": {
      "name": "Room 101"
    },
    "reminderLeadMinutes": 30,
    "createdBy": "USER_ID",
    "created": "2026-03-01 00:00:00.000Z",
    "updated": "2026-03-01 00:00:00.000Z",
    "expand": {
      "event_participants_via_event": [
        {
          "id": "PARTICIPANT_ID",
          "event": "EVENT_ID",
          "user": "USER_ID",
          "status": "going"
        }
      ],
      "createdBy": {
        "id": "USER_ID",
        "username": "creator"
      }
    }
  }
}

​
Create Event

Create a new calendar event.

​
Request

curl -X POST "https://your-domain.com/api/events" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Study Session",
    "description": "Prepare for final exam",
    "start": "2026-03-10T10:00:00.000Z",
    "end": "2026-03-10T12:00:00.000Z",
    "scopeType": "group",
    "scopeId": "GROUP_ID",
    "location": {
      "name": "Library"
    },
    "reminderLeadMinutes": 60
  }'
​
title
string
required
Event title
​
description
string
Event description
​
start
string
required
Event start time (ISO 8601 format)
​
end
string
required
Event end time (ISO 8601 format)
​
scopeType
string
default:"global"
Event scope: global, space, group, or course
​
scopeId
string
Scope entity ID (required for non-global events)
​
location
object
Location information (JSON object with any structure)
​
reminderLeadMinutes
number
default:"30"
Minutes before event to send reminder
​
date
string
Simplified date field (alternative to start/end). Creates 1-hour event.

​
Response

{
  "event": {
    "id": "EVENT_ID",
    "collectionId": "events_collection_id",
    "collectionName": "events",
    "title": "Study Session",
    "description": "Prepare for final exam",
    "start": "2026-03-10T10:00:00.000Z",
    "end": "2026-03-10T12:00:00.000Z",
    "scopeType": "group",
    "scopeId": "GROUP_ID",
    "location": "{\"name\":\"Library\"}",
    "reminderLeadMinutes": 60,
    "createdBy": "USER_ID",
    "created": "2026-03-03 12:00:00.000Z",
    "updated": "2026-03-03 12:00:00.000Z"
  },
  "message": "Event created successfully"
}

​
Update Event

Update an existing event. Only the event creator can update it.

​
Request

curl -X PATCH "https://your-domain.com/api/events/{id}" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Study Session",
    "start": "2026-03-10T11:00:00.000Z",
    "end": "2026-03-10T13:00:00.000Z"
  }'
​
title
string
Updated event title
​
description
string
Updated description
​
start
string
Updated start time
​
end
string
Updated end time
​
location
object
Updated location
​
reminderLeadMinutes
number
Updated reminder time

​
Response

{
  "event": {
    "id": "EVENT_ID",
    "title": "Updated Study Session",
    "start": "2026-03-10T11:00:00.000Z",
    "end": "2026-03-10T13:00:00.000Z",
    "updated": "2026-03-03 13:00:00.000Z"
  },
  "message": "Event updated successfully"
}

​
Delete Event

Delete an event. Only the event creator can delete it.

​
Request

curl -X DELETE "https://your-domain.com/api/events/{id}" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

​
Response

{
  "message": "Event deleted successfully"
}

​
RSVP to Event

Update your RSVP status for an event.

​
Request

curl -X POST "https://your-domain.com/api/events/{id}/rsvp" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "going"
  }'
​
status
string
required
RSVP status: going, maybe, or declined

​
Response

{
  "participant": {
    "id": "PARTICIPANT_ID",
    "collectionId": "event_participants_collection_id",
    "collectionName": "event_participants",
    "event": "EVENT_ID",
    "user": "USER_ID",
    "status": "going",
    "created": "2026-03-03 12:00:00.000Z",
    "updated": "2026-03-03 12:00:00.000Z"
  },
  "message": "RSVP updated successfully"
}

​
Remove RSVP

Remove your RSVP from an event.

​
Request

curl -X DELETE "https://your-domain.com/api/events/{id}/rsvp" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

​
Response

{
  "message": "RSVP removed successfully"
}

​
Export Event (ICS)

Download an event in iCalendar format for calendar apps.

​
Request

curl -X GET "https://your-domain.com/api/events/{id}/ics" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

​
Response

Returns an .ics file with Content-Type: text/calendar: 
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Campus//Event//EN
BEGIN:VEVENT
UID:unique-ics-id
DTSTART:20260310T100000Z
DTEND:20260310T120000Z
SUMMARY:Study Session
DESCRIPTION:Prepare for final exam
LOCATION:Library
END:VEVENT
END:VCALENDAR

​
Conflict Detection

When creating or updating events, the API automatically checks for conflicts within the same scope. If a conflict is detected, a 409 Conflict response is returned: 
{
  "error": "Event conflicts with existing event(s)",
  "conflicts": [
    {
      "id": "CONFLICTING_EVENT_ID",
      "title": "Existing Event",
      "start": "2026-03-10T10:30:00.000Z",
      "end": "2026-03-10T11:30:00.000Z"
    }
  ]
}
Conflict detection considers:
  • Events in the same scope (same scopeType and scopeId)
  • Overlapping time ranges
  • The current event is excluded when updating

Build docs developers (and LLMs) love

Get started for freeTalk to us