Events

Get the stored events that changed after a cursor, oldest first. Use it to keep a copy of the events in sync. Scope: events:read.

• On the first poll, do not send cursor.
• Each response has a cursor. Send it as cursor on the next poll. Do not change or parse it.
• A cursor that this API did not write returns 422 validation.
• limit is 1 to 500. The default is 100. Other values return 422.
• When hasMore is true, more rows wait. Send the next poll at once.
• The cursor holds the exact position of the last row. A page boundary does not skip or repeat a row.
• When no event changed, the response has no rows and a cursor that you can send again.

The rows are different from the event model:

• The response has one row for each stored event. It does not expand a recurring event into its occurrences.
• A changed occurrence is a separate stored event. Its row has the stored id of that event, not seriesId@<original date>. No other read gives this id. GET /events/{id} with it returns the occurrence with the id seriesId@<original date>.
• The response does not show deleted events.
• A row has only id, name, start, end, recurrence (for a series), areaId, activityTypeId, and updatedAt. updatedAt is an ISO 8601 instant.
• An event with no name has the name "(untitled)".

To read a day, use GET /schedule.

Response fields

Responses

Create, change, move, reflect, and delete events. This route is the one event write of the API. Send 1 to 50 ops, and an optional partial. Scope: events:write.

Ops

Each op has an op field with its name.

Examples of tasks

Rules of the fields

• areaId and activityTypeId take an id or null. On update, null removes the link, and an omitted key keeps the link. On create, null and an omitted key are the same.
• On create, kind is a manual choice, also the default blocking. AI classification does not change it.
• On create, an areaId or an activityTypeId that you send is a manual choice. A field with no id stays open for AI classification.
• On update, areaId: null or activityTypeId: null is a manual choice of no link. AI classification does not fill that field again, also when it was already empty.
• projectId takes the id of a live project from the projects list of GET /schedule. On update, null removes the project and keeps the area. An omitted key keeps the project. On create, null and an omitted key are the same.
• When an op sets a new project and no areaId, the event takes the area of the project. This also replaces an area that you set before. It also applies to an op on an occurrence id.
• An unknown project, or an archived project, fails the row with not_found: No live project with id "<id>". An archived project that the event already has can stay.
• On an event from a task of a task app, a new projectId that needs a move of the task fails with read_only: A scheduled task keeps the project of its list. Change the project in the Inbox. Change the project in the Inbox.
• priority is a whole number from 0 to 4. On create, an omitted priority is 0. On update, an omitted priority keeps the value.
• An undo puts back the project, the priority, and the area of the event.
• On an event that came from a task of a task app, a priority change can also go to the task in its app. Reassign sends it only after a pull of the task records its priority. Refer to Backlog.
• calendarId is the home calendar. On create, send null to keep the event only on the dial. When you omit it, the event goes to the default calendar of the account, if one is set. Otherwise it stays on the dial only. mirrorCalendarIds lists the calendars that get a one-way copy. On update, [] removes all copies.
• On update, an omitted calendarId keeps the home calendar. mirrorCalendarIds checks only the ids that the op adds. An id that is already on the event can stay, also when its calendar is now read-only or disconnected.
• On update, calendarId: null removes the event from its home calendar. It also deletes all the copies in mirrorCalendarIds. The event then stays on the dial only.
  • Send it with the bare series id and no scope. An occurrence id or a scope is a validation error.
  • It can carry start, end, name, notes, areaId, activityTypeId, projectId, priority, and kind. These edits apply first, in the same write.
  • With mirrorCalendarIds, mirrorStyles, recurrence, recurrenceEnd, sourceUrl, or focusIntervals, it is a validation error. Send that change in a separate op.
  • On an event that is already on the dial only, calendarId: null is not a change. The copies stay. To remove them, send mirrorCalendarIds: [].
