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, write:handbooks.

Endpoints

GET

/api/open/v1/handbooks

List handbooks (published by default, paginated)

GET

/api/open/v1/handbooks/{id}

Get a handbook incl. ordered chapter summaries

POST

/api/open/v1/handbooks

Create a handbook (draft by default)

PATCH

/api/open/v1/handbooks/{id}

Update a handbook; publish via is_published

DELETE

/api/open/v1/handbooks/{id}

Delete a handbook and its chapters (returns 204)

GET

/api/open/v1/handbooks/{id}/chapters

List chapters (position order, paginated)

POST

/api/open/v1/handbooks/{id}/chapters

Create a chapter — its article is created automatically

GET

/api/open/v1/handbook-chapters/{id}

Get a single chapter

PATCH

/api/open/v1/handbook-chapters/{id}

Update title/subtitle, position, is_published

DELETE

/api/open/v1/handbook-chapters/{id}

Delete a chapter (409 when a course shares its article)

Lists support ?status=published|draft|all (default published) and ?since=.

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] }'

Field	Type	Notes
`title`	string	Required.
`subtitle`	string	Optional.
`groups`	int[]	Optional group targeting; omit for a global handbook.
`is_published`	boolean	Optional, default `false` (draft). Publishing without a title returns `422`.
`translations`	object	Optional — the handbook's own title/subtitle in other locales: `{ "title": { "sv": "…" }, "subtitle": { "sv": "…" } }`. Same semantics as article translations.

PATCH /handbooks/{id} accepts the same fields — all optional. Chapter titles and content are translated through their articles; the translations field here covers only the handbook's own title and subtitle.

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" }'

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+00:00",
    "is_referenced": false,
    "created_at": "2026-07-01T09:00:00+00:00",
    "updated_at": "2026-07-01T09:00:00+00:00"
  }
}

is_referenced is true when a course chapter shares this chapter's article — such chapters cannot be deleted (409), and editing the article changes both places. 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.