Skip to content
Optiwork API Docs

Update an event

PATCH
/events/{eventId}
curl --request PATCH \
  --url https://calendar.work.optidata.cloud/api/events/4167 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": "4167", "inv_id": "4167-4166", "ms": 20125, "rev": 20120, "calendar_id": "10", "title": "Sprint review — August", "datetime_start": "2026-08-24 14:00:00", "datetime_end": "2026-08-24 15:00:00", "is_all_day": false, "location": "Meeting room 2", "organizer": "jane.doe@acme.example", "attendees": [ { "email": "john.smith@acme.example", "type": "user", "optiworkIdentifier": "9ef34ce3-3b69-4762-b5e8-045499390ce6" } ], "attendees_to_add": [ { "email": "sam.lee@acme.example", "type": "user", "optiworkIdentifier": "9f0021bb-5c2f-4a71-9c0e-6f2ad4c1e777" } ], "should_notify_all_attendees": true }'

Rewrites an event. Read it first, change what you need and send the whole record back — the fields you omit are not preserved.

id, inv_id, ms, rev and calendar_id must come from the event you just read. Moving the event to another calendar means sending the new calendar_id together with the old one in original_calendar_id.

Attendee changes are a delta, like calendar sharing: attendees_to_add and attendees_to_remove decide who gets invited or uninvited, while attendees restates the current guest list. Set should_notify_all_attendees to false to change the event without e-mailing everybody who was already on it.

An edit that touches only the event itself — a rename, a new location, a new time — still reaches the people already invited: their calendars are updated and they are notified that the event changed.

To change only the start and end, prefer POST /events/{eventId}/reschedule, which needs far less of the record.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
eventId
required
string

Id of the event, as returned in an event’s id.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
title
required
string
datetime_start
required

When the event starts. Interpreted in the caller’s display time zone unless it carries an offset.

string
datetime_end
required

When the event ends. Must not be before datetime_start.

string
is_all_day
required

true for an event that spans whole days; send midnight-to-midnight bounds.

boolean
description
string | null
location
string | null
video_conference_url

Meeting room to attach to the event.

string | null format: uri
organizer
required

Address of the organizer.

string format: email
notification
One of:

A single reminder. Send time_unit and value for a timed event, or days_before and trigger_hour for an all-day one. Omit the object entirely for an event with no reminder.

object
time_unit

Unit of the lead time, for a timed event.

string
Allowed values: minutes hours days weeks
value

How many units before the start to fire the reminder.

integer
days_before

How many days before the event to fire it, for an all-day event.

integer
trigger_hour

Hour of the day the reminder fires, for an all-day event.

integer
<= 23
locale

Language for the invitation e-mails, e.g. pt_BR or en.

string | null
id
required

Id of the event, from the record you read.

string
inv_id
required

Invitation id, from the record you read.

string
ms
required

Modification sequence, from the record you read.

integer
rev
required

Revision, from the record you read.

integer
calendar_id
required

Calendar the event should live in after the update.

string
original_calendar_id

Calendar the event is in now. Send it when calendar_id moves the event elsewhere.

string | null
event_uid

ICalendar UID of the event.

string | null
recurrence_id

Start of the occurrence being edited, when the update targets one occurrence of a series.

string | null
attendees

The current guest list.

Array<object>

Somebody to invite.

object
email
required
string format: email
name

Display name of the attendee. Mainly useful for somebody outside the tenant, who has no directory entry to take a name from.

string | null
type
One of:

user is somebody with an Optiwork account in the tenant, group a user group, and guest an address outside it.

string
Allowed values: user guest group
optiworkIdentifier

Optiwork identifier of the attendee, from GET /search/invitables. null for somebody outside the tenant.

string | null
attendees_to_add

People to invite.

Array<object>

Somebody to invite.

object
email
required
string format: email
name

Display name of the attendee. Mainly useful for somebody outside the tenant, who has no directory entry to take a name from.

string | null
type
One of:

user is somebody with an Optiwork account in the tenant, group a user group, and guest an address outside it.

string
Allowed values: user guest group
optiworkIdentifier

Optiwork identifier of the attendee, from GET /search/invitables. null for somebody outside the tenant.

string | null
attendees_to_remove

People to uninvite.

Array<object>

Somebody to invite.

object
email
required
string format: email
name

Display name of the attendee. Mainly useful for somebody outside the tenant, who has no directory entry to take a name from.

string | null
type
One of:

user is somebody with an Optiwork account in the tenant, group a user group, and guest an address outside it.

string
Allowed values: user guest group
optiworkIdentifier

Optiwork identifier of the attendee, from GET /search/invitables. null for somebody outside the tenant.

string | null
should_notify_all_attendees

Whether everybody already on the event is e-mailed about the change. Defaults to true.

boolean | null
recurrence_rule
One of:

How an event repeats, in iCalendar terms. frequency is the only required part; count and until are two ways of ending the series, and the by_* fields narrow which occurrences the frequency produces.

When a by_* field is omitted, it is inferred from datetime_start — a weekly series repeats on the weekday it starts on, a monthly one on the same day of the month.

object
frequency

How often the event repeats.

string
Allowed values: DAILY WEEKLY MONTHLY YEARLY
interval

Repeat every N periods: 2 with WEEKLY means fortnightly.

integer | null
>= 1 <= 99
count

End the series after this many occurrences.

integer | null
>= 1 <= 999
until

End the series at this moment.

string | null
by_day

Weekdays the event falls on.

Array<string> | null
Allowed values: SU MO TU WE TH FR SA
by_month_day

Days of the month, 1–31.

Array<integer> | null
by_month

Months, 1–12.

Array<integer> | null
by_set_pos

Which occurrence within the period: 1–4 for first through fourth, -1 for last. Combine with by_day for “the last Friday of the month”.

Array<integer> | null
Allowed values: 1 2 3 4 -1
Examples
Exampleretitle

Rename and add one guest

{
  "id": "4167",
  "inv_id": "4167-4166",
  "ms": 20125,
  "rev": 20120,
  "calendar_id": "10",
  "title": "Sprint review — August",
  "datetime_start": "2026-08-24 14:00:00",
  "datetime_end": "2026-08-24 15:00:00",
  "is_all_day": false,
  "location": "Meeting room 2",
  "organizer": "jane.doe@acme.example",
  "attendees": [
    {
      "email": "john.smith@acme.example",
      "type": "user",
      "optiworkIdentifier": "9ef34ce3-3b69-4762-b5e8-045499390ce6"
    }
  ],
  "attendees_to_add": [
    {
      "email": "sam.lee@acme.example",
      "type": "user",
      "optiworkIdentifier": "9f0021bb-5c2f-4a71-9c0e-6f2ad4c1e777"
    }
  ],
  "should_notify_all_attendees": true
}

Responses

Section titled “ Responses ”

200

Section titled “200”

The updated event.

Media typeapplication/json
object
event
required

An event and its occurrences. The event itself carries the identifiers; everything about the schedule lives in instances.

object
id
string | null
uid

ICalendar UID. Unlike id, it survives the event being copied between calendars.

string | null
calendarId
required

Calendar the event lives in.

string
originalCalendarId
string | null
invId

Invitation id. Part of the concurrency triple you send back on an update.

string | null
ms

Modification sequence. Send it back unchanged on an update.

integer | null
rev

Revision. Send it back unchanged on an update.

integer | null
nextAlarm
One of:

The next reminder due for the event.

object
nextAlarmAt

When the reminder fires.

string | null
alarmInstStart

Start of the occurrence it belongs to.

string | null
invId
integer | null
instances
required
Array<object>

One occurrence of an event. A one-off event has exactly one; a recurring event has one per occurrence inside the window you asked for.

object
id
string | null
invId

Invitation id. Send it back when updating or rescheduling.

string | null
status
required

CONF confirmed, TENT tentative, CANC cancelled, NEED awaiting an answer.

string
Allowed values: CONF TENT CANC NEED
recurrenceId

Start of this occurrence, for a recurring event.

string | null
name

Title of the event.

string | null
location
string | null
start
required
string
end
required
string
isOrganizer
required

true when the caller owns the event.

boolean
isRecurring
required
boolean
isException
required

true when this occurrence was detached from its series.

boolean
isAllDay
required
boolean
videoConferenceUrl
string | null
description

Filled in on a single-event read; on a list, only when include_description was requested.

string | null
organizer
One of:

Who owns the event.

object
email
string | null
name
string | null
type
One of:

user is somebody with an Optiwork account in the tenant, group a user group, and guest an address outside it.

string
Allowed values: user guest group
avatarUrl
string | null
sentBy

Set when somebody sent the invitation for the organizer.

string | null
recurrenceRule
One of:

The repetition rule as stored. Mirrors the rule you send, in camelCase.

object
frequency
string
Allowed values: DAILY WEEKLY MONTHLY YEARLY
until
string | null
count
integer | null
interval
integer | null
byDay
Array<string> | null
byMonthDay
Array<integer> | null
byMonth
Array<integer> | null
bySetPos
Array<integer> | null
userParticipationStatus
One of:

How an attendee answered. NEEDS-ACTION means they have not answered yet.

string
Allowed values: NEEDS-ACTION ACCEPTED DECLINED TENTATIVE
originalTimezone

Time zone the event was created in, when it differs.

string | null
recurrenceBaseStart
string | null
recurrenceBaseEnd
string | null
attendees
required
Array<object>

Somebody invited to the event.

object
email
string | null
name
string | null
type
One of:

user is somebody with an Optiwork account in the tenant, group a user group, and guest an address outside it.

string
Allowed values: user guest group
avatarUrl
string | null
participationStatus
One of:

How an attendee answered. NEEDS-ACTION means they have not answered yet.

string
Allowed values: NEEDS-ACTION ACCEPTED DECLINED TENTATIVE
optiworkIdentifier
string | null
alarms
required
Array<object>

A reminder, expressed as an offset from the event. isNegative: true means the reminder fires before the moment named by related; the unit fields that do not apply are 0 or null.

object
description
string | null
related

Whether the offset is measured from the start or the end.

string | null
Allowed values: START END
isNegative
boolean
weeks
integer | null
days
integer | null
hours
integer | null
minutes
integer | null
seconds
integer | null
locale
string | null
participantsSummary

Who takes part in one occurrence, summarized for an event card. Present only on a list (GET /events) called with include_participants_summary=true; absent otherwise.

The participants are listed as the event details show them: the organizer first, when the occurrence has one, then the attendees in invitation order. The organizer is not looked up among the attendees, so an organizer who is also listed as an attendee counts twice. An exception occurrence is summarized from its own participants.

Even with the flag on, an occurrence can lack participantsSummary when its participants could not be read, for instance when the event was deleted while the list was being built. Read a missing participantsSummary as unknown, not as zero participants.

object
participantsCount
required

Number of participants of the occurrence: the organizer, when there is one, plus every attendee. 0 when it has none.

integer
participants
required

The first three participants, in the order above. Empty when the occurrence has none.

Array<object>
<= 3 items
object
name
required

The participant’s name or, when it has none, their email address. null when both are missing.

string | null
avatarUrl
required

The participant’s avatar, or null when there is none.

string | null
Example
{
  "event": {
    "id": "4167",
    "calendarId": "10",
    "instances": [
      {
        "status": "CONF",
        "organizer": {
          "type": "user"
        },
        "recurrenceRule": {
          "frequency": "DAILY"
        },
        "userParticipationStatus": "NEEDS-ACTION",
        "attendees": [
          {
            "type": "user",
            "participationStatus": "NEEDS-ACTION"
          }
        ],
        "alarms": [
          {
            "related": "START"
          }
        ],
        "participantsSummary": {
          "participantsCount": 5,
          "participants": [
            {
              "name": "Jane Doe"
            }
          ]
        }
      }
    ]
  }
}

401

Section titled “401”

Missing, malformed or expired authentication key.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Examplemissing

No bearer token sent

{
  "error": "JWT passport exception: Missing bearer token in request"
}

403

Section titled “403”

The caller is not the organizer of the event, or lacks write access to the calendar it lives in.

Media typeapplication/json

Failures raised by the calendar layer itself — a permission refusal, or a calendar or event that cannot be read. help is a hint for the end user and is often empty.

object
error
required

What went wrong.

string
status
required

Repeats the HTTP status code.

integer
help
required

Suggested next step, or an empty string.

string
Examples
ExamplenotOrganizer
{
  "error": "Only the event organizer can change this event.",
  "status": 403,
  "help": "Ask the organizer to make this change for you."
}

422

Section titled “422”

The request body or query string failed validation.

Media typeapplication/json
object
message
required

The first validation message.

string
errors
required

Validation messages keyed by field name.

object
key
additional properties
Array<string>
Examples
Exampleinvalid
{
  "message": "The event title field is required.",
  "errors": {
    "title": [
      "The event title field is required."
    ]
  }
}

429

Section titled “429”

Rate limit exceeded. Retry after the window resets.

Media typeapplication/json

Generic error envelope used by policy, binding and framework failures.

object
message
required

Human-readable description of the failure.

string
Examples
Examplethrottled
{
  "message": "Too Many Attempts."
}