Mantle2 Activities Endpoints

Core activity catalogue (global) plus user activity management (see users.md). Parameter name in spec: activityId.

Global Catalogue Endpoints

• GET /v2/activities — list activities
• POST /v2/activities — create activity (Admin Only)
• GET /v2/activities/random — random selection
• GET /v2/activities/{activityId} — retrieve by ID
• PATCH /v2/activities/{activityId} — update (Admin Only)
• DELETE /v2/activities/{activityId} — delete (Admin Only)
• GET /v2/activities/list — array of activity IDs (lightweight)

User-Scoped Activity Operations (cross-reference)

Documented in users.md under:

• /v2/users/{id|username|current}/activities (GET/PATCH/PUT/DELETE)
• /v2/users/{id|username|current}/activities/recommend (GET)

Activity Schema

Activities represent global catalog items that users can add to their profiles. Each activity contains:

Field	Type	Description	Constraints
id	string	Unique activity identifier (24-digit zero-padded)	Required
name	string	Activity name	Required, max 255
description	string | null	Activity description	Optional, max 500
types	array	Array of ActivityType enum values	Max 5 types
aliases	array	Alternative names for the activity	Optional
fields	object	Custom metadata key-value pairs	Optional
created_at	string	ISO 8601 timestamp	Auto-generated
updated_at	string	ISO 8601 timestamp	Auto-updated

ActivityType Enum

Activities can be tagged with up to 5 types from the following list:

HOBBY, SPORT, WORK, STUDY, TRAVEL, SOCIAL, RELAXATION, HEALTH, PROJECT, PERSONAL_GOAL, COMMUNITY_SERVICE, CREATIVE, FAMILY, HOLIDAY, ENTERTAINMENT, LEARNING, NATURE, TECHNOLOGY, ART, SPIRITUALITY, FINANCE, HOME_IMPROVEMENT, PETS, FASHION, OTHER

Endpoints and Responses

GET /v2/activities

Retrieve paginated list of activities.

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": "000000000000001234567890",
			"name": "Hiking",
			"description": "Outdoor walking activity in natural environments",
			"types": ["SPORT", "NATURE", "HEALTH"],
			"aliases": ["trekking", "trail walking"],
			"fields": {
				"difficulty": "moderate",
				"equipment": "hiking boots"
			},
			"created_at": "2025-01-09T14:48:00Z",
			"updated_at": "2025-01-09T14:48:00Z"
		}
	],
	"page": 1,
	"limit": 20,
	"total": 1
}

400 Bad Request — invalid query parameters

POST /v2/activities

Create new activity (Admin Only).

Request Body

{
	"name": "Yoga",
	"description": "Mind-body practice combining physical postures and breathing",
	"types": ["HEALTH", "RELAXATION", "SPORT"],
	"aliases": ["yoga practice"],
	"fields": {
		"style": "hatha",
		"level": "beginner"
	}
}

Responses

201 Created:

{
	"id": "000000000000001234567891",
	"name": "Yoga",
	"description": "Mind-body practice combining physical postures and breathing",
	"types": ["HEALTH", "RELAXATION", "SPORT"],
	"aliases": ["yoga practice"],
	"fields": {
		"style": "hatha",
		"level": "beginner"
	},
	"created_at": "2025-01-10T10:30:00Z",
	"updated_at": "2025-01-10T10:30:00Z"
}

400 Bad Request — validation error (e.g., more than 5 types, missing required fields)

401 Unauthorized — authentication required

403 Forbidden — admin permission required

GET /v2/activities/random

Retrieve random activity selection.

Query Parameters

Name	Type	Description
limit	int	Number of random activities to get

Responses

200 OK:

{
	"items": [
		{
			"id": "000000000000001234567892",
			"name": "Rock Climbing",
			"description": "Ascending rock formations using hands and feet",
			"types": ["SPORT", "NATURE", "HEALTH"],
			"aliases": ["climbing", "bouldering"],
			"fields": {},
			"created_at": "2025-01-08T09:15:00Z",
			"updated_at": "2025-01-08T09:15:00Z"
		}
	],
	"page": 1,
	"limit": 1,
	"total": 1
}

GET /v2/activities/

Retrieve single activity by ID.

Path Parameters

Name	Type	Description
activityId	string	Activity identifier (24-digit string)

Responses

200 OK:

{
	"id": "000000000000001234567890",
	"name": "Hiking",
	"description": "Outdoor walking activity in natural environments",
	"types": ["SPORT", "NATURE", "HEALTH"],
	"aliases": ["trekking", "trail walking"],
	"fields": {
		"difficulty": "moderate",
		"equipment": "hiking boots"
	},
	"created_at": "2025-01-09T14:48:00Z",
	"updated_at": "2025-01-09T14:48:00Z"
}

404 Not Found:

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

PATCH /v2/activities/

Update activity (Admin Only).

Path Parameters

Name	Type	Description
activityId	string	Activity identifier (24-digit string)

Request Body

Any subset of activity fields:

{
	"name": "Updated Hiking",
	"types": ["SPORT", "NATURE"],
	"fields": {
		"difficulty": "hard"
	}
}

Responses

200 OK — returns updated activity object

400 Bad Request — validation error

401 Unauthorized — authentication required

403 Forbidden — admin permission required

404 Not Found

DELETE /v2/activities/

Delete activity (Admin Only).

Path Parameters

Name	Type	Description
activityId	string	Activity identifier (24-digit string)

Responses

204 No Content — deleted successfully

401 Unauthorized — authentication required

403 Forbidden — admin permission required

404 Not Found

GET /v2/activities/list

Get lightweight array of activity IDs only.

Responses

200 OK:

["000000000000001234567890", "000000000000001234567891", "000000000000001234567892"]

Notes

• Activities support up to 5 types from the ActivityType enum
• The fields object allows custom metadata storage for domain-specific properties
• User-scoped activity operations (adding activities to user profiles) are documented in users.md
• Recommendation endpoints use activity types and user preferences to suggest relevant activities

Error Format

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