Announcements

Announcements are company-wide messages that can be targeted to specific groups. They are automatically published on creation.

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 and publish an announcement

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.

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.
`body`	string	Required.
`subtitle`	string	Optional.
`groups`	array of integers	Optional. Group IDs to target. Empty/omitted = company-wide.

Update

All fields are optional on PUT. Send only the fields you want to change.

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",
      "email": "john@example.com",
      "type": "user",
      "avatar_url": "https://images.monotree.com/avatars/john-doe.jpg",
      "groups": []
    },
    "groups": [
      { "id": 1, "name": "All Staff", "type": "custom", "created_at": "2026-01-15T10:00:00+00: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+00:00",
    "created_at": "2026-03-22T10:00:00+00:00",
    "updated_at": "2026-03-22T10:00:00+00:00"
  }
}

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",
        "email": "jane@example.com",
        "type": "employee",
        "avatar_url": null,
        "groups": []
      },
      "announcement": {
        "id": 456,
        "title": "Fire drill briefing",
        "is_confirmable": true,
        "confirmations_count": 12
      }
    }
  ]
}

The confirmed item is keyed by its type, which is announcement. 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.