Changelog

Changes and updates to the Open API. This API is currently in beta — breaking changes may occur between versions.

v0.45.0 — September 2026

Added GET /token, which returns the calling token's name, scopes and expiry. It works with any valid token and needs no scope, so an integration can check a token at setup
monotree.onboarding.completed now carries onboarding_completed_at, the moment the employee completed onboarding (additive). The payloads of both user events are now documented

v0.44.0 — September 2026

New outgoing webhook event monotree.announcement.confirmed, sent when an employee confirms they have read a confirmable announcement. The payload carries the confirmation with the employee and the announcement embedded, keyed by its type
Added GET /announcements/{id}/confirmations (read:announcements) — who has acknowledged one briefing — and GET /confirmations?since=, every announcement confirmation newest first, for catching up after a failed webhook delivery
Confirming is once per employee per announcement, and there is no un-confirm: a confirmation is announced exactly once and its id is a stable idempotency key. Company events can be made confirmable too, but their confirmations are not exposed yet

v0.43.0 — September 2026

Added POST /notifications (new write:notifications scope) to put a notification in employees' activity feed, targeted by groups, users or both. Each recipient gets one feed notification (no push) with a title, a body and an optional https:// or app link that opens on tap
The response gives the number of employees matched; the notifications are created in the background. Employees who have turned notifications off, deactivated employees and bots are skipped

v0.41.1 — September 2026

Wall posts that an employee has scheduled for later are no longer returned: they are left out of GET /walls/{wall_id}/posts under every status, and GET /walls/{wall_id}/posts/{id} answers 404 until the post goes live

v0.41.0 — September 2026

Added POST /achievements and PATCH /achievements/{id} (new write:achievements scope) to create and update achievements: type, title, description, emoji, visibility, trigger config, translations and published state. Achievements are created as drafts unless is_published is true; requires the achievements feature
The type cannot be changed after creation. Completion and employment achievements need a complete trigger_config before they can be published, and publishing one starts awarding employees who meet the trigger
Added POST /achievements/{id}/awards (write:achievements) to award a published achievement to employees, in a department (required for employee of the month). assigned_by on these awards is the company's own user (type: customer); an identical award (same user and day) is returned instead of duplicated, and new awards are announced like CMS awards — push notification, colleague feed and the monotree.achievement.awarded webhook
Deleting achievements and awards is not part of the API

v0.40.0 — September 2026

Added Achievements endpoints (read:achievements scope): GET /achievements, GET /achievements/{id}, GET /achievements/{id}/awards and GET /users/{id}/achievements — achievements, every award of one, and the awards a user holds. Personal achievements are included; requires the achievements feature
New outgoing webhook event monotree.achievement.awarded, sent when a user is given an achievement (automatically or by hand), filterable by achievement. The payload is the award with the achievement and the user embedded. awarded_at is the awarded day as midnight in the customer server's timezone, with its offset — read the date in that offset
Every outgoing webhook and report delivery now carries customer in the envelope — the sending customer's Monotree identifier, the CMS test event included — so one receiver can serve several Monotree customers (additive)
Outgoing webhook retries now run 1 minute and 10 minutes after the first attempt (was ~10 s and ~100 s), and every attempt is signed with a fresh Timestamp, so a retry passes a receiver's replay window. The per-attempt timeout is 3 seconds

v0.39.0 — September 2026

Users carry a title — the employee's job title, set per user in the CMS (null when unset, never synced from an HR system). It is on the user object everywhere it appears (additive)
GET /org-chart labels a person box with that job title, falling back to the title typed on the box and then to the profession name. custom_title still returns the box's own title

v0.38.0 — September 2026

Added POST /users/{id}/avatar (write:users scope) to set an employee's profile picture from an uploaded image (multipart media field), for example from an HR system. It replaces any picture the employee chose themselves; colleagues are not notified
The response is the user object with the new avatar_url, the same field GET /users already exposes

v0.37.0 — September 2026

POST /walls/{wall_id}/posts and the wall_post incoming webhook accept a mix of image, video and document media in one post. A single-type batch is still stored as an image, video or file gallery; a mix (or more than one video) as a mixed gallery. Chat message media is still one type per batch

v0.36.0 — August 2026

Added POST /groups (write:groups scope) to create departments, professions and custom groups. Created groups are live immediately. type defaults to department; is_open is only valid on custom groups

v0.35.1 — August 2026

