Announcements

Announcements are company-wide messages that can be targeted to specific groups. They are published on creation unless you send is_published: false.

Required scope: read:announcements, write:announcements.

Endpoints

GET

/api/open/v1/announcements

List announcements (published by default, paginated)

GET

/api/open/v1/announcements/{id}

Get a single announcement

POST

/api/open/v1/announcements

Create an announcement (published by default)

PUT

/api/open/v1/announcements/{id}

Update an announcement

DELETE

/api/open/v1/announcements/{id}

Delete an announcement (returns 204)

GET

/api/open/v1/announcements/{id}/confirmations

List who has confirmed this announcement (paginated)

GET

/api/open/v1/confirmations

List announcement confirmations, newest first (paginated)

Filtering by status

By default, the list returns only published announcements. Use the status query parameter to retrieve drafts:

`status`	Returns
`published` (default)	Currently-live content only (published, with a publish time in the past).
`draft`	Unpublished content only — drafts, plus items awaiting a scheduled publish.
`all`	Every item, regardless of state.

curl "https://customer.monotree.com/api/open/v1/announcements?status=draft" \
  -H "Authorization: Bearer mono_your_token_here"

An unrecognised value returns 422. Read each item's is_published field to tell drafts and published items apart in an all response. Fetching a single announcement by id (GET /announcements/{id}) always works regardless of state.

The list is sorted by published_at, newest first, and takes the standard page, per_page (max 50) and since parameters (see Pagination).

Create

curl -X POST https://customer.monotree.com/api/open/v1/announcements \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Office closed on Friday",
    "subtitle": "Facility update",
    "body": "Due to maintenance, the office will be closed this Friday.",
    "groups": [1, 3]
  }'

Instead of body, pass article_id to attach a pre-built standalone article (see Articles) — the two are mutually exclusive.

Published by default — pass is_published: false to create a draft, then publish later via the update endpoint.

Request body

Field	Type	Notes
`title`	string	Required. Max 255 characters.
`body`	string	Required unless `article_id` is sent. Plain text, becomes a single article paragraph. Max 50,000 characters. Cannot be combined with `article_id`.
`article_id`	integer	Optional. Attach a pre-built standalone article created via `POST /articles` (create only). An article that already belongs to other content returns `422`.
`subtitle`	string	Optional. Max 255 characters.
`groups`	array of integers	Optional. Group IDs to target. Empty/omitted = company-wide. An unknown group ID returns `422`.
`is_published`	boolean	Optional. Defaults to `true` (published on create). `false` creates a draft.

Returns 201 with the announcement.

Update

PUT accepts the same fields as create (minus article_id, which only attaches an article at create — an update ignores it). All fields are optional — send only the fields you want to change. groups replaces the targeted groups; [] removes them all.

Publish a draft now: { "is_published": true }
Unpublish (back to draft): { "is_published": false }
Once an announcement's article carries rich content (anything beyond a single paragraph), body writes are rejected (422, error on body) — use PUT /articles/{id}/elements instead.

curl -X PUT https://customer.monotree.com/api/open/v1/announcements/456 \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title"}'

Response

{
  "data": {
    "id": 456,
    "article_id": 91,
    "title": "Office closed on Friday",
    "subtitle": "Facility update",
    "body": "Due to maintenance, the office will be closed this Friday.",
    "author": {
      "id": 1,
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "title": "Facility Manager",
      "email": "john@example.com",
      "type": "default",
      "avatar_url": "https://images.monotree.com/avatars/john-doe.jpg",
      "is_manager": false,
      "groups": [],
      "hired_at": "2025-06-01",
      "date_of_birth": "1994-08-12",
      "is_away": false,
      "last_active_on": "2026-03-22T14:05:12.000000Z",
      "registered_at": "2025-06-01T09:00:00+02:00",
      "created_at": "2025-06-01T09:00:00+02:00"
    },
    "groups": [
      { "id": 1, "name": "All Staff", "type": "custom", "created_at": "2026-01-15T10:00:00+01:00" }
    ],
    "is_published": true,
    "is_commentable": true,
    "is_confirmable": false,
    "is_pinned": false,
    "comments_count": 0,
    "completions_count": 0,
    "confirmations_count": 0,
    "starts_at": "2026-03-22",
    "published_at": "2026-03-22T10:00:00+01:00",
    "created_at": "2026-03-22T10:00:00+01:00",
    "updated_at": "2026-03-22T10:00:00+01:00"
  }
}

body is plain text from the article's first three headers and paragraphs, "" when the article is empty. It is not the full content: read that with GET /articles/{article_id} or GET /articles/{article_id}/markdown.

Confirmations

An announcement marked confirmable in the CMS asks employees to acknowledge that they have read it — a required briefing. confirmations_count on the announcement is the total; these endpoints list the confirmations themselves, for reconciling against the monotree.announcement.confirmed webhook.

Confirming is once per employee per item and cannot be undone, so each confirmation id is stable and appears exactly once.

curl "https://customer.monotree.com/api/open/v1/announcements/456/confirmations" \
  -H "Authorization: Bearer mono_your_token_here"

GET /confirmations returns them across announcements instead of one at a time — the call to make after a failed webhook delivery, since an employee can confirm a briefing published months ago.

Parameter	Notes
`since`	ISO 8601 timestamp; only confirmations made at or after it. URL-encode the `+` in the offset.
`per_page`	Default 25, maximum 50.

Both endpoints are newest first, and both take since and per_page.

Response

{
  "data": [
    {
      "id": 8842,
      "type": "announcement",
      "created_at": "2026-09-21T09:12:41+02:00",
      "user": {
        "id": 501,
        "name": "Jane Doe",
        "first_name": "Jane",
        "last_name": "Doe",
        "title": null,
        "email": "jane@example.com",
        "type": "default",
        "avatar_url": null,
        "is_manager": false,
        "groups": [],
        "hired_at": "2025-09-01",
        "date_of_birth": null,
        "is_away": false,
        "last_active_on": "2026-09-21T07:12:41.000000Z",
        "registered_at": "2025-11-01T09:00:00+01:00",
        "created_at": "2025-11-01T09:00:00+01:00"
      },
      "announcement": {
        "id": 456,
        "article_id": 91,
        "title": "Fire drill briefing",
        "subtitle": "",
        "body": "Read before your next shift.",
        "author": {
          "id": 1,
          "name": "John Doe",
          "first_name": "John",
          "last_name": "Doe",
          "title": "Facility Manager",
          "email": "john@example.com",
          "type": "default",
          "avatar_url": null,
          "is_manager": false,
          "groups": [],
          "hired_at": "2025-06-01",
          "date_of_birth": null,
          "is_away": false,
          "last_active_on": "2026-09-21T07:00:00.000000Z",
          "registered_at": "2025-06-01T09:00:00+02:00",
          "created_at": "2025-06-01T09:00:00+02:00"
        },
        "groups": [],
        "is_published": true,
        "is_commentable": true,
        "is_confirmable": true,
        "is_pinned": false,
        "comments_count": 0,
        "completions_count": 40,
        "confirmations_count": 12,
        "starts_at": "2026-09-01",
        "published_at": "2026-09-01T08:00:00+02:00",
        "created_at": "2026-09-01T08:00:00+02:00",
        "updated_at": "2026-09-01T08:00:00+02:00"
      }
    }
  ]
}

The confirmed item is keyed by its type, which is announcement, and is the full announcement in the shape of the response above. created_at is the moment the employee confirmed. Company events can be made confirmable too, but their confirmations are not exposed yet — ask us if you need them.

article_id links the entry's rich content — manage it through the articles endpoints.