Mantle2 Prompts Endpoints

Prompt catalogue and user responses. Path parameter names: prompt, response.

Catalogue & Management

• GET /v2/prompts — list prompts
• POST /v2/prompts — create prompt
• GET /v2/prompts/random — random prompts
• GET /v2/prompts/{prompt} — retrieve prompt
• PATCH /v2/prompts/{prompt} — update prompt
• DELETE /v2/prompts/{prompt} — delete prompt
• POST /v2/prompts/check_expired — admin task to check expired prompts

Responses to Prompts

• GET /v2/prompts/{prompt}/responses — list responses for a prompt
• POST /v2/prompts/{prompt}/responses — create response
• GET /v2/prompts/{prompt}/responses/{response} — get single response
• PATCH /v2/prompts/{prompt}/responses/{response} — update response
• DELETE /v2/prompts/{prompt}/responses/{response} — delete response

Prompt Schema

Prompts are daily reflection questions presented to users. Each prompt contains:

Field	Type	Description	Constraints
id	string	Unique prompt identifier (24-digit zero-padded)	Required
prompt	string	The prompt question/statement	10-100 chars
owner_id	string	ID of user who created the prompt (24-digit)	Required
owner	object	Full user object of prompt creator	Embedded
visibility	string	Who can see the prompt (see Visibility enum)	Required
responses_count	number	Total number of responses to this prompt	Auto-calculated
has_responded	boolean	Whether current user has responded (authenticated only)	Conditional
created_at	string	ISO 8601 timestamp	Auto-generated
updated_at	string	ISO 8601 timestamp	Auto-updated

Visibility Enum (for Prompts)

Value	Description
PUBLIC	Visible to all users, auto-expires after 2 days
UNLISTED	Requires login to view, not shown in public listings
PRIVATE	Only visible to owner and admins

Prompt Expiration

• PUBLIC prompts automatically expire and are deleted after 2 days (172,800 seconds)
• UNLISTED and PRIVATE prompts do not expire automatically
• The /v2/prompts/check_expired admin endpoint processes expired prompts

Prompt Response Schema

User responses to prompts. Each response contains:

Field	Type	Description	Constraints
id	string	Unique response identifier (24-digit zero-padded)	Required
prompt_id	string	ID of the prompt being responded to (24-digit)	Required
response	string	User's text response	Max 700 chars
owner	object	Full user object of response author	Embedded
created_at	string	ISO 8601 timestamp	Auto-generated
updated_at	string	ISO 8601 timestamp	Auto-updated

Endpoints and Responses

GET /v2/prompts

Retrieve paginated list of prompts.

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": "000000000000004567890123",
			"prompt": "What made you smile today?",
			"owner_id": "000000000000000123456789",
			"owner": {
				"id": "000000000000000123456789",
				"username": "prompt_creator",
				"email": "[email protected]"
			},
			"visibility": "PUBLIC",
			"responses_count": 42,
			"has_responded": false,
			"created_at": "2025-01-10T08:00:00Z",
			"updated_at": "2025-01-10T08:00:00Z"
		}
	],
	"page": 1,
	"limit": 20,
	"total": 1
}

400 Bad Request — invalid query parameters

POST /v2/prompts

Create new prompt.

Request Body

{
	"prompt": "What are you grateful for today?",
	"visibility": "PUBLIC"
}

Responses

201 Created:

{
	"id": "000000000000004567890124",
	"prompt": "What are you grateful for today?",
	"owner_id": "000000000000000123456789",
	"owner": {
		"id": "000000000000000123456789",
		"username": "prompt_creator",
		"email": "[email protected]"
	},
	"visibility": "PUBLIC",
	"responses_count": 0,
	"has_responded": false,
	"created_at": "2025-01-10T14:00:00Z",
	"updated_at": "2025-01-10T14:00:00Z"
}

400 Bad Request — validation error (e.g., prompt too short/long)

401 Unauthorized — authentication required

GET /v2/prompts/random

Retrieve random prompt selection.

Query Parameters

Name	Type	Description
limit	int	Number of random prompts to get

Responses

200 OK:

{
	"items": [
		{
			"id": "000000000000004567890125",
			"prompt": "What's one thing you learned this week?",
			"owner_id": "000000000000000987654321",
			"owner": {
				"id": "000000000000000987654321",
				"username": "another_user",
				"email": "[email protected]"
			},
			"visibility": "PUBLIC",
			"responses_count": 18,
			"has_responded": true,
			"created_at": "2025-01-09T10:00:00Z",
			"updated_at": "2025-01-09T10:00:00Z"
		}
	],
	"page": 1,
	"limit": 1,
	"total": 1
}