POST /calendar-entries no longer fails with 500 when the company has no published event type named "Default" to fall back on — calendar_event_type_id is required in that case and a missing one returns 422 with a message pointing at GET /calendar-event-types
The calendar_entry incoming webhook accepts an optional calendar_event_type_id and follows the same rule

v0.35.0 — August 2026

Added the Org Chart endpoint (read:org_chart scope): GET /org-chart returns the organizational chart as a nested tree of person and department boxes, exactly as employees see it (deactivated people are left out and their reports move up)
Department boxes carry a members_count; list the people themselves with the existing GET /users?group_id=. The response meta tells whether the chart is published to employees yet

v0.34.0 — August 2026

POST /walls/{wall_id}/posts accepts an optional bot_user_id — the post is then attributed to that bot user instead of the token's user, matching the direct message endpoint and wall_post incoming webhooks. A non-bot id returns 422

v0.33.0 — August 2026

Forms now carry a due_at date (YYYY-MM-DD, null when unset) — the date by which respondents should have answered, set per form in the CMS and shown in-app to users who have not yet responded (additive)
Form responses mirror it as form_due_at next to form_title — in the response endpoints and the formresponse.* webhook payloads; detail payloads also carry it on the embedded form (additive)

v0.32.0 — August 2026

Bot messages can now be pinned: POST /chat-messages/{id}/pin pins a bot-sent message at the top of its room (optional pinned_until expiry) and DELETE /chat-messages/{id}/pin removes it — one pinned message per room, scope write:chat_messages
Chat message responses (POST /users/{id}/messages and the pin endpoints) now carry nullable pinned_at and pinned_until fields (always present, additive)
Added user management endpoints (write:users scope): POST /users creates an employee — optionally with group memberships and an app invite (send_invite) — and DELETE /users/{id} soft deletes one, mirroring the CMS user management
Creating a user whose email belongs to a deleted account restores that account instead of creating a duplicate; an email in use by an active user is rejected with 422
Only manually created users can be deleted — users synced from an external HR or rota system return 422
Deleted (archived) form responses are now retrievable everywhere: ?include_deleted=1 works on GET /forms/{id}/responses and lets GET /formresponses/{id} return a deleted response instead of 404 (previously bulk-feed only)
Added ?only_deleted=1 to GET /forms/{id}/responses and GET /formresponses to list just the archive — historical form data without paging through live responses
Added Journeys endpoints (read:journeys scope): list journeys, and read per-user journey status — GET /journeys/{id}/users lists everyone a journey is assigned to and GET /users/{id}/journeys lists a user's journeys, each with assigned_at, due_at, completed_at, has_completed and is_overdue
due_at / is_overdue follow the CMS onboarding and offboarding weeks limits; custom journeys carry no deadline (due_at is null). Assignment uses the same user pool as /stats/academy/journeys, so the two surfaces agree

v0.31.0 — July 2026

Form responses now carry a nullable deleted_at field (always present) and an assignees array with the staff members assigned to handle the response — in the response endpoints and the formresponse.* webhook payloads (additive)
The formresponse.updated webhook now also fires when a response is deleted, restored, or permanently deleted — the delivery's deleted_at tells you the response is gone
GET /formresponses accepts ?include_deleted=1 to include deleted (archived) responses, letting a since-based sync catch deletions it missed

v0.30.0 — July 2026

Form responses now include a media array with the files uploaded with the submission (images, videos and documents), each carrying a direct download url — in the response endpoints and the formresponse.* webhook payloads (additive)
On anonymous responses the files are stored encrypted, so url is a short-lived signed link (expires after ~5 minutes) — re-fetch the response for a fresh one

v0.29.0 — July 2026

Users now include first_name and last_name as separate fields alongside name, plus date_of_birth (null unless collected)
hired_at now returns the effective hire date: a manual CMS override wins over the synced value
Users expose manager info: a top-level is_manager flag and a per-membership is_manager flag on each entry in groups[]
Groups returned by the /groups endpoints now include a managers array (id + name) — not included where groups are embedded in other payloads
Docs: corrected the users type example value (default, not user) and documented the existing since filter on users and groups

v0.28.0 — July 2026

Added Staff Cards endpoints (read:staff_cards, write:staff_cards scopes): full CRUD for the informational cards shown in the employee app — mirroring the CMS staff cards management. Cards are created as drafts by default
Cards are targeted via groups (departments, professions and custom groups mixed in one array) and/or individually assigned users; publishing (is_published: true) notifies targeted employees, exactly like the CMS publish button
Cards support a translatable title, an expiry (expires_date/expires_time), manager visibility, and a QR code image via media_ids
Personal cards: type: personal creates a card belonging to exactly one user (no groups) — e.g. a digital business card. qr_data generates a QR code image server-side, attached as media tagged qr_code. List filterable via ?type=
Rich card content is managed through the card's article_id via the articles endpoints — or attach a pre-built standalone article at create time

