GET POST
learn/articles/list
User API Service tier
List learn articles, or create one with POST. derived from route
URL
User API https://www.mattering.io/api/user/v1/learn/articles/list
Service tier https://www.mattering.io/api/internal/v1/learn/articles/list
Pagination
Accepts limit and offset. The response meta carries total, limit and offset.
Responses
200 data and meta envelope
{
"data": {
"articles": [
{
"slug": "...",
"title": "...",
"excerpt": "...",
"topic_slug": "...",
"tags": [
"..."
],
"difficulty_level": "...",
"related_products": "...",
"featured": "...",
"published": "...",
"published_at": "2026-01-01T00:00:00Z",
"reading_time": "...",
"seo_title": "...",
"seo_description": "...",
"canonical_url": "...",
"has_schema": true,
"url_path": "...",
"updated_at": "2026-01-01T00:00:00Z",
"content": "...",
"schema_jsonld": "..."
}
]
},
"meta": {
"total": 0,
"limit": 0,
"offset": 0
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 invalid_json401 unauthorized500 server_misconfigured
Example
User API Service tier
curl -X GET "https://www.mattering.io/api/user/v1/learn/articles/list" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://www.mattering.io/api/internal/v1/learn/articles/list" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: education/api.py (api.list_articles)
POST
learn/articles/manage
User API Service tier
POST to learn/articles/manage. derived from route
This read is not paginated. It returns at most 200 rows and does not report a total, so a result of exactly 200 may be truncated.
URL
User API https://www.mattering.io/api/user/v1/learn/articles/manage
Service tier https://www.mattering.io/api/internal/v1/learn/articles/manage
Body keys (JSON)
Key Required Default
actionoptional or conditional none canonical_urloptional or conditional none contentrequired none difficulty_leveloptional or conditional none excerptrequired none featuredoptional or conditional none publishedoptional or conditional falsepublished_atoptional or conditional none reading_timeoptional or conditional none related_productsoptional or conditional none schema_jsonldoptional or conditional none seo_descriptionoptional or conditional none seo_titleoptional or conditional none slugrequired none tagsoptional or conditional none titlerequired none topicoptional or conditional none topic_slugrequired none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 data and meta envelope
{
"data": {
"article": {
"slug": "...",
"title": "...",
"excerpt": "...",
"topic_slug": "...",
"tags": [
"..."
],
"difficulty_level": "...",
"related_products": "...",
"featured": "...",
"published": "...",
"published_at": "2026-01-01T00:00:00Z",
"reading_time": "...",
"seo_title": "...",
"seo_description": "...",
"canonical_url": "...",
"has_schema": true,
"url_path": "...",
"updated_at": "2026-01-01T00:00:00Z",
"content": "...",
"schema_jsonld": "..."
}
}
}
200 data and meta envelope
{
"data": {
"deleted": "..."
}
}
201 data and meta envelope
{
"data": {
"article": {
"slug": "...",
"title": "...",
"excerpt": "...",
"topic_slug": "...",
"tags": [
"..."
],
"difficulty_level": "...",
"related_products": "...",
"featured": "...",
"published": "...",
"published_at": "2026-01-01T00:00:00Z",
"reading_time": "...",
"seo_title": "...",
"seo_description": "...",
"canonical_url": "...",
"has_schema": true,
"url_path": "...",
"updated_at": "2026-01-01T00:00:00Z",
"content": "...",
"schema_jsonld": "..."
}
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 field_too_long400 invalid_action400 invalid_json400 missing_field401 unauthorized404 article_not_found409 slug_exists500 server_misconfigured
Example
User API Service tier
curl -X POST "https://www.mattering.io/api/user/v1/learn/articles/manage" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "...",
"excerpt": "...",
"slug": "...",
"title": "...",
"topic_slug": "...",
"action": "...",
"canonical_url": "...",
"difficulty_level": "..."
}' curl -X POST "https://www.mattering.io/api/internal/v1/learn/articles/manage" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"content": "...",
"excerpt": "...",
"slug": "...",
"title": "...",
"topic_slug": "...",
"action": "...",
"canonical_url": "...",
"difficulty_level": "..."
}'
Source: education/api.py (api.manage_article)
GET
learn/articles/{slug}
User API Service tier
Read one of the learn articles by id. derived from route
URL
User API https://www.mattering.io/api/user/v1/learn/articles/{slug}
Service tier https://www.mattering.io/api/internal/v1/learn/articles/{slug}
Path parameters
Responses
200 data and meta envelope
{
"data": {
"article": {
"slug": "...",
"title": "...",
"excerpt": "...",
"topic_slug": "...",
"tags": [
"..."
],
"difficulty_level": "...",
"related_products": "...",
"featured": "...",
"published": "...",
"published_at": "2026-01-01T00:00:00Z",
"reading_time": "...",
"seo_title": "...",
"seo_description": "...",
"canonical_url": "...",
"has_schema": true,
"url_path": "...",
"updated_at": "2026-01-01T00:00:00Z",
"content": "...",
"schema_jsonld": "..."
}
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
401 unauthorized404 article_not_found500 server_misconfigured
Example
User API Service tier
curl -X GET "https://www.mattering.io/api/user/v1/learn/articles/SLUG" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://www.mattering.io/api/internal/v1/learn/articles/SLUG" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: education/api.py (api.get_article)
POST
learn/topics/manage
User API Service tier
POST to learn/topics/manage. derived from route
URL
User API https://www.mattering.io/api/user/v1/learn/topics/manage
Service tier https://www.mattering.io/api/internal/v1/learn/topics/manage
Body keys (JSON)
Key Required Default
actionoptional or conditional none coloroptional or conditional none cta_typeoptional or conditional none descriptionoptional or conditional none iconoptional or conditional none namerequired none orderoptional or conditional none slugrequired none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 data and meta envelope
{
"data": {
"deleted": true,
"slug": "..."
}
}
200 data and meta envelope
{
"data": {
"topic": {
"slug": "...",
"name": "...",
"description": "...",
"icon": "...",
"color": "...",
"cta_type": "...",
"order": 0
}
}
}
201 data and meta envelope
{
"data": {
"topic": {
"slug": "...",
"name": "...",
"description": "...",
"icon": "...",
"color": "...",
"cta_type": "...",
"order": 0
}
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 invalid_action400 invalid_json400 missing_field401 unauthorized404 topic_not_found409 slug_exists409 topic_has_articles500 server_misconfigured
Example
User API Service tier
curl -X POST "https://www.mattering.io/api/user/v1/learn/topics/manage" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "...",
"slug": "...",
"action": "...",
"color": "...",
"cta_type": "...",
"description": "...",
"icon": "...",
"order": "..."
}' curl -X POST "https://www.mattering.io/api/internal/v1/learn/topics/manage" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"name": "...",
"slug": "...",
"action": "...",
"color": "...",
"cta_type": "...",
"description": "...",
"icon": "...",
"order": "..."
}'
Source: education/api.py (api.manage_topic)