Handbooks

Structured, chaptered content — policies, guides, manuals. A handbook holds ordered chapters; each chapter owns an article carrying its title and content. Flow: create the handbook (draft by default), add chapters, fill each chapter's article, publish.

Required scope: read:handbooks for the GET endpoints, write:handbooks for the rest. A chapter's content is read and written through the articles endpoints, which take read:articles / write:articles plus the handbook scope: reading a chapter's article takes read:handbooks or write:handbooks, writing it takes write:handbooks, otherwise 403.

Handbooks are a feature that is switched on per company. While it is off, every endpoint on this page, and the articles endpoints for a handbook chapter's article, return 403 with the message The handbooks feature is not enabled., even with the right scope.

Endpoints

Both lists take ?status=published|draft|all (default published; any other value returns 422) and page / per_page (max 50). GET /handbooks also takes ?since= (created at or after); the chapter list does not. Handbooks and chapters are listed in the order set in the CMS (position). GET /handbooks/{id} and GET /handbook-chapters/{id} return drafts too.

Handbook response

GET, POST and PATCH on a handbook return this object. chapters — the ordered chapter summaries — is only included by GET /handbooks/{id}; the list, create and update leave it out.

{
  "data": {
    "id": 7,
    "title": "Employee Handbook",
    "subtitle": "Everything you need to know",
    "translations": {
      "title": { "en": "Employee Handbook", "sv": "Personalhandbok" },
      "subtitle": { "en": "Everything you need to know" }
    },
    "groups": [
      { "id": 1, "name": "Kitchen", "type": "department", "created_at": "2025-09-01T10:00:00+02:00" }
    ],
    "is_published": false,
    "published_at": null,
    "chapters_count": 1,
    "chapters": [
      { "id": 55, "title": "Getting Started", "subtitle": "First steps", "position": 0, "is_published": true, "article_id": 91 }
    ],
    "created_at": "2026-07-01T09:00:00+02:00",
    "updated_at": "2026-07-01T09:00:00+02:00"
  }
}

groups is the handbook's targeting, empty for a global handbook. chapters_count counts the chapters, drafts included.

Create a handbook

curl -X POST https://customer.monotree.com/api/open/v1/handbooks \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Employee Handbook", "subtitle": "Everything you need to know", "groups": [1, 3] }'

Returns 201 with the handbook object.

PATCH /handbooks/{id} accepts the same fields — all optional — and only changes what you send; groups replaces the targeting. Publishing a handbook that has no title in the default content locale returns 422. Chapter titles and content are translated through their articles; the translations field here covers only the handbook's own title and subtitle.

DELETE /handbooks/{id} deletes the handbook together with its chapters and returns 204.

Add a chapter

Creating a chapter automatically creates its article — the response carries the article_id for the articles endpoints. Chapters are published by default (visibility is governed by the handbook); pass is_published: false for a draft. Chapter title/subtitle live on the article.

curl -X POST https://customer.monotree.com/api/open/v1/handbooks/7/chapters \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Getting Started", "subtitle": "First steps" }'

Returns 201 with the chapter object. PATCH /handbook-chapters/{id} takes the same fields, all optional, plus position (integer, 0 or more).

Chapter response

{
  "data": {
    "id": 55,
    "handbook_id": 7,
    "article_id": 91,
    "title": "Getting Started",
    "subtitle": "First steps",
    "position": 0,
    "is_published": true,
    "published_at": "2026-07-01T09:00:00+02:00",
    "is_referenced": false,
    "created_at": "2026-07-01T09:00:00+02:00",
    "updated_at": "2026-07-01T09:00:00+02:00"
  }
}

is_referenced is true when a course chapter shares this chapter's article — such chapters cannot be deleted, and editing the article changes both places. Deleting one returns 409:

{
  "error": "conflict",
  "message": "This chapter is referenced by one or more courses and cannot be deleted."
}

Otherwise DELETE /handbook-chapters/{id} returns 204. PATCH with position reorders the chapter within its handbook. For a flat markdown export of a chapter's content, use GET /articles/{article_id}/markdown.

Chapter title/subtitle in responses are the default content locale — their translations are read and written through the chapter's article, see translations.