Events

Events are company calendar events with date, time, location, and optional group targeting.

Required scope: read:events, write:events.

Publication state

Events have a publication lifecycle so you can stage content for review before it goes live — useful when an automated process (e.g. an AI assistant) drafts events that a human approves later.

An event is always in one of three states:

State	`is_published`	`published_at`	`scheduled_at`	Visible to employees
Draft	`false`	`null`	`null`	No
Scheduled	`false`	`null`	future timestamp	No (until the scheduled time)
Published	`true`	timestamp	`null`	Yes

By default, GET /events lists only published events. Pass ?status=draft to list drafts and scheduled events, or ?status=all for everything (an unrecognised value returns 422). Any event can also be fetched directly with GET /events/{id} regardless of state.

Endpoints

GET

/api/open/v1/events

List events (published by default, paginated)

GET

/api/open/v1/events/{id}

Get a single event (including drafts and scheduled)

POST

/api/open/v1/events

Create an event (draft by default)

PUT

/api/open/v1/events/{id}

Update an event, including its publication state

DELETE

/api/open/v1/events/{id}

Delete an event (returns 204)

Create

By default the event is created as a draft:

curl -X POST https://customer.monotree.com/api/open/v1/events \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Team Building Day",
    "body": "Join us for a fun day of activities.",
    "starts_at": "2026-05-01",
    "starts_time": "09:00",
    "ends_at": "2026-05-01",
    "ends_time": "17:00",
    "location": "Main Office",
    "groups": [1, 3]
  }'

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

To publish straight away, add "is_published": true. To schedule publication for a future time, add "publish_at": "2026-04-28T08:00:00+00:00".

Request body

Field	Type	Notes
`title`	string	Required.
`body`	string	Required. Description, stored as the event article.
`starts_at`	date (`YYYY-MM-DD`)	Required.
`starts_time`	time (`HH:MM`)	Optional.
`ends_at`	date (`YYYY-MM-DD`)	Optional. Must be on or after `starts_at`.
`ends_time`	time (`HH:MM`)	Optional.
`location`	string	Optional.
`groups`	array of integers	Optional. Group IDs to target.
`is_published`	boolean	Optional. `true` publishes the event immediately. Defaults to `false` (draft).
`publish_at`	datetime (ISO 8601)	Optional. Schedules publication for a future time. Must be in the future. Takes precedence over `is_published`.

Update

PUT accepts the same fields as create. All fields are optional — only what you send is changed.

Use the publication fields to move an event between states:

Publish a draft now: { "is_published": true }
Unpublish (back to draft): { "is_published": false }
Schedule a draft: { "publish_at": "2026-04-28T08:00:00+00:00" } (the event must be a draft — scheduling an already-published event returns 422)
Cancel a pending schedule: { "publish_at": null } (keeps the event a draft)

curl -X PUT https://customer.monotree.com/api/open/v1/events/789 \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "is_published": true }'

Response

{
  "data": {
    "id": 789,
    "article_id": 92,
    "title": "Team Building Day",
    "body": "Join us for a fun day of activities.",
    "starts_at": "2026-05-01",
    "starts_time": "09:00",
    "ends_at": "2026-05-01",
    "ends_time": "17:00",
    "location": "Main Office",
    "author": { "id": 1, "name": "John Doe", "email": "john@example.com", "avatar_url": "https://images.monotree.com/avatars/john-doe.jpg" },
    "groups": [
      { "id": 1, "name": "All Staff", "type": "custom", "created_at": "2026-01-15T10:00:00+00:00" }
    ],
    "is_published": false,
    "comments_count": 0,
    "completions_count": 0,
    "published_at": null,
    "scheduled_at": null,
    "created_at": "2026-04-20T10:00:00+00:00",
    "updated_at": "2026-04-20T10:00:00+00:00"
  }
}

Field	Type	Notes
`is_published`	boolean	Whether the event is published and visible to employees.
`published_at`	datetime or `null`	When the event was published. `null` for drafts and scheduled events.
`scheduled_at`	datetime or `null`	When a scheduled draft will be published. `null` unless a publication is scheduled.

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