Events API: Create and Manage Availability Polls

The Events API is the core of Timeful. It lets you create availability polls (specific dates, days-of-week, or availability groups), collect responses from signed-in users or guests, and query aggregated calendar availability.

Most event endpoints do not require authentication — guests can view and respond to events without an account. Endpoints that modify ownership (delete, duplicate, archive, calendar availabilities, decline) do require a valid session.

Create Event

POST /api/events

Authentication is optional. If a session cookie is present, the new event is owned by that user. Otherwise ownerId is set to null (guest-created event). On success, returns 201 Created with the new event’s IDs:

{ "eventId": "64b3f1a2c9e77f001234abcd", "shortId": "abc123" }

Request Body

name

string

required

Display name for the event (e.g. "Team sync").

duration

number

required

Duration of the event window in hours (e.g. 1.5 for 90 minutes).

dates

datetime[]

required

Array of ISO 8601 datetime strings representing the candidate dates/slots.

type

string

required

Event type. One of:

"specific_dates" — poll across specific calendar dates
"dow" — poll across days of the week (repeating)
"group" — availability group (invites members by email)

hasSpecificTimes

boolean

When true, each date in dates has a corresponding entry in times specifying the exact time window. Only applicable for specific_dates events.

times

datetime[]

Parallel array to dates containing specific start times. Required when hasSpecificTimes is true.

description

string

Optional event description. Maximum 5 000 characters.

location

string

Optional location string. Maximum 500 characters.

When true, the event becomes a sign-up form where respondents choose named blocks rather than free-form availability.

Sign-up form mode string (used when isSignUpForm is true).

Array of SignUpBlock objects { name, capacity, startDate, endDate }. Each block is assigned an _id automatically if one is not provided.

startOnMonday

boolean

When true, the week view starts on Monday instead of Sunday. Applicable to dow events.

notificationsEnabled

boolean

When true, the event owner receives an email when someone responds.

blindAvailabilityEnabled

boolean

When true, respondents cannot see others’ availability until they have submitted their own.

daysOnly

boolean

When true, the poll collects day-level availability rather than time slots.

remindees

string[]

Array of email addresses. Each address receives a reminder email to respond. Scheduled via Google Cloud Tasks.

sendEmailAfterXResponses

integer

If set to a positive integer N, the owner receives a notification email after N responses are collected (fires once).

when2meetHref

string

Optional URL of an existing When2meet poll to import. When set, the event displays a link to the original When2meet page.

collectEmails

boolean

When true, guests are prompted to provide their email address when responding.

timeIncrement

integer

Time slot granularity in minutes. Defaults to 60 in this fork. Common values: 15, 30, 60.

maxCapacityPerSlot

integer

Columbia Math Department addition. Maximum number of respondents per time slot. When a slot is full, further sign-ups for that slot are rejected with a 400 listing blockedTimestamps.

attendees

string[]

Array of email addresses to invite. Only used when type is "group". Each address receives an invitation email.

Example:

curl -s -X POST http://localhost:3002/api/events \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team Kickoff",
    "duration": 1,
    "dates": ["2025-09-01T09:00:00Z", "2025-09-02T09:00:00Z"],
    "type": "specific_dates"
  }'

Get Event

GET /api/events/:eventId

No authentication required. Accepts either the MongoDB ObjectID hex string or the short ID (e.g. abc123). Response 200 OK: Full Event object including a responses map (keyed by user ID or guest name) with user profile info populated. Availability arrays are omitted from the responses map in this endpoint — use Get Responses to retrieve filtered availability.

curl -s http://localhost:3002/api/events/64b3f1a2c9e77f001234abcd

Edit Event

PUT /api/events/:eventId

Replaces the mutable fields of an event. If the event has an ownerId, the caller must be that owner (returns 403 otherwise). Guest-created events (no owner) can be edited by anyone. The request body accepts the same fields as Create Event minus creatorPosthogId. All four required fields (name, duration, dates, type) must always be sent. Response 200 OK: No body.

curl -s -X PUT http://localhost:3002/api/events/64b3f1a2c9e77f001234abcd \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team Kickoff (updated)",
    "duration": 1.5,
    "dates": ["2025-09-01T09:00:00Z"],
    "type": "specific_dates"
  }'

Get Responses

GET /api/events/:eventId/responses?timeMin=<ISO8601>&timeMax=<ISO8601>

Returns a map<userId, Response> with availability filtered to the [timeMin, timeMax] window. Useful when rendering a specific week in the availability grid. Query Parameters:

Parameter	Type	Required	Description
`timeMin`	ISO 8601	✅	Start of the time window
`timeMax`	ISO 8601	✅	End of the time window

curl -s "http://localhost:3002/api/events/64b3f1a2c9e77f001234abcd/responses?timeMin=2025-09-01T00:00:00Z&timeMax=2025-09-07T23:59:59Z"

Submit / Update Response

POST /api/events/:eventId/response

Creates or replaces the caller’s availability for an event. Works for both signed-in users ("guest": false) and guests ("guest": true).

guest

boolean

required

true for anonymous respondents; false for signed-in users.

name

string

Guest display name. Required when guest is true.

string

Guest email address. Optional when guest is true and collectEmails is enabled.

availability

datetime[]

Array of ISO 8601 timestamps the user is available.

ifNeeded

datetime[]

Array of timestamps where the user is available “if needed” (lower priority).

useCalendarAvailability

boolean

When true (Availability Groups), derive availability from connected calendars. Signed-in users only.

enabledCalendars

object

Map of { calendarAccountKey: [subCalendarId, ...] } specifying which sub-calendars to pull. Used with useCalendarAvailability.

manualAvailability

object

Map of { dayTimestamp: [availableTimestamps] } for manual overrides in Availability Groups.

calendarOptions

object

Per-response CalendarOptions (bufferTime, workingHours) to override the user’s global settings.

Array of SignUpBlock IDs the user is signing up for. Only used when isSignUpForm is true.

When maxCapacityPerSlot is set on the event and a requested time slot is full, the server returns 400 with { "error": "Some time slots are at capacity", "blockedTimestamps": [...] }.

Response 200 OK: Returns {}.

# Signed-in user response
curl -s -X POST http://localhost:3002/api/events/64b3f1a2c9e77f001234abcd/response \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "guest": false,
    "availability": ["2025-09-01T09:00:00Z", "2025-09-01T10:00:00Z"]
  }'

# Guest response
curl -s -X POST http://localhost:3002/api/events/64b3f1a2c9e77f001234abcd/response \
  -H "Content-Type: application/json" \
  -d '{
    "guest": true,
    "name": "Alice",
    "availability": ["2025-09-01T09:00:00Z"]
  }'

Delete Response

DELETE /api/events/:eventId/response

Removes a respondent’s availability from an event.

guest

boolean

required

true for guests; false for signed-in users.

name

string

Guest name to remove. Required when guest is true.

userId

string

The user ID whose response to delete. Required when guest is false and a signed-in user is removing another user’s response (owner-only action).

Response 200 OK: Returns {}.

Rename Guest Response

POST /api/events/:eventId/rename-user

Renames a guest respondent across all stored responses for the event.

oldName

string

The current guest name to replace.

newName

string

The new display name.

Response 200 OK: Returns {}.

Mark Remindee as Responded

POST /api/events/:eventId/responded

Marks the given email address as having responded to the event. This cancels the pending reminder email tasks for that address. If all remindees have responded, the event owner receives a “everyone responded” email.

string

required

Email address of the remindee to mark as responded.

Response 200 OK: Returns {}.

Decline Invite (Availability Groups)

POST /api/events/:eventId/decline

Requires authentication. Only valid for events with type: "group".

Sets the declined flag to true for the current user in the event’s attendees list. The user is removed from the group without deleting their existing response. Response 200 OK: Returns {}.

Get Calendar Availabilities

GET /api/events/:eventId/calendar-availabilities?timeMin=<ISO8601>&timeMax=<ISO8601>

Requires authentication. Only valid for events with type: "group".

Returns a map of { userId: [CalendarEvent, ...] } for all group members who have opted in to calendar-based availability (useCalendarAvailability: true). Events belonging to other users have their summary redacted to "BUSY". Query Parameters:

Parameter	Type	Required	Description
`timeMin`	ISO 8601	✅	Start of the window
`timeMax`	ISO 8601	✅	End of the window

curl -s -b cookies.txt \
  "http://localhost:3002/api/events/64b3f1a2c9e77f001234abcd/calendar-availabilities?timeMin=2025-09-01T00:00:00Z&timeMax=2025-09-07T23:59:59Z"

Delete Event

DELETE /api/events/:eventId

Requires authentication. The caller must be the event owner.

If the event has responses from users other than the owner, the event is soft-deleted (isDeleted: true). If no such responses exist, the event and all folder associations are permanently removed. Response 200 OK: No body.

curl -s -X DELETE http://localhost:3002/api/events/64b3f1a2c9e77f001234abcd \
  -b cookies.txt

Duplicate Event