v0.27.0 — July 2026

Added Forms and Form Responses endpoints (read:forms, read:formresponses scopes): list forms, page through a form's responses, fetch single responses with full context, and a GET /formresponses?since= bulk feed for external dashboards and sync
Detail payloads embed the form, the shared public_comments thread (incl. media attachments), and staff-only internal_comments
The bulk feed's since filters on updated_at — one poll captures new, edited, status-changed, and newly-commented responses. Public comments now bump their response's updated_at, like internal notes already did
Whistleblower forms are completely excluded — never listed, always 404; anonymous responses keep respondent and comment author as null
Form response comment payloads (API and the formresponse.comment.* webhooks) now include a media array with the comment's attachments (additive)

v0.26.0 — July 2026

Added Feedback endpoint: POST /feedback sends feedback on the Open API straight to the Monotree team — feature requests, bug reports, anything. No scope required; any valid token works

v0.25.0 — July 2026

Added Handbooks and Courses endpoints (read:/write:handbooks, read:/write:courses scopes): CRUD for both containers and their chapters — create a draft, add chapters (each owning an article), publish when ready. Publishing notifies targeted employees
Added Articles endpoints (read:articles, write:articles scopes): the shared rich-content structure. Read an article's typed elements and bulk-save the complete element list via PUT /articles/{id}/elements; read-only elements (reference, gif) are never deleted by bulk saves
Element types: paragraph (markdown), header, image_gallery, video_gallery, document — media is referenced from the existing POST /media flow
Added GET /articles/{id}/markdown — any article flattened to a single markdown document (?locale= supported)
Announcements, events, calendar entries and certificates now expose their article_id, so the articles endpoints can manage their rich content too
Articles are fully translatable: every text field carries a field-keyed translations object on read and write — writing a translation activates that locale on the owning content. Handbooks and courses accept the same translations object for their own title/subtitle
The body convenience field on announcements, events and calendar entries now returns 422 instead of silently replacing rich article content. Existing integrations are unaffected: creating with body and updating content whose article was built by body itself keep working unchanged
Create standalone articles via POST /articles and attach them with article_id when creating announcements, events, and calendar entries — content is complete the moment it goes live
Added is_published to POST /announcements and POST /calendar-entries (default true — behavior unchanged): create drafts with is_published: false and publish later via update. Events already supported this

v0.24.0 — July 2026

Added Calendar Event Types endpoints (read:calendar_event_types, write:calendar_event_types scopes): list, create, and update the event types that categorize calendar entries — names are translatable per locale via a translations object
Calendar entries now accept calendar_event_type_id on create and update; when omitted on create, the default event type is used
Calendar entry responses now include the entry's calendar_event_type
PATCH /calendar-entries/{id} is now accepted alongside PUT
Added GET /locales (read:locales scope): the platform's active languages as a map of locale code to name, plus the default content locale — the valid keys for translatable fields

v0.23.0 — June 2026

