Scheduling

Read one day or a range of days. The response gives the events, the free slots, and the load of each day. It also gives your areas, activity types, projects, and preferences. Scope: events:read.

• from and to are required. For one day, send the same date in both.
• to must not be before from. The range is 366 days or less. Else the server returns 422.
• Send each boolean parameter as true or false. Other values return 422.
• includeBacklog=true adds the Inbox items in backlog. backlogQuery, backlogPlannedOn, backlogProjectId, backlogMinPriority, and backlogOffset work only with includeBacklog=true. Without it, they return 422. Refer to Backlog.
• backlogProjectId keeps the Inbox items of one project. Send a project id, or none for the items with no project.
• backlogMinPriority keeps the Inbox items with a priority of this value or more, from 0 to 4.
• The Inbox filters work together. With one or more filters, the response also has backlogMatchedCount.
• includeSeries=true adds the recurring series in series. Refer to Series rows.
• includeLookups=false removes areas, activityTypes, projects, and integrations from the response. Use it when you have them from an earlier read. The default is true. userPreferences and timezone stay.
• minDuration is an optional whole number from 1 to 1440, in minutes. For example, minDuration=90 returns only freeSlots of at least 90 minutes. It keeps the full span of each qualifying gap and does not filter events.

The MCP tool get_schedule has separate weather and energy options. For REST, read those reports through GET /weather and GET /energy. The optional energy field in the shared response schema is used by MCP only.

What the response contains

• timezone is the IANA time zone of the account. All start and end values are local datetimes in this time zone.
• now is the current local datetime, for example "2026-09-23T14:05".
• days has one item for each date. Each day has events (the event model) and freeSlots (each a start and end). On today, the first free slot starts on the first 5-minute mark that is more than 5 minutes after now. A write accepts that start.
• Each occurrence of a series has seriesId and originalDate. Refer to Ids of recurring events.
• loadByArea and loadByActivityType give the time of the blocking events of the day. Each bucket is areaId (or activityTypeId), minutes, and eventCount. areaId is null for the events with no area.
• loadByProject gives the same buckets by projectId. projectId is null for the events with no project. The buckets start with the most minutes.
• A read of more than one day also has a top-level loadByProject: the sum of the loadByProject buckets of all days. An event on two days (across midnight) counts one time in eventCount.
• projects lists your projects: id, name, and areaId (or null). An archived project also has archived: true. It keeps its links, but it refuses new links. Refer to Categories.
• nonBlockingLoadByArea and nonBlockingLoadByActivityType give the same buckets for the events of the kind non_blocking. The reference events are not in them. A day with no non_blocking event does not have these fields.
• A day that has a confirmed review also has review: reviewedAt (an ISO 8601 instant) and the adherence scores. A score can be null. Refer to Day reviews.
• userPreferences.conflictPolicy is always propose. A write that overlaps a blocking event fails with conflict and gives nearestSlots. No setting changes this.
• integrations is in the response when a calendar is connected. Every caller gets integrations.sources[].account, the account name at the provider. integrations.sources[].calendars[].timezone is the time zone of the calendar at the provider. It is for information only: all spans use the top-level timezone. integrations.defaultCalendarId is the default calendar of a new event, and the default Source of a new Inbox item. It is absent when the default calendar is not writable or its source is not connected. backlogCount is in the response when the Inbox is not empty. With includeBacklog=true, it is always there.
• A writable event calendar in integrations.sources[].calendars[] also has copyStyle: full, private, or busy. It is the style of a copy on that calendar when the mirrorStyles of the event does not name the calendar. With copyStyle: "busy", busyCopyTitle is the title of the copy. null means "Busy". Refer to Copy styles.
• integrations.aiRuleWarnings lists the problems in the AI rules of the user. Each item is an area or an activity type that the rules name. It does not exist, or its name matches more than one category. It has up to 20 items { code, field, name }. code is missing_taxonomy_reference or ambiguous_taxonomy_reference. field is area or activityType. The field is absent when there is no warning.

