Menu

Knowledge bases

2 endpoints in the Mattering Productivity API.

POST kb/manage/ User APIService tier

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.

This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.

URL

  • User APIhttps://productivity.mattering.io/api/user/v1/kb/manage/
  • Service tierhttps://productivity.mattering.io/api/internal/kb/manage/

Body keys (JSON)

KeyRequiredDefault
actionoptional or conditionalnone
article_idoptional or conditionalnone
category_idoptional or conditionalnone
contentoptional or conditionalnone
entityoptional or conditionalnone
filenameoptional or conditionalnone
image_base64optional or conditionalnone
nameoptional or conditionalnone
orderoptional or conditionalnone
statusoptional or conditionalnone
titleoptional or conditionalnone
user_idoptional or conditionalnone
widget_idoptional or conditionalnone

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

StatusCode
400empty_image
400image_base64_required
400image_too_large
400invalid_base64
400name_required
400not_a_docs_widget
400unsupported_action
400unsupported_entity
400unsupported_image_type
401missing_actor
401unauthorized
403forbidden
404article_not_found
404category_not_found
404widget_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": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_manage_kb)

POST query/kb/ User APIService tier

Read Knowledge Base (DOCS widget) content.

Required: space_id, config (with widget_id). Optional config: article_id (returns the full article incl. content), query (case-insensitive search over title + content), document (true: the whole KB: or category_id's articles: as ONE markdown document, max_chars cap, default 200k). With none of these, returns the full category + article tree. Draft articles are visible only to editors.

This read is not paginated. It returns at most 8 rows and does not report a total, so a result of exactly 8 may be truncated.

URL

  • User APIhttps://productivity.mattering.io/api/user/v1/query/kb/
  • Service tierhttps://productivity.mattering.io/api/internal/query/kb/

Body keys (JSON)

KeyRequiredDefault
configoptional or conditionalnone
space_idoptional or conditionalnone

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,
  "data": {
    "type": "query",
    "query": "query_kb",
    "widget": {
      "id": "...",
      "title": "...",
      "widget_type": "...",
      "widget_type_label": "..."
    },
    "can_edit": true,
    "categories": [
      {
        "id": "...",
        "name": "...",
        "order": 0
      }
    ],
    "articles": [
      {
        "id": "...",
        "title": "...",
        "status": "...",
        "order": 0,
        "category_id": "...",
        "updated_at": "2026-01-01T00:00:00Z",
        "content": "..."
      }
    ]
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
401missing_actor
401unauthorized
403forbidden
404article_not_found
404docs_widget_not_found

Example

curl -X POST "https://productivity.mattering.io/api/user/v1/query/kb/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "config": "...",
  "space_id": "..."
}'

Source: MatteringPMCore/internal_api.py (internal_api.internal_query_kb)

All Productivity resources
Start Free Explore our Products