Events
BlueSuite MCP tools for events
See connection and authentication and workflow rules before calling these tools.
Related REST API and behavior.
List events (appointments, tasks, visits) with optional pagination, search, and filters
| Field | Type / accepted values | Required | Details |
|---|
page | integer | No | Page number (default: 1) |
per_page | integer | No | Results per page (default: 25) minimum: 1. maximum: 100. |
search | string | No | Search events |
sort_by | "id", "name", "status", "type", "start_date", "end_date", "created_at", "modified_at" | No | Field to sort by. Unknown values fall back to the default sort. |
sort_direction | "asc", "desc" | No | Sort direction |
start_date | string | No | Filter: start date (YYYY-MM-DD) |
end_date | JSON value | No | Filter: end date (YYYY-MM-DD) |
job_id | integer | No | Filter by job ID |
type | "appointment", "task", "event" | No | Filter by event type |
assignee_ids | array of string | No | Filter by assignee UUIDs. Use list_users to resolve names to UUIDs. |
status | array of "pending", "in_progress", "scheduled", "cancelled", "missed", "completed" | No | Filter by one or more statuses. |
request_id | JSON value | No | Filter by request ID |
| Field | Type / accepted values | Required | Details |
|---|
data | array of object | Yes | The matching records for this page. |
pagination | object | No | How many more pages of results exist. Absent when the API returned an unpaged result. |
pagination.page | integer | When parent supplied | Current page number, 1-based. |
pagination.per_page | integer | When parent supplied | Number of results per page. |
pagination.total_pages | integer | When parent supplied | Total number of pages available. |
Create a new event. Three kinds: an APPOINTMENT is a visit for an existing job or request, a TASK is a to-do on the calendar, an EVENT is a standalone calendar entry. Recurrence (recurrence_type="recurring") applies to tasks and events only, appointments cannot repeat on their own. For repeating visits, put the job on a recurring schedule with setup_recurring_job, which also sets the job type and billing settings.
| Field | Type / accepted values | Required | Details |
|---|
name | string | No | Event name/title |
description | string | No | Event description |
job_id | integer | No | Associated job ID |
request_id | JSON value | No | Associated request ID |
start_date | string | Yes | Start date (YYYY-MM-DD) |
end_date | JSON value | Yes | End date (YYYY-MM-DD) |
start_time | string | No | Start time (HH:MM) in workspace timezone. Required for timed events; omit only for all_day=true or an update retaining the saved time. |
end_time | JSON value | No | End time (HH:MM) in workspace timezone, after the start. Required for timed events; omit only for all_day=true or an update retaining the saved time. |
all_day | boolean | No | Whether this is an all-day event (default: false) |
multi_day | JSON value | No | Whether this spans multiple days (default: false) |
type | "appointment", "task", "event" | No | Event type (default: event) |
status | "scheduled", "cancelled", "missed", "completed" | No | Event status (default: scheduled) |
is_flexible | JSON value | No | Whether the visit can be moved within the day by scheduling. |
duration_minutes | integer | No | Expected length of the visit in minutes. |
recurrence_type | "single", "recurring" | No | Set to 'recurring' for a repeating task or standalone event. Default: 'single'. NOT valid for type='appointment', repeating visits come from setup_recurring_job. The repeat_* fields below only apply when this is 'recurring'. |
repeat_frequency | JSON value | No | Interval between occurrences, used when repeat_frequency_unit is 'custom' (e.g. 2 with a custom weekly unit means every 2 weeks). |
repeat_frequency_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | How often it repeats: daily, weekly, monthly, yearly, or 'custom' to combine repeat_frequency with repeat_frequency_unit_custom. Default: weekly. |
repeat_frequency_unit_custom | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | The unit the custom interval counts in. Only used when repeat_frequency_unit is 'custom'. |
repeat_frequency_schedule | object | No | Which days a custom weekly or monthly pattern lands on. Required for those patterns. |
repeat_frequency_schedule.days | array of JSON value | When parent supplied | Days to repeat on: 1-7 for weekdays, 1-31 for days of the month. |
repeat_frequency_schedule.type | "weekDays", "monthWeekDays", "monthDays" | When parent supplied | |
repeat_duration | JSON value | No | How long the series runs. With repeat_duration_unit='occurrences' this is a visit count. Required unless the series repeats forever. |
repeat_duration_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | How the series ends: 'forever' (no end), 'occurrences' (a fixed number of visits, set in repeat_duration), or a time unit. Default: forever. |
assignee_ids | array of string | No | Array of assignee UUIDs. Use list_users to resolve names. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Get a single event by ID with expanded details
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Event ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Update an existing event. For an occurrence of a recurring appointment, set update_scope to say whether the change applies to just this visit, all future visits, or should rebuild the upcoming schedule.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Event ID |
name | string | No | Event name/title |
description | string | No | Event description |
job_id | JSON value | No | Associated job ID |
request_id | JSON value | No | Associated request ID |
start_date | string | No | Start date (YYYY-MM-DD) |
end_date | JSON value | No | End date (YYYY-MM-DD) |
start_time | string | No | Start time (HH:MM) in workspace timezone. Required for timed events; omit only for all_day=true or an update retaining the saved time. |
end_time | JSON value | No | End time (HH:MM) in workspace timezone, after the start. Required for timed events; omit only for all_day=true or an update retaining the saved time. |
all_day | boolean | No | Whether this is an all-day event |
multi_day | JSON value | No | Whether this spans multiple days |
type | "appointment", "task", "event" | No | Event type |
status | "scheduled", "cancelled", "missed", "completed" | No | Event status |
is_flexible | JSON value | No | Whether the visit can be moved within the day by scheduling. |
duration_minutes | integer | No | Expected length of the visit in minutes. |
recurrence_type | "single", "recurring" | No | Set to 'recurring' for a repeating task or standalone event. Default: 'single'. NOT valid for type='appointment', repeating visits come from setup_recurring_job. The repeat_* fields below only apply when this is 'recurring'. |
repeat_frequency | JSON value | No | Interval between occurrences, used when repeat_frequency_unit is 'custom' (e.g. 2 with a custom weekly unit means every 2 weeks). |
repeat_frequency_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | How often it repeats: daily, weekly, monthly, yearly, or 'custom' to combine repeat_frequency with repeat_frequency_unit_custom. Default: weekly. |
repeat_frequency_unit_custom | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | The unit the custom interval counts in. Only used when repeat_frequency_unit is 'custom'. |
repeat_frequency_schedule | object | No | Which days a custom weekly or monthly pattern lands on. Required for those patterns. |
repeat_frequency_schedule.days | array of JSON value | When parent supplied | Days to repeat on: 1-7 for weekdays, 1-31 for days of the month. |
repeat_frequency_schedule.type | "weekDays", "monthWeekDays", "monthDays" | When parent supplied | |
repeat_duration | JSON value | No | How long the series runs. With repeat_duration_unit='occurrences' this is a visit count. Required unless the series repeats forever. |
repeat_duration_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | How the series ends: 'forever' (no end), 'occurrences' (a fixed number of visits, set in repeat_duration), or a time unit. Default: forever. |
update_scope | "single", "all", "recreate" | No | Which occurrences of a recurring appointment this update touches. 'single' changes only this visit, 'all' applies to this and future visits, 'recreate' rebuilds the upcoming schedule after a pattern change. Default: single. Ask the user which they mean rather than guessing. |
assignee_ids | array of string | No | Array of assignee UUIDs. Use list_users to resolve names. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Set the line items for ONE visit of a job, so that visit bills differently from the rest, the parts used on this trip, an extra callout. When the appointment is completed, its invoice is built from these instead of the job's line items; discount, tax and deposit still come from the job. Send line_items as null to clear the override and bill from the job again. This affects only the single visit, never the whole recurring schedule.
| Field | Type / accepted values | Required | Details |
|---|
event_id | integer | Yes | The appointment (visit) to price. |
line_items | array of object or object or null | Yes | Line items for this visit only, or null to go back to billing from the job. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Delete an event by ID
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Event ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Update only the status of an event. Use this instead of update_event when changing status, as status transitions may trigger business logic.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Event ID |
status | "scheduled", "cancelled", "missed", "completed" | Yes | New status |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
The downloadable tool schemas include the full input and output contracts. Tables describe schema-level required fields; cross-field rules still apply.