Series rows

With includeSeries=true, series has one row for each recurring series that obeys one of these conditions:

• The series has an occurrence in the range from from to to.
• The series has a nextOccurrence.
• The series has no end yet. A series with an open rule never ends, also when its next date is more than 366 days ahead.

A series ends when its UNTIL or COUNT leaves no date on or after today. The response does not include a series that ended outside the range.

A series row has no notes. The events of the series have them.

Response fields

Responses

Place one or more events into free time. You do not calculate the slots. Send 1 to 20 requests. Scope: events:write.

The requests run in their order. A later request does not overlap an event that an earlier request booked.

The call is atomic by default. When one request fails, the server books nothing. Send partial: true to book the requests that succeed.

Two forms of a request

Each request has name (1 to 200 characters) and durationMinutes (a whole number from 5 to 1440). It also has one of these two forms:

• All times are local datetimes "YYYY-MM-DDTHH:MM".
• autoCommitBest is deprecated. A window accepts true or an omitted field, with the same behavior. false fails with validation.
• A request with start and also earliest, latest, or autoCommitBest is an error.
• A request can also have kind and recurrence, as on an event create. A fixed-start request with kind: "non_blocking" or kind: "reference" does not fail with conflict. A blocking fixed-start request with recurrence fails with conflict when an occurrence overlaps a blocking event.
• A start or a window in the past is an error. On today, the start must be more than 5 minutes after now. A window with no room for a 5-minute slot after that point fails with validation, not conflict.
• A window slot starts on a 30-minute mark. When no 30-minute mark fits, it starts at the start of a free gap (a 5-minute mark).
• A nearest slot can start at one of these times: a 15-minute mark, the start of a free gap, or the latest start that fits in a free gap. It can also start at the free minute nearest to the requested start. It keeps the exact durationMinutes. This rule applies to each nearestSlots list, also in POST /events and POST /backlog.
• An unknown key fails the row with validation: Unrecognized key(s): <keys>. When the key belongs to the other form, the message names that form.
• calendarId, mirrorCalendarIds, and mirrorStyles work as on an event create. null keeps the event on the dial only. When you omit calendarId, the event goes to the default calendar if there is one. Else it stays on the dial only. A request with recurrence and mirrorCalendarIds needs a home calendar. Refer to Rules of the fields.
• mirrorStyles sets the style of each copy. Each key must be in the mirrorCalendarIds of the request. {} is the same as no map. Refer to Copy styles.
• areaId and activityTypeId take an id. null and an omitted key are the same. An id that does not exist, or that you cannot see, fails the row with not_found.
• projectId takes the id of a live project. null and an omitted key are the same. An empty string fails the row with validation. An archived or unknown id fails the row with not_found. In result.event, projectId is the stored form of the id, also when you send it braced or in upper case.
• With no areaId, the event takes the area of the project. An areaId in the request wins. When the area of the project is hidden, the event gets no area. Refer to Rules of the fields.
• priority is a whole number: 0 none, 1 low, 2 medium, 3 high, 4 urgent. An omitted value is 0. null, a number that is not whole, or a value out of the range fails the row with validation.
• The server checks areaId and activityTypeId before projectId. When a request has an unknown area and an unknown project, the row error names the area.

Results

Each successful row has event, the booked event, in result.

• An exact-start conflict row gives nearestSlots. To take one, send its start as a new request.
• When the call books one or more events and records an undo receipt, the body has one undoToken and its expiresAt. This token undoes all bookings of the call. If the server cannot record the undo, the bookings stay and the response has no undoToken.

Row errors

A request that is not valid has status: "error" and the code validation. In the default atomic mode, the other rows are skipped, and the server rejects the call. With partial: true, the other requests still run, and the call returns 200 when one or more rows are ok.

A validation row from a schema check also has error.issues. Later checks, such as a start in the past or a series with copies and no home calendar, can return validation without issues. Refer to Validation errors.