POST /api/events/:eventId/duplicate

Requires authentication. The caller must be the event owner.

Creates a new event that is a copy of the original. A new short ID is generated automatically.

eventName

string

required

Display name for the duplicated event.

copyAvailability

boolean

required

When true, all existing responses are copied to the new event.

Response 201 Created:

{ "eventId": "64b3f1a2c9e77f001234xxxx", "shortId": "xyz789" }

Archive Event

POST /api/events/:eventId/archive

Requires authentication. The caller must be the event owner.

Toggles the isArchived flag on an event. Archived events are hidden from the default event list but not deleted.

Event Object Reference

_id

string

MongoDB ObjectID of the event.

shortId

string

Human-readable short identifier (used in /e/:shortId URLs).

ownerId

string

ObjectID of the owning user, or null for guest-created events.

name

string

Event display name.

description

string

Optional event description. Maximum 5,000 characters.

location

string

Optional location string. Maximum 500 characters.

type

string

"specific_dates", "dow", or "group".

duration

number

Duration of the polling window in hours.

dates

datetime[]

Candidate dates/slots as ISO 8601 datetime strings.

hasSpecificTimes

boolean

When true, each date has a corresponding entry in times specifying the exact time window.

times

datetime[]

Parallel array to dates with specific start times. Present when hasSpecificTimes is true.

notificationsEnabled

boolean

When true, the event owner receives an email when someone responds.

sendEmailAfterXResponses

integer

When positive, the owner receives a one-time email after this many responses are collected. Set to -1 after the email fires.

when2meetHref

string

URL of a linked When2meet poll, if set.

collectEmails

boolean

When true, guests are prompted to provide their email address when responding.

timeIncrement

integer

Slot granularity in minutes (e.g. 15, 30, 60).

maxCapacityPerSlot

integer

Maximum number of respondents per time slot. When a slot is full, further sign-ups are rejected.

When true, the event is a sign-up form where respondents choose named blocks rather than free-form availability.

Sign-up form mode string (used when isSignUpForm is true).

Array of SignUpBlock objects ({ _id, name, capacity, startDate, endDate }).

Map of { userId/guestName: SignUpResponse } for sign-up form events.

startOnMonday

boolean

When true, the week view starts on Monday rather than Sunday. Applicable to dow events.

blindAvailabilityEnabled

boolean

When true, respondents cannot see others’ availability until they have submitted their own.

daysOnly

boolean

When true, the poll collects day-level availability rather than time slots.

responses

object

Map of { userId/guestName: Response }. Populated by GET /api/events/:eventId with user profile info. Availability arrays are omitted in that endpoint; use GET /api/events/:eventId/responses for filtered availability.

numResponses

integer

Cached count of responses.

scheduledEvent

object

A CalendarEvent object representing a scheduled meeting created from this poll, if one has been set.

calendarEventId

string

ID of the calendar event associated with this poll’s scheduled meeting.

remindees

object[]

Array of Remindee objects ({ email, responded }). Each remindee receives a reminder email to respond.

attendees

object[]

Array of Attendee objects for availability group events (type: "group"). Populated on GET /api/events/:eventId.

hasResponded

boolean

For availability group events, indicates whether the authenticated user has already submitted availability. Populated on GET /api/user/events.

isArchived

boolean

Whether the event is archived (hidden from the default event list).

isDeleted

boolean

Whether the event is soft-deleted. Soft-deleted events retain responses but are excluded from user event listings.

creatorPosthogId

string

Optional PostHog analytics ID for the event creator.

Overview

Endpoints

Events API: Create and Manage Availability Polls

Create Event

Request Body

Get Event

Edit Event

Get Responses

Submit / Update Response

Delete Response

Rename Guest Response

Mark Remindee as Responded

Decline Invite (Availability Groups)

Get Calendar Availabilities

Delete Event

Duplicate Event

Archive Event

Event Object Reference

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Create Event

​Request Body

​Get Event

​Edit Event

​Get Responses

​Submit / Update Response

​Delete Response

​Rename Guest Response

​Mark Remindee as Responded

​Decline Invite (Availability Groups)

​Get Calendar Availabilities

​Delete Event

​Duplicate Event

​Archive Event

​Event Object Reference

Build docs developers (and LLMs) love

Create Event

Request Body

Get Event

Edit Event

Get Responses

Submit / Update Response

Delete Response

Rename Guest Response

Mark Remindee as Responded

Decline Invite (Availability Groups)

Get Calendar Availabilities

Delete Event

Duplicate Event

Archive Event

Event Object Reference