Mantle2 Articles Endpoints
Scientific article metadata (ingested via Cloud + Ocean scraping pipeline). Parameter: articleId.
Catalogue & Management
- GET /v2/articles — list articles
- POST /v2/articles — create article
- GET /v2/articles/random — random articles
- GET /v2/articles/{articleId} — retrieve article
- PATCH /v2/articles/{articleId} — update article
- DELETE /v2/articles/{articleId} — delete article
- POST /v2/articles/check_expired — admin check expired articles
Article Schema
Articles represent scientific publications and research content scraped from external sources (PubMed, DOAJ, SpringerOpen). Each article contains user-created summary/commentary plus rich metadata from the original source.
| Field | Type | Description | Constraints |
|---|---|---|---|
| id | string | Unique article identifier (24-digit zero-padded) | Required |
| title | string | User-defined article title | Required, max 100 |
| description | string | User-created summary/description | Required, max 512 |
| tags | array | User-defined tags for categorization | Max 10, 30 chars each |
| content | string | User-written article content/commentary | 50-25000 chars |
| color | number | Color identifier (integer) | Auto-generated |
| color_hex | string | Hex color code | Derived from color |
| author_id | string | ID of user who created the article (24-digit) | Required |
| author | object | Full user object of article creator | Embedded |
| ocean | object | Scraped metadata from original source | See Ocean Schema |
| created_at | string | ISO 8601 timestamp | Auto-generated |
| updated_at | string | ISO 8601 timestamp | Auto-updated |
Ocean Metadata Schema
The ocean object contains rich metadata scraped from the original scientific article source:
| Field | Type | Description | Constraints |
|---|---|---|---|
| title | string | Original article title from source | Required |
| url | string | URL to original article | URI format |
| author | string | Original article author(s) | Optional |
| source | string | Publication source (e.g., "PubMed", "DOAJ") | Optional |
| abstract | string | Original article abstract | Max 10000 chars |
| content | string | Full article text content | Max 100000 chars |
| keywords | array | Article keywords/subjects | Max 25 items |
| links | object | Related links (DOI, PMC, etc.) | Key-value pairs |
| theme_color | string | Extracted theme color from source | Hex format (#RRGGBB) |
| date | string | Publication date | ISO 8601 datetime |
| favicon | string | Source website favicon URL | URI format |
Endpoints and Responses
GET /v2/articles
Retrieve paginated list of articles.
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:
json
{
"items": [
{
"id": "000000000000002345678901",
"title": "Circadian Rhythm and Sleep Patterns",
"description": "Analysis of how circadian rhythms affect sleep quality in shift workers",
"tags": ["sleep", "circadian", "health", "research"],
"content": "This article explores the relationship between circadian rhythms and sleep patterns...",
"color": 16711680,
"color_hex": "#FF0000",
"author_id": "000000000000000123456789",
"author": {
"id": "000000000000000123456789",
"username": "dr_smith",
"email": "[email protected]"
},
"ocean": {
"title": "Effects of Circadian Disruption on Sleep Quality in Night Shift Workers",
"url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
"author": "Smith J, Johnson A, Williams K",
"source": "PubMed",
"abstract": "Background: Circadian rhythm disruption is common among night shift workers...",
"content": "Full article text content here...",
"keywords": ["circadian rhythm", "sleep", "shift work", "melatonin", "chronobiology"],
"links": {
"doi": "10.1234/journal.2024.12345",
"pmc": "PMC12345678"
},
"theme_color": "#003366",
"date": "2024-11-15T00:00:00Z",
"favicon": "https://pubmed.ncbi.nlm.nih.gov/favicon.ico"
},
"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/articles
Create new article entry.
Request Body
json
{
"title": "Chronobiology Research Review",
"description": "Comprehensive review of recent chronobiology research findings",
"tags": ["chronobiology", "research", "review"],
"content": "This review examines the latest developments in chronobiology research, focusing on practical applications for improving sleep and health outcomes. The field has seen significant advances in understanding how circadian rhythms influence various physiological processes...",
"ocean": {
"title": "Advances in Chronobiology: A 2024 Review",
"url": "https://doaj.org/article/xyz789",
"author": "Chen L, Patel R",
"source": "DOAJ",
"abstract": "This comprehensive review examines recent advances...",
"content": "Full article content...",
"keywords": ["chronobiology", "circadian", "sleep"],
"links": {
"doi": "10.5678/review.2024.999"
},
"theme_color": "#1a5490",
"date": "2024-12-01T00:00:00Z",
"favicon": "https://doaj.org/favicon.ico"
}
}Responses
201 Created:
json
{
"id": "000000000000002345678902",
"title": "Chronobiology Research Review",
"description": "Comprehensive review of recent chronobiology research findings",
"tags": ["chronobiology", "research", "review"],
"content": "This review examines the latest developments in chronobiology research...",
"color": 8421504,
"color_hex": "#808080",
"author_id": "000000000000000123456789",
"author": {
"id": "000000000000000123456789",
"username": "dr_smith",
"email": "[email protected]"
},
"ocean": {
"title": "Advances in Chronobiology: A 2024 Review",
"url": "https://doaj.org/article/xyz789",
"author": "Chen L, Patel R",
"source": "DOAJ",
"abstract": "This comprehensive review examines recent advances...",
"content": "Full article content...",
"keywords": ["chronobiology", "circadian", "sleep"],
"links": {
"doi": "10.5678/review.2024.999"
},
"theme_color": "#1a5490",
"date": "2024-12-01T00:00:00Z",
"favicon": "https://doaj.org/favicon.ico"
},
"created_at": "2025-01-10T11:00:00Z",
"updated_at": "2025-01-10T11:00:00Z"
}400 Bad Request — validation error (e.g., title too long, content too short/long, too many tags)
401 Unauthorized — authentication required
403 Forbidden — permission denied
GET /v2/articles/random
Retrieve random article selection.
Query Parameters
| Name | Type | Description |
|---|---|---|
| limit | int | Number of random articles to get |
Responses
200 OK:
json
{
"items": [
{
"id": "000000000000002345678903",
"title": "Neural Mechanisms of Memory",
"description": "Exploring how the brain encodes and retrieves memories",
"tags": ["neuroscience", "memory", "brain"],
"content": "Recent advances in neuroscience have revealed fascinating insights...",
"color": 255,
"color_hex": "#0000FF",
"author_id": "000000000000000987654321",
"author": {
"id": "000000000000000987654321",
"username": "neuro_researcher",
"email": "[email protected]"
},
"ocean": {
"title": "Neural Correlates of Long-Term Memory Formation",
"url": "https://springeropen.com/articles/memory-2024",
"author": "Brown M, Davis P",
"source": "SpringerOpen",
"abstract": "We investigated neural mechanisms underlying memory formation...",
"content": "Full research article...",
"keywords": ["memory", "neuroscience", "hippocampus", "plasticity"],
"links": {
"doi": "10.1234/springer.2024.456"
},
"theme_color": "#006699",
"date": "2024-10-20T00:00:00Z",
"favicon": "https://springeropen.com/favicon.ico"
},
"created_at": "2025-01-08T09:30:00Z",
"updated_at": "2025-01-08T09:30:00Z"
}
],
"page": 1,
"limit": 1,
"total": 1
}GET /v2/articles/
Retrieve single article by ID.
Path Parameters
| Name | Type | Description |
|---|---|---|
| articleId | string | Article identifier (24-digit string) |
Responses
200 OK — returns full article object (same structure as POST response)
404 Not Found:
json
{
"error": {
"code": "E404",
"message": "Article not found"
}
}PATCH /v2/articles/
Update article. Only the article creator or admin can update.
Path Parameters
| Name | Type | Description |
|---|---|---|
| articleId | string | Article identifier (24-digit string) |
Request Body
Any subset of updatable fields:
json
{
"title": "Updated Title",
"description": "Updated description",
"tags": ["new", "tags"],
"content": "Updated article content with at least 50 characters to meet minimum length requirement."
}Responses
200 OK — returns updated article object
400 Bad Request — validation error
401 Unauthorized — authentication required
403 Forbidden — not article creator or admin
404 Not Found
DELETE /v2/articles/
Delete article. Only the article creator or admin can delete.
Path Parameters
| Name | Type | Description |
|---|---|---|
| articleId | string | Article identifier (24-digit string) |
Responses
204 No Content — deleted successfully
401 Unauthorized — authentication required
403 Forbidden — not article creator or admin
404 Not Found
POST /v2/articles/check_expired
Admin endpoint to check and process expired articles.
Responses
204 No Content — processed successfully
401 Unauthorized — authentication required
403 Forbidden — admin permission required
Notes
- Articles are created by users to share and discuss scientific research
- The
oceanobject contains rich metadata from the original source (scraped via Cloud + Ocean pipeline) - Color is auto-generated as an integer and provided as hex code for frontend use
- User-scoped listing endpoints exist in
users.md(/v2/users/{id|username|current}/articles) - Tags are limited to 10 items with max 30 characters each
- Content must be between 50 and 25,000 characters
Error Format
json
{
"error": {
"code": "E404",
"message": "Not found"
}
}