A body that is not valid returns 422 with no results, for example when requests is empty or has more than 20 items.

Some row errors:

When all rows fail with not_found, the status is 404.

A window schema error does not repeat the values that you sent. When earliest or latest has a bad format, its issue has expected: "YYYY-MM-DDTHH:MM"; the schema skips the window-order and length checks until both values have valid formats. Later errors, such as a window in the past or a window with no free slot, include the window's times.

Retries with requestId

Give each request a requestId. When you send the same requestId again in 60 seconds, the server does not book a second event. It returns the first result with replayed: true, and it writes nothing new.

• The retry must send the same content. A request with different content is a new request.
• mirrorStyles is content. The order of the keys in mirrorStyles does not change the match. {} and no map match. The order of mirrorCalendarIds changes the match.
• projectId and priority are content. A retry with another priority is a new request.
• priority: 0, projectId: null, areaId: null, and activityTypeId: null match an omitted key. priority: null is not valid.
• The server compares the ids as you sent them. Send each id in the same form in a retry.
• Only a booked result can replay. The server does not replay a result that you undid.
• Omitting autoCommitBest or sending true does not change retry matching. Clients can drop the deprecated field while keeping the same requestId.
• Only a requestId replays a result. A request with no requestId is always a new request.
• When one call sends the same requestId in more than one request, the server replays an earlier result for one request only. The other requests run as new requests.

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.

Reverse one or more recent writes. Send 1 to 20 tokens. Each token is the undoToken of a write that recorded an undo receipt. Scope: events:write.

• A token is valid until its expiresAt, 30 minutes after the write.
• You can use a token one time only.
• The results rows are in the order of tokens. The server undoes the newest write first. Thus two tokens that change one row work in any order.
• The undo stops when a row that the write changed has a newer change. Refer to Stale tokens.
• The response has only results. An undo does not return a new undoToken. You cannot undo an undo.

These routes can return an undoToken when the server records an undo receipt: POST /events, POST /schedule/plan, POST /reviews/{date}, POST /backlog, POST /categories, and POST /command. The tracker and moment routes return no undoToken. Refer to Moments & trackers.

Row results

Each ok row has one shape: { reverted, restored, removed, voided, occurrenceRestored? }. The counts count the rows that the undo changed.

The four counts reverted, restored, removed, and voided are always there. A count is 0 when nothing of that kind changed. A calendar link or a task link is not a counted row.

The undo of an Inbox capture to a task list cancels the task create when the server did not send it yet. When the task exists, the undo deletes it in its app. Linear cannot delete an issue, so the undo closes it.

Stale tokens

The server stores a stamp of each row that a write changed. The undo compares each row with its stamp. A sync that changes only the bookkeeping fields of a row does not change the stamp. The stamp of an event or an Inbox item includes its project and its priority. A token from before projects stays valid while the row has no project and the priority 0.

The undo fails the token row with stale in these cases:

• A row that the write changed has a newer change.
• A row is gone, or a row that the write did not delete is now deleted.
• The token is from before the stamps.
• A category undo would delete a category that the write made, and an event, an Inbox item, a tracker, or a calendar default now uses it.
• A user changed the area, the activity type, the project, or the priority of an event or an Inbox item by hand. An AI classification after the write does not make the token stale.
• A category undo would show a shared default again, and a category of the same type now has its name.

A stale row changes nothing. A token that an undo already used is validation, not stale.

A stale row from a stamp check has error.conflictingRows: up to 50 items { entity, id, reason }. error.conflictingRowsTruncated: true shows that more rows block the undo. A token from before the stamps, and a category refusal, have no conflictingRows.

Item errors

A sync race changes nothing. Send the undo again after a short time. Do not send a stale token again: it fails again. When all the rows of the call fail with conflict, or all fail with stale, the status is 409. A mix of codes gives 400 with batch_rejected.

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.