Create / update / delete / reorder Knowledge Base categories and articles.
Required: widget_id (a DOCS widget), entity ("category" | "article" | "image"), action ("create" | "update" | "delete" | "reorder"; "upload" for images).
Category fields: name (create/update), category_id (update/delete), order (reorder: a list of category public_ids in the desired order).
Article fields: title, content (Quill HTML), status ("draft" | "published"), category_id, order; article_id for update/delete; order (reorder: a list of article public_ids).
Image fields (entity="image", action="upload"): image_base64 (raw base64 or a data-URL; max 10 MB decoded), filename (extension decides the type: jpg/jpeg/png/gif/webp/svg), optional title. Returns the stored image's url and ready-made embed_html: put that in article content to show the image.
URL
- User APIhttps://productivity.mattering.io/api/user/v1/kb/manage/
- Service tierhttps://productivity.mattering.io/api/internal/kb/manage/
Body keys (JSON)
| Key | Required | Default |
|---|---|---|
action | optional or conditional | none |
article_id | optional or conditional | none |
category_id | optional or conditional | none |
content | optional or conditional | none |
entity | optional or conditional | none |
filename | optional or conditional | none |
image_base64 | optional or conditional | none |
name | optional or conditional | none |
order | optional or conditional | none |
status | optional or conditional | none |
title | optional or conditional | none |
user_id | optional or conditional | none |
widget_id | optional or conditional | 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 bare JSON object (no envelope)
{
"success": true,
"article": {
"id": "...",
"title": "...",
"status": "...",
"order": 0,
"category_id": "...",
"updated_at": "2026-01-01T00:00:00Z",
"content": "..."
}
}
200 bare JSON object (no envelope)
{
"success": true,
"category": {
"id": "...",
"name": "...",
"order": 0
}
}
200 bare JSON object (no envelope)
{
"success": true,
"image": {
"id": "...",
"url": "...",
"title": "...",
"embed_html": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
|---|---|
| 400 | empty_image |
| 400 | image_base64_required |
| 400 | image_too_large |
| 400 | invalid_base64 |
| 400 | name_required |
| 400 | not_a_docs_widget |
| 400 | unsupported_action |
| 400 | unsupported_entity |
| 400 | unsupported_image_type |
| 401 | missing_actor |
| 401 | unauthorized |
| 403 | forbidden |
| 404 | article_not_found |
| 404 | category_not_found |
| 404 | widget_not_found |
Example
curl -X POST "https://productivity.mattering.io/api/user/v1/kb/manage/" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "...",
"article_id": "...",
"category_id": "...",
"content": "...",
"entity": "...",
"filename": "...",
"image_base64": "...",
"name": "..."
}'curl -X POST "https://productivity.mattering.io/api/internal/kb/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 '{
"action": "...",
"article_id": "...",
"category_id": "...",
"content": "...",
"entity": "...",
"filename": "...",
"image_base64": "...",
"name": "..."
}'
Source: MatteringPMCore/internal_api.py (internal_api.internal_manage_kb)