Added Manager Hub endpoints (read:managerhub scope): the department reporting view from the mobile Manager Hub — team roster (/managerhub/team) and onboarding / journey / course / certificate progress (/managerhub/progress/*)
Every request names the department(s) to report on via a required department_ids parameter; figures share their queries with the in-app Manager Hub so the two surfaces cannot drift
Read-only and department-scoped: the manager-personal action drill-downs and dismiss / snooze state are not exposed

v0.22.0 — June 2026

Added direct messages (write:chat_messages scope): POST /users/{id}/messages sends a direct message to a single user's private chat, delivered by a bot user (the 1:1 room is created on first use and reused afterwards)
New direct_message incoming webhook action — deliver a webhook payload to one user's private chat; a bot user is always the sender
Added Bots endpoints (read:bots, write:bots scopes): create and manage the bot users that send direct messages and power incoming webhooks
Added Incoming Webhook management endpoints (read:incoming_webhooks, write:incoming_webhooks scopes): create, read, update, and revoke incoming webhooks programmatically — the trigger URL and token are returned once on create, and webhooks are scoped to the token that created them

v0.21.0 — June 2026

Added Webhook Management endpoints (read:webhooks, write:webhooks scopes): create, read, update, revoke, activate/deactivate, and test outgoing webhook endpoints programmatically — the same capabilities as the CMS Outgoing Webhooks tab
Choose events per endpoint and optionally filter entity-scoped events (post/comment events by wall, form response events by form)
Configure delivery auth (bearer_token, basic_auth, api_key) and custom headers; secrets, credentials, and header values are encrypted at rest and never returned (fetch the signing secret once via GET /webhooks/{id}/secret)
Endpoints are scoped to the token that created them; removing an endpoint is a revoke (history is preserved), matching the CMS

v0.20.0 — June 2026

Added form response comment webhook events: monotree.formresponse.comment.created, monotree.formresponse.comment.deleted
Fire when a public comment is created or deleted on a form response. Internal staff notes do not trigger webhooks
Filterable by form (select one or more forms when subscribing); whistleblower forms never dispatch
The comment payload's author is null when written by the respondent on an anonymous form — managers/owners are always identified

v0.19.0 — June 2026

Added Certificates endpoints (read:certificates, write:certificates scopes): full CRUD for certificate templates, plus assign, reset/expire, list holders, and a user's certificates
Added Certificate Types endpoints (read:certificatetypes, write:certificatetypes scopes): full CRUD for certificate categories
Assigning mirrors the in-app bulk assignment; "removing" a certificate from a user is the reset/expire operation (history is preserved, matching the platform)
Certificate templates and types are created as drafts by default; pass is_published: true to publish
Update endpoints accept both PUT and PATCH

v0.18.0 — June 2026

Added a status query parameter to list endpoints — published (default), draft, or all — on announcements, events, calendar entries, posts, and surveys
published returns only currently-live content; draft returns unpublished items (including those awaiting a scheduled publish); all returns everything. An unrecognised value returns 422
Breaking: GET /walls/{wall_id}/posts and GET /surveys previously returned drafts; they now return only published content by default. Pass status=draft or status=all to include drafts. (Posts created via the API are published immediately, so this mainly affects draft survey templates.)
Single-item endpoints (GET /{resource}/{id}) are unchanged — they still return an item regardless of its publication state
Certificates are not exposed via the Open API, so the status filter does not apply to them

v0.17.0 — June 2026

Breaking: events are now created as drafts by default. Previously POST /events always published immediately
Added is_published to POST / PUT /events — set true to publish, false to unpublish (back to draft)
Added publish_at to POST / PUT /events — schedule a draft to publish at a future time (mirrors the in-app scheduled publishing). Must be a future timestamp; takes precedence over is_published
Send publish_at: null on update to cancel a pending schedule; scheduling an already-published event returns 422
Event responses now include a scheduled_at field — the time a scheduled draft will go live, or null
Drafts and scheduled events are excluded from GET /events but remain fetchable via GET /events/{id}

v0.16.0 — June 2026

Form response webhook payloads (monotree.formresponse.created, monotree.formresponse.updated) now include choice and user field selections in field_responses — previously those field types were delivered with an empty value
choices fields serialize as an array of { id, title }; users and department_users fields serialize as an array of user objects, matching the respondent shape
Documented the full form response webhook payload, including the per-field-type value shapes

v0.15.0 — June 2026

Added monotree.formresponse.alarm_triggered webhook event (filterable by form)
Fires when a submitted form response matches a configured field alarm rule
Each alarm rule fires its own delivery — idempotent per response + rule pair (never fires twice for the same match)
Payload includes the full form response and the triggered alarm (rule name, operator, value, matched field)
Whistleblower forms are excluded, matching other form response events

v0.14.0 — June 2026

Added Academy statistics endpoints (read:stats scope) that mirror the CMS academy figures
Aggregate: GET /stats/academy/onboarding, GET /stats/academy/courses, GET /stats/academy/journeys (all accept an optional group_ids filter)
Quiz performance: GET /stats/academy/quizzes/{quiz_id} — per-question respondents, passed and pass rate
Per-user progress: GET /stats/academy/users/{user_id}/courses and GET /stats/academy/users/{user_id}/onboarding for HR / LMS integrations

v0.13.0 — May 2026

Added Surveys read endpoints (read:surveys scope): GET /surveys, GET /surveys/{id}
Added Survey answers endpoints keyed by template id: GET /surveys/{template_id}/answers and GET /surveys/{template_id}/answers/{id} — mirrors the CMS Excel export
Each answer embeds its spawn (id + starts_at), question, and choice so consumers can interpret rows without separate lookups
Filters: since, until (created_at), spawn_starts_at; per_page raised to 100 for bulk pulls
Anonymous surveys: spawns below survey_respondents_threshold (default 3) are suppressed entirely, matching the export's privacy contract

v0.12.0 — May 2026

User responses now include an avatar_url field — direct URL to the user's profile picture, or null if none is set
Affects GET /users, GET /users/{id}, and embedded user objects on posts, comments, announcements, events, calendar entries, form responses, and monotree.user.registered / monotree.onboarding.completed webhooks

v0.11.0 — April 2026

Added Media upload endpoints (write:media scope): POST /media and GET /media/{id}
Extended POST /walls/{wall_id}/posts with optional media_ids array — upload first, then attach by id
Incoming webhook wall_post and chat_message actions now accept an optional media array of URL + type pairs (server fetches URLs)
Supported media types: image, video, document. Max 10 per post/message, same type across the batch

v0.10.0 — April 2026

Added monotree.formresponse.updated webhook event (filterable by form)
Fires when a form response's status, deadline, visibility/archive flag, or assignees change
Does not fire on initial creation (use formresponse.created) or on unrelated activity like comments/notes
Whistleblower forms are excluded, matching the existing formresponse.created behavior

v0.9.0 — April 2026

Added Comments CRUD endpoints on posts (read:comments, write:comments scopes)
New endpoints: GET/POST /posts/{post_id}/comments and GET/PUT/DELETE /posts/{post_id}/comments/{id}
Added monotree.comment.created, monotree.comment.updated and monotree.comment.deleted webhook events (filterable by wall)
Comment updates are restricted to the author within 30 minutes of creation

v0.8.0 — April 2026

Outgoing webhooks now support resource filtering — optionally select specific forms or walls per event type
Form response webhooks can be scoped to specific forms (multi-select)
Post created webhooks can be scoped to specific walls (multi-select)
Default remains "all" — no filter means you receive all events of that type
Added filters field to webhook create/update API

v0.7.0 — April 2026

Added Calendar Entries CRUD endpoints (read:calendar_entries, write:calendar_entries scopes)
Create, update, and delete calendar entries with optional body and group targeting
Added Create calendar entry action for incoming webhooks

v0.6.0 — April 2026

Added Events CRUD endpoints (read:events, write:events scopes)
Create, update, and delete company events with date, time, location, and group targeting
Events are automatically published and added to the calendar on creation

v0.5.0 — March 2026

Added Statistics read-only endpoints (read:stats scope)
User summary: total, registered, active and new users (yesterday/7d/30d)
Engagement: time series with active users, app time, sessions — filterable by granularity, period count, and group
Adoption rate: per-department active/total employees percentage — filterable by group
Content activity: posts, comments, reactions, chat messages, completed todos — this week vs last week
All statistics responses are cached server-side (1h–24h) for performance

v0.4.0 — March 2026

Added Walls read-only endpoints with group associations (read:walls scope)
Post endpoints now nested under walls: /walls/{wall_id}/posts
Added Timestamp header to outgoing webhooks for replay attack prevention
Webhook signatures now include the timestamp: HMAC-SHA256(timestamp + "." + payload, secret)
Added bot user avatars for incoming webhooks (defaults to app icon)
Outgoing webhooks now use revoke instead of delete
Incoming webhooks now use unified text field for all actions
Added Pagination section to documentation with meta and links format
Added incoming webhook rate limiting documentation

v0.3.0 — March 2026

Added Users read-only endpoints (read:users scope)
Added Groups read-only endpoints (read:groups scope)
Added monotree.user.registered webhook event
Added monotree.onboarding.completed webhook event
Added monotree.formresponse.created webhook event
Added IP whitelist per token
Added configurable rate limit with rate limit response headers
Added usage counters on tokens, outgoing webhooks, and incoming webhooks
Added content author selection (bot user or yourself) on incoming webhooks
Added Test Webhook buttons for outgoing and incoming webhooks
Added signature verification documentation with Node.js example

v0.2.0 — March 2026

Added Announcements CRUD endpoints (read:announcements, write:announcements scopes)
Added Create post on wall action for incoming webhooks
Added monotree.announcement.published webhook event

v0.1.0 — March 2026

Initial beta release of the Open API
Bearer token authentication with scoped permissions
Posts CRUD endpoints (read:posts, write:posts scopes)
Outgoing webhooks with HMAC-SHA256 signing for post events
Incoming webhooks for sending messages to chat rooms
API request logging and webhook delivery logging
Rate limiting at 60 requests per minute per token
CMS admin interface for managing tokens, webhooks, and logs