Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ptshen/timeful-plus/llms.txt

Use this file to discover all available pages before exploring further.

All endpoints in the User API are grouped under /api/user and require an authenticated session. Requests without a valid session cookie receive 401 Unauthorized.
Every endpoint in this group is protected by middleware.AuthRequired(). Sign in first via POST /api/auth/sign-in and include the session cookie on all requests.

​
Get Profile

GET /api/user/profile
Returns the complete User object for the currently signed-in user, including the current month’s event creation count. Response 200 OK: A User object (see User Object Reference). 
curl -s -b cookies.txt http://localhost:3002/api/user/profile

​
Update Name

PATCH /api/user/name
Sets a custom display name for the user. Once a custom name is set, signing in again will not overwrite it with the name from the OAuth provider.
​
firstName
string
required
New first name.
​
lastName
string
required
New last name.
Response 200 OK: Returns {}. 
curl -s -X PATCH http://localhost:3002/api/user/name \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Alex", "lastName": "Smith" }'

​
Update Calendar Options

PATCH /api/user/calendar-options
Persists the user’s calendar autofill preferences. All fields are optional; only provided fields are updated.
​
bufferTime
object
Buffer time settings applied when computing free slots.
​
workingHours
object
Constrains calendar availability to a working-hours window.
Response 200 OK: Returns {}.

​
Get Events

GET /api/user/events
Returns an array of all events the user owns, has responded to, or is an attendee of. Results are sorted newest-first. Soft-deleted events (isDeleted: true) are excluded. For availability groups (type: "group"), each event includes a hasResponded boolean indicating whether the user has already submitted availability. Response 200 OK: Array of Event objects. 
curl -s -b cookies.txt http://localhost:3002/api/user/events

​
Set Event Folder

POST /api/user/events/:eventId/set-folder
Assigns an event to a folder, or removes it from any folder.
​
folderId
string
ObjectID of the target folder. Pass null to remove the event from its current folder.
Response 200 OK: No body. 
# Assign event to folder
curl -s -X POST http://localhost:3002/api/user/events/64b3f1a2c9e77f001234abcd/set-folder \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{ "folderId": "64b3f1a2c9e77f001234ffff" }'

# Remove from folder
curl -s -X POST http://localhost:3002/api/user/events/64b3f1a2c9e77f001234abcd/set-folder \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{ "folderId": null }'

​
Get Calendar Events

GET /api/user/calendars?timeMin=<ISO8601>&timeMax=<ISO8601>&accounts=<comma-separated>
Fetches calendar events from the user’s connected accounts within the specified time window. Query Parameters:
ParameterTypeRequiredDescription
timeMinISO 8601✅Start of the time window
timeMaxISO 8601✅End of the time window
accountsstring—Comma-separated list of calendarAccountKey strings to query
Response 200 OK: Map of { calendarAccountKey: { calendarEvents: [...], error: ... } }. 
curl -s -b cookies.txt \
  "http://localhost:3002/api/user/calendars?timeMin=2025-09-01T00:00:00Z&timeMax=2025-09-07T23:59:59Z"

​
Add Google Calendar Account

POST /api/user/add-google-calendar-account
Links an additional Google account to the user’s profile using an OAuth authorization code.
​
code
string
required
Google OAuth authorization code.
​
scope
string
required
OAuth scope string.
Response 200 OK: Returns {}.

​
Add Apple Calendar Account

POST /api/user/add-apple-calendar-account
Links an Apple Calendar account using an Apple ID email and app-specific password. Credentials are encrypted before storage.
​
email
string
required
Apple ID email address.
​
password
string
required
App-specific password generated from Apple ID settings.
Response 200 OK: Returns {}. Returns 401 with { "error": "invalid-credentials" } if the credentials are rejected.

​
Add Outlook Calendar Account

POST /api/user/add-outlook-calendar-account
Links a Microsoft Outlook account using an OAuth authorization code.
​
code
string
required
Microsoft OAuth authorization code.
​
scope
string
required
OAuth scope string.
Response 200 OK: Returns {}.

​
Remove Calendar Account

DELETE /api/user/remove-calendar-account
Unlinks a calendar account from the user’s profile.
​
email
string
required
Email address of the account to remove.
​
calendarType
string
required
Calendar type of the account: "google", "outlook", or "apple".
Response 200 OK: Returns {}.

​
Toggle Calendar Account

POST /api/user/toggle-calendar
Enables or disables an entire calendar account for availability autofill.
​
email
string
required
Email of the calendar account to toggle.
​
calendarType
string
required
Calendar type: "google", "outlook", or "apple".
​
enabled
boolean
required
true to enable; false to disable.
Response 200 OK: Returns {}.

​
Toggle Sub-Calendar

POST /api/user/toggle-sub-calendar
Enables or disables an individual sub-calendar (e.g. a specific Google Calendar within an account) for availability autofill.
​
email
string
required
Email of the parent calendar account.
​
calendarType
string
required
Calendar type: "google", "outlook", or "apple".
​
subCalendarId
string
required
ID of the sub-calendar to toggle.
​
enabled
boolean
required
true to enable; false to disable.
Response 200 OK: Returns {}.

​
Search Contacts

GET /api/user/searchContacts?query=<string>
Searches the user’s Google contacts matching the query string. Useful for auto-completing attendee email fields. Query Parameters:
ParameterTypeRequiredDescription
querystring✅Search term
Response 200 OK: Array of matching User-shaped objects (name, email, picture). 
curl -s -b cookies.txt \
  "http://localhost:3002/api/user/searchContacts?query=alice"

​
Delete User

DELETE /api/user
Permanently deletes the signed-in user’s account from MongoDB and clears their session. Response 200 OK: Returns {}.
This action is irreversible. The user’s events and responses are not automatically removed.

​
User Object Reference

​
_id
string
MongoDB ObjectID of the user.
​
email
string
Primary email address from the OAuth provider.
​
firstName
string
First name (from OAuth or custom override).
​
lastName
string
Last name (from OAuth or custom override).
​
picture
string
Profile picture URL from the OAuth provider.
​
timezoneOffset
integer
User’s UTC offset in minutes at time of last sign-in.
​
hasCustomName
boolean
When true, OAuth sign-in will not overwrite firstName/lastName.
​
calendarAccounts
object
Map of { "email_CALENDARTYPE": CalendarAccount }. Keys are constructed as {email}_{CALENDARTYPE} (e.g. alice@gmail.com_google).
​
primaryAccountKey
string
The calendarAccountKey of the account used during initial sign-in.
​
calendarOptions
object
Global CalendarOptions containing bufferTime and workingHours settings.
​
isPremium
boolean
Whether the user has an active premium subscription (or SELF_HOSTED_PREMIUM=true is set).
​
stripeCustomerId
string
Stripe customer ID associated with the user’s premium subscription. Absent for users who have never initiated a checkout.
​
numEventsCreated
integer
Number of events created this calendar month (computed at request time, not stored).

Build docs developers (and LLMs) love

Get started for freeTalk to us