GET /v2/prompts/

Retrieve single prompt by ID.

Path Parameters

Name	Type	Description
prompt	string	Prompt identifier (24-digit string)

Responses

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

404 Not Found:

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

PATCH /v2/prompts/

Update prompt. Only the prompt owner or admin can update.

Path Parameters

Name	Type	Description
prompt	string	Prompt identifier (24-digit string)

Request Body

Any subset of updatable fields:

{
	"prompt": "Updated prompt text?",
	"visibility": "UNLISTED"
}

Responses

200 OK — returns updated prompt object

400 Bad Request — validation error

401 Unauthorized — authentication required

403 Forbidden — not prompt owner or admin

404 Not Found

DELETE /v2/prompts/

Delete prompt. Only the prompt owner or admin can delete.

Path Parameters

Name	Type	Description
prompt	string	Prompt identifier (24-digit string)

Responses

204 No Content — deleted successfully

401 Unauthorized — authentication required

403 Forbidden — not prompt owner or admin

404 Not Found

POST /v2/prompts/check_expired

Admin endpoint to check and delete expired PUBLIC prompts (older than 2 days).

Responses

204 No Content — processed successfully

401 Unauthorized — authentication required

403 Forbidden — admin permission required

GET /v2/prompts/{prompt}/responses

List all responses for a specific prompt.

Path Parameters

Name	Type	Description
prompt	string	Prompt identifier (24-digit string)

Query Parameters

Name	Type	Description
limit	int	Page size
page	int	Page index
sort	string	Sort expression

Responses

200 OK:

{
	"items": [
		{
			"id": "000000000000005678901234",
			"prompt_id": "000000000000004567890123",
			"response": "Today I smiled when I saw a beautiful sunset on my evening walk. It reminded me to appreciate the simple things.",
			"owner": {
				"id": "000000000000000987654321",
				"username": "reflective_user",
				"email": "[email protected]"
			},
			"created_at": "2025-01-10T18:30:00Z",
			"updated_at": "2025-01-10T18:30:00Z"
		}
	],
	"page": 1,
	"limit": 20,
	"total": 1
}

404 Not Found — prompt does not exist

POST /v2/prompts/{prompt}/responses

Create response to a prompt.

Path Parameters

Name	Type	Description
prompt	string	Prompt identifier (24-digit string)

Request Body

{
	"response": "I'm grateful for my health, my family, and the opportunity to pursue my passions. Today was especially meaningful."
}

Responses

201 Created:

{
	"id": "000000000000005678901235",
	"prompt_id": "000000000000004567890124",
	"response": "I'm grateful for my health, my family, and the opportunity to pursue my passions. Today was especially meaningful.",
	"owner": {
		"id": "000000000000000123456789",
		"username": "prompt_creator",
		"email": "[email protected]"
	},
	"created_at": "2025-01-10T15:00:00Z",
	"updated_at": "2025-01-10T15:00:00Z"
}

400 Bad Request — validation error (e.g., response too long, exceeds 700 char limit)

401 Unauthorized — authentication required

403 Forbidden — permission denied

404 Not Found — prompt does not exist

GET /v2/prompts/{prompt}/responses/

Retrieve single response by ID.

Path Parameters

Name	Type	Description
prompt	string	Prompt identifier (24-digit string)
response	string	Response identifier (24-digit string)

Responses

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

404 Not Found

PATCH /v2/prompts/{prompt}/responses/

Update response. Only the response owner or admin can update.

Path Parameters

Name	Type	Description
prompt	string	Prompt identifier (24-digit string)
response	string	Response identifier (24-digit string)

Request Body

{
	"response": "Edited response text that still respects the 700 character limit."
}

Responses

200 OK — returns updated response object

400 Bad Request — validation error

401 Unauthorized — authentication required

403 Forbidden — not response owner or admin

404 Not Found

DELETE /v2/prompts/{prompt}/responses/

Delete response. Only the response owner or admin can delete.

Path Parameters

Name	Type	Description
prompt	string	Prompt identifier (24-digit string)
response	string	Response identifier (24-digit string)

Responses

204 No Content — deleted successfully

401 Unauthorized — authentication required

403 Forbidden — not response owner or admin

404 Not Found

Notes

• Prompts must be between 10 and 100 characters
• Responses can be up to 700 characters
• PUBLIC prompts automatically expire after 2 days and are deleted via the check_expired endpoint
• The has_responded field only appears when a user is authenticated
• The responses_count field is automatically calculated and updated
• Content flagging is applied to both prompts and responses

Error Format

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

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