• A one-off event on the dial only can have copies. On create, send calendarId: null with mirrorCalendarIds.
• A series with copies needs a home calendar. These ops fail with validation and the message Copies of a series need a home calendar. Give the series a calendarId, or remove its mirrorCalendarIds.:
  • A create with recurrence, mirrorCalendarIds, and calendarId: null. An omitted calendarId also fails when the account has no default calendar.
  • An update that adds recurrence to a dial-only event with copies.
  • An update that adds mirrorCalendarIds to a dial-only series.
• A series that came from a connected calendar is an exception. After calendarId: null, Reassign keeps the identity of the calendar series. An update can then add mirrorCalendarIds. A read does not show this identity.
• mirrorStyles sets how much each copy shows. Refer to Copy styles.
• On update, sourceUrl: null removes the link, recurrence: null stops the repeat, and focusIntervals: null removes the focus rhythm.
• recurrenceEnd needs recurrence. focusIntervals is valid only on a blocking event.
• recurrence, calendarId, mirrorCalendarIds, mirrorStyles, and sourceUrl belong to the full series. On one occurrence, the same value as now is not a change. A new value is an error.
• An update that moves a series to another day needs a rule that occurs on that day.
• The API rejects a key that it does not know, and a key that has no effect.

Copy styles

mirrorStyles maps a copy calendar id to a style. A read gives it only when the event has a style. Use busy to block the time on a second calendar and hide the details.

• Each key must be in the mirrorCalendarIds of the op. When an update has no mirrorCalendarIds, the current copies apply. Else the op fails with validation: mirrorStyles has calendar "<id>", which is not in the event's mirrorCalendarIds. Add it to mirrorCalendarIds, or remove it from mirrorStyles.
• A value that is not full, private, or busy fails the schema check with validation. The row has error.issues with a path of ["mirrorStyles", "<id>"]. Refer to Validation errors.
• On create, {} is the same as no map. On update, mirrorStyles replaces the map. {} removes all styles.
• A calendar that is not in the map uses the default style of that calendar. Without a default, the style is full. GET /schedule gives the default as integrations.sources[].calendars[].copyStyle.
• A private or busy copy of a non_blocking or reference event shows as free.
• The style belongs to the full series. On an occurrence id or with scope, a new value fails with validation.
• A changed occurrence inherits the styles of its series.

The reflect op

• The occurrence must be on a past day in the account's time zone. Today and future days fail with validation, even when today's event has already ended.
• actualStart and actualEnd go together. Send them only with changed or added.
• With added, the actual times become the time of the event. actualStart must be on the day of the event.
• To mark one occurrence of a series, send its occurrence id. A bare series id is an error.
• The actual span must be from 5 minutes to 168 hours. Else the row fails with Event is too short (minimum 5 minutes). or Event is too long (maximum 168 hours).

Order and batch rules

• The API applies the ops in their order. An op sees the result of the ops before it. For example, a delete frees the time for a later create.
• The API reads the result rows after all ops commit. Thus a later op can change the row of an earlier op, for example a scope: "future" split.
• An op can target an event id one time only in each call. A second op on the same id is an error row.
• A call can have one scope: "future" op for each series. It cannot also have an op on the bare series id. The later op is a validation error row.
• A scope: "future" update also changes an overridden occurrence on the split date. With a new start or end, it replaces that override with the new series occurrence. With other fields, it applies those fields to the override, keeps its own time, and returns that occurrence. Later overrides keep their individual fields.
• A scope: "future" split of a dial-only series with copies gives the new series no copies and no mirrorStyles. The old series keeps its copies.
• A blocking event that overlaps another blocking event fails with conflict. The error row has conflicts. It can also have up to 3 nearestSlots.
• A non_blocking or reference event can overlap other events. It does not cause a conflict.

Atomic and partial batches

By default, the batch is atomic. When one op fails, the API applies no op. Each valid op then has status: "skipped" and a reason.

With partial: true, the API applies each op that it can. The failed ops are error rows.

• When one or more ops apply, the status is 200. The body has results, and undoToken with expiresAt when the server recorded an undo receipt.
• Reassign does not reject a batch after its writes land. When the read of a written op fails after the write, that op is an error row with the code internal and the message The change was saved, but the read-back failed. Read it again. The body keeps any recorded undoToken.
• When no op applies, the body is the error envelope and results. The status follows error.code, as the Responses table shows.

The top-level timezone is there only when a row has a span: a created or updated event, conflicts, or nearestSlots. For example, a batch of only delete or clear ops has no timezone.

A batch where no op applies is a rejected batch. This is also true for partial: true when all ops fail. The error.message of a rejected batch is the message of the one failed op. When more ops fail, it tells you to look in results. A rejected batch has no undoToken.

Rows

Each item of results has index (0-based), status (ok, error, or skipped), and one of result, error, or reason.

An ok row can also have warnings: ["classification_pending"]. The write succeeded and queued AI classification. AI classification can fill eligible fields after the reply, for example an area that you did not set. It does not change the kind of a create, or an areaId or activityTypeId that a create sent. This warning appears only when the account and plan allow classification. Read the event again if you need its latest classification.

An op that the API cannot read does not fail the full request. It becomes an error row with the code validation. The message names the problem, for example an unknown op or a bad field. The full request fails with 422 only when the body is not valid, for example when ops is empty or has more than 50 items. These items are also error rows:

Each of these rows also has error.issues. Refer to Validation errors.

Undo

A write that records an undo receipt returns one undoToken and its expiresAt (30 minutes) at the top level. Send the token to POST /actions/undo to reverse the full write. Refer to Scheduling. A write that changes nothing has no undoToken. If the server cannot record the undo, the response also has no undoToken, and the change stays. Thus, a response with no undoToken does not prove that nothing changed.

Request body

Response fields

Responses

Most error responses: When no op of the batch applied, the body also has the results rows, so the caller sees which op failed.

Get one event and the timezone of its span. Scope: events:read.

• A one-off event: send its id.
• One occurrence of a series: send the occurrence id seriesId@YYYY-MM-DD.
• A bare series id returns 404 not_found. The API looks for the id in the events of the first day of the series, and there each occurrence has an occurrence id.
• A changed occurrence keeps its id seriesId@<original date>. This id finds the occurrence also after a move to another day.
• A stored id of a changed occurrence from an older write result also works. The response then gives event.id as seriesId@<original date>.
• An unknown id returns 404 with the message Event not found.

Response fields

Responses

Find events by name. The search does not look in the notes. Scope: events:read.

• query is required. An empty value returns 422 validation.

• The default window is from 7 days before today to 30 days after from (or after today).

• With only to, the window starts 7 days before today. If to is less than 30 days after that start, the window starts 30 days before to. If the window is then more than 92 days, it starts 91 days before to.

• A to before from returns 422 with the message `to` must be on or after `from`.

• The window is 92 days or less. A wider window returns 422 with the message Range too wide (max 92 days).

• The window includes each event that overlaps a day of the window. This includes an overnight event that started the day before. An event that ends exactly at 00:00 of the first day is not in the window. timeOfDay still uses the start time of the event.

• timeOfDay keeps the events that start in that part of the day:

  timeOfDay	Start time
  morning	05:00 to 12:00
  afternoon	12:00 to 17:00
  evening	17:00 to 21:00
  night	All other times

• Each event in events has the full event model and a score from 0 to 1 for its name match. A series shows one time, as the occurrence that matches best, with its occurrence id. Thus a query that names a renamed occurrence gets that occurrence. When more occurrences match equally well, the search gives the one nearest to today: the first on or after today, else the last before today.

• A score of 1 is an exact match, 0.9 is a prefix, and 0.75 is a substring. Matches below 0.34 are omitted. Results are best match first.

• ambiguous is true when more than one event matches equally well.

Response fields

Responses