Mantle2 Events Endpoints

Event lifecycle management and participation. Parameter name in spec: eventId.

Endpoints

• GET /v2/events — list events
• POST /v2/events — create event
• GET /v2/events/{eventId} — retrieve event
• PATCH /v2/events/{eventId} — update event
• DELETE /v2/events/{eventId} — delete event
• GET /v2/events/{eventId}/attendees — list attendees
• POST /v2/events/{eventId}/signup — current user signs up
• POST /v2/events/{eventId}/leave — current user cancels signup
• GET /v2/events/current — events for current user

Event Schema

Events represent gatherings or activities organized by users. Each event contains:

Field	Type	Description	Constraints
id	string	Unique event identifier (24-digit zero-padded)	Required
hostId	string	ID of user hosting the event (24-digit)	Required
host	object	Full user object of event host	Embedded
name	string	Event name/title	Required, max 50
description	string	Event description	Required, max 3000
type	string	Event type (see EventType enum)	Required
activities	array	Array of ActivityType values	Optional
location	object	Geographic coordinates	Required for IN_PERSON
date	string	Event start date/time (ISO 8601)	Required (milliseconds)
end_date	string | null	Event end date/time (ISO 8601)	Optional
visibility	string	Who can see the event (see Visibility enum)	Required
attendees	array	Array of attendee user IDs (24-digit)	Auto-managed
created_at	string	ISO 8601 timestamp	Auto-generated
updated_at	string	ISO 8601 timestamp	Auto-updated

EventType Enum

Value	Description
IN_PERSON	Physical event at a specific location
ONLINE	Virtual event (no physical location)
HYBRID	Both in-person and online attendance options

Visibility Enum

Value	Description
PUBLIC	Visible to all users
UNLISTED	Requires login to view, not shown in public listings
PRIVATE	Only visible to owner, admins, attendees, and mutual friends

Location Schema

For IN_PERSON and HYBRID events:

Field	Type	Description
latitude	number	Latitude coordinate
longitude	number	Longitude coordinate

Endpoints and Responses

GET /v2/events

Retrieve paginated list of events.

Query Parameters

Name	Type	Description
limit	int	Page size
page	int	Page index
search	string	Free-text search
sort	string	Sort expression

Responses

200 OK:

{
	"items": [
		{
			"id": "000000000000003456789012",
			"hostId": "000000000000000123456789",
			"host": {
				"id": "000000000000000123456789",
				"username": "event_organizer",
				"email": "[email protected]"
			},
			"name": "Community Running Group",
			"description": "Weekly running group for all fitness levels. We meet at the park entrance and run together on the trails.",
			"type": "IN_PERSON",
			"activities": ["SPORT", "HEALTH", "SOCIAL"],
			"location": {
				"latitude": 37.7749,
				"longitude": -122.4194
			},
			"date": "2025-01-15T18:00:00Z",
			"end_date": "2025-01-15T19:30:00Z",
			"visibility": "PUBLIC",
			"attendees": ["000000000000000123456789", "000000000000000987654321"],
			"created_at": "2025-01-09T10:00:00Z",
			"updated_at": "2025-01-09T10:00:00Z"
		}
	],
	"page": 1,
	"limit": 20,
	"total": 1
}

400 Bad Request — invalid query parameters

POST /v2/events

Create new event.

Request Body

{
	"name": "Virtual Book Club Meeting",
	"description": "Monthly book club discussion via video call. This month we're discussing science fiction classics.",
	"type": "ONLINE",
	"activities": ["LEARNING", "SOCIAL", "ENTERTAINMENT"],
	"date": "2025-01-20T19:00:00Z",
	"end_date": "2025-01-20T21:00:00Z",
	"visibility": "PUBLIC"
}

For IN_PERSON events, include location:

{
	"name": "Park Cleanup Day",
	"description": "Community service event to clean up the local park. Bring gloves and bags.",
	"type": "IN_PERSON",
	"activities": ["COMMUNITY_SERVICE", "SOCIAL", "NATURE"],
	"location": {
		"latitude": 37.7749,
		"longitude": -122.4194
	},
	"date": "2025-01-22T09:00:00Z",
	"end_date": "2025-01-22T12:00:00Z",
	"visibility": "PUBLIC"
}

Responses

201 Created:

{
	"id": "000000000000003456789013",
	"hostId": "000000000000000123456789",
	"host": {
		"id": "000000000000000123456789",
		"username": "event_organizer",
		"email": "[email protected]"
	},
	"name": "Virtual Book Club Meeting",
	"description": "Monthly book club discussion via video call. This month we're discussing science fiction classics.",
	"type": "ONLINE",
	"activities": ["LEARNING", "SOCIAL", "ENTERTAINMENT"],
	"date": "2025-01-20T19:00:00Z",
	"end_date": "2025-01-20T21:00:00Z",
	"visibility": "PUBLIC",
	"attendees": ["000000000000000123456789"],
	"created_at": "2025-01-10T12:00:00Z",
	"updated_at": "2025-01-10T12:00:00Z"
}

400 Bad Request — validation error (e.g., name too long, description too long, IN_PERSON event missing location)

401 Unauthorized — authentication required

403 Forbidden — permission denied

GET /v2/events/

Retrieve single event by ID.

Path Parameters

Name	Type	Description
eventId	string	Event identifier (24-digit string)

Responses

200 OK — returns full event object (same structure as POST response)

404 Not Found:

{
	"error": {
		"code": "E404",
		"message": "Event not found"
	}
}

PATCH /v2/events/

Update event. Only the event host or admin can update.

Path Parameters

Name	Type	Description
eventId	string	Event identifier (24-digit string)

Request Body

Any subset of updatable fields:

{
	"name": "Updated Event Name",
	"description": "Updated description",
	"date": "2025-01-25T18:00:00Z",
	"visibility": "UNLISTED"
}

Responses

200 OK — returns updated event object

400 Bad Request — validation error

401 Unauthorized — authentication required

403 Forbidden — not event host or admin

404 Not Found

DELETE /v2/events/

Delete event. Only the event host or admin can delete.

Path Parameters

Name	Type	Description
eventId	string	Event identifier (24-digit string)

Responses

204 No Content — deleted successfully

401 Unauthorized — authentication required

403 Forbidden — not event host or admin

404 Not Found

GET /v2/events/{eventId}/attendees

List all attendees for an event.

Path Parameters

Name	Type	Description
eventId	string	Event identifier (24-digit string)

Responses

200 OK:

{
	"items": [
		{
			"id": "000000000000000123456789",
			"username": "event_organizer",
			"email": "[email protected]"
		},
		{
			"id": "000000000000000987654321",
			"username": "participant1",
			"email": "[email protected]"
		}
	],
	"page": 1,
	"limit": 20,
	"total": 2
}

404 Not Found — event does not exist

POST /v2/events/{eventId}/signup

Current user signs up to attend the event.

Path Parameters

Name	Type	Description
eventId	string	Event identifier (24-digit string)

Responses

200 OK — successfully joined event

401 Unauthorized — authentication required

404 Not Found — event does not exist

409 Conflict — already signed up

POST /v2/events/{eventId}/leave

Current user cancels their signup for the event.

Path Parameters

Name	Type	Description
eventId	string	Event identifier (24-digit string)

Responses

200 OK — successfully left event

401 Unauthorized — authentication required

404 Not Found — event does not exist or user not signed up

GET /v2/events/current

Retrieve events for the current authenticated user (events they're hosting or attending).

Responses

200 OK — returns paginated list of events (same structure as GET /v2/events)

401 Unauthorized — authentication required

Notes

• Event dates and end_dates are stored as millisecond timestamps internally, returned as ISO 8601 strings
• IN_PERSON events require location coordinates (latitude/longitude)
• ONLINE events do not require location
• HYBRID events should include location for the in-person component
• Visibility controls who can see the event:
  • PUBLIC: visible to all users
  • UNLISTED: requires login, not in public listings
  • PRIVATE: only visible to host, admins, attendees, and mutual friends
• Host is automatically added to attendees when event is created
• Activity types help categorize events and power recommendation algorithms

Error Format

{
	"error": {
		"code": "E404",
		"message": "Not found"
	}
}