Create an event

POSThttps://<your-url>/api/v2/events

MCP id events.storeAlso on this path: GET List events

Puts an event on the authenticated user's agenda and returns it with a Location header.

Token scope: api:write:events
Without it: 403 insufficient-token-scope.
Permission: events::manage_self
Without it: 403 insufficient-permission.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts Idempotency-Key. Never cached: private, no-store. Unknown body keys are refused, never dropped.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: A one-off block on my agenda

curl -X POST \
  'https://<your-url>/api/v2/events' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "title": "Design review",
    "start": "2026-03-03T09:00:00Z",
    "end": "2026-03-03T10:30:00Z",
    "is_all_day": false
  }'

const response = await fetch('https://<your-url>/api/v2/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "title": "Design review",
    "start": "2026-03-03T09:00:00Z",
    "end": "2026-03-03T10:30:00Z",
    "is_all_day": false
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/events', [
        'title' => 'Design review',
        'start' => '2026-03-03T09:00:00Z',
        'end' => '2026-03-03T10:30:00Z',
        'is_all_day' => false,
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/events',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'title': 'Design review', 'start': '2026-03-03T09:00:00Z', 'end': '2026-03-03T10:30:00Z', 'is_all_day': False},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "user_id": 1,
    "task_id": 1,
    "parent_event_id": 1,
    "occurrence_date": "2026-03-04",
    "start": "2026-03-03T09:00:00Z",
    "end": "2026-03-03T10:30:00Z",
    "title": "Design review",
    "description": "<p>…</p>",
    "is_all_day": false,
    "is_recurring": false,
    "recurrence_interval": 1
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/idempotency-key-in-flight",
  "title": "Idempotency key in flight",
  "status": 409,
  "detail": "The original request for this Idempotency-Key is still being processed. Retry shortly.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S"
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 fields failed validation.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "errors": [
    {
      "pointer": "/date",
      "code": "date_format",
      "detail": "The date does not match the format Y-m-d."
    },
    {
      "pointer": "/minutes",
      "code": "min",
      "detail": "The minutes must be at least 1."
    },
    {
      "pointer": "/description",
      "code": "required",
      "detail": "The description field is required."
    }
  ]
}

11 more fields, listed under Response

The event is always the caller's own: user_id is not a body key, and there is no way to book an event for a colleague through the API, even with events::manage_for_others. start, end, recurrence_start and recurrence_end are stored exactly as sent: they are RFC 3339 UTC instants and no timezone conversion is applied, unlike the form in plnnrly, which collects local wall-clock time. Send is_recurring: true with a frequency and an interval to create a series master; recurrence_pattern only affects a monthly or yearly frequency and selected_weekdays only a weekly one; a value that does not apply is stored and ignored. Linking a task_id requires the task to be one the caller may see, and only an event with a task can have time logged on it. parent_event_id and occurrence_date are server-assigned and cannot be sent: separating a single occurrence out of a series is done in plnnrly and has no API equivalent in this version. Creating an event notifies anyone @-mentioned in the description and pushes the new event to open agenda tabs.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

Idempotency-Keystring≤ 255

A caller-chosen key that makes this POST safe to retry. Replaying it returns the original response with Idempotency-Replayed: true.

Request body

Unknown keys are refused with 422, naming the key.

titlestring≤ 255Required

Event title, as shown on the calendar tile.

starttimestamp (YYYY-MM-DDThh:mm:ssZ)Required

When the event starts. RFC 3339 UTC.

Must be after -5 years.

endtimestamp (YYYY-MM-DDThh:mm:ssZ)Required

When the event ends. RFC 3339 UTC.

Must be on or after start. Must be before +5 years.

is_all_daybooleanRequired

Whether the event occupies whole days rather than a time range. An all-day event is measured against the owner's working week rather than against start and end.

descriptionstring or null

Free-text description, authored in the rich editor. HTML, sanitised on the way in and on the way out; @-mention spans are preserved, and changing them is what notifies the people mentioned.

task_idinteger or null → Task.id

Kanban task this event is planned against, or null for a plain calendar block. Only an event with a task can have time logged on it.

is_recurringboolean

Whether this row is the master of a recurring series. When true, the recurrence fields describe how occurrences are generated.

recurrence_intervalinteger or null≥ 1

How many frequency units pass between occurrences: 2 with a weekly frequency is every other week.

recurrence_frequencystring or null

The unit the series repeats in.

day: Repeats every recurrence_interval days.
week: Repeats every recurrence_interval weeks, on the weekdays named in selected_weekdays.
month: Repeats every recurrence_interval months, positioned by recurrence_pattern.
year: Repeats every recurrence_interval years, positioned by recurrence_pattern.

New values may be added.

recurrence_patternstring or null

How a monthly or yearly series positions its occurrence within the month. Ignored for a daily or weekly frequency.

day_of_month: Falls on the same day number as recurrence_start, such as the 17th of every month.
weekday_occurrence: Falls on the same weekday occurrence as recurrence_start, such as the third Tuesday of every month.

New values may be added.

Response 201

Returns a Event in the detail view.

Headers

ETag: A strong validator of exactly this representation.
Idempotency-Replayed: true when this response was replayed from a stored Idempotency-Key rather than produced by a new write.
Location: The absolute URL of the created or queued resource.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning

idinteger

Unique identifier.

user_idintegerServer-assigned

Whose agenda the event is on. Always the authenticated user at creation time; not writable.

task_idinteger or null

Kanban task this event is planned against, or null for a plain calendar block. Only an event with a task can have time logged on it.

parent_event_idinteger or nullServer-assigned

Master event, when this row is a separated occurrence of a recurring series. Set by the server; not writable.

occurrence_datedate (YYYY-MM-DD) or nullServer-assigned

The date of the series occurrence this row replaces. Set by the server; not writable.

starttimestamp (YYYY-MM-DDThh:mm:ssZ)

When the event starts. RFC 3339 UTC.

endtimestamp (YYYY-MM-DDThh:mm:ssZ)

When the event ends. RFC 3339 UTC.

titlestring≤ 255

Event title, as shown on the calendar tile.

descriptionhtml or nullDetail only

Free-text description, authored in the rich editor. HTML, sanitised on the way in and on the way out; @-mention spans are preserved, and changing them is what notifies the people mentioned.

is_all_dayboolean

Whether the event occupies whole days rather than a time range. An all-day event is measured against the owner's working week rather than against start and end.

is_recurringboolean

Whether this row is the master of a recurring series. When true, the recurrence fields describe how occurrences are generated.

recurrence_intervalinteger or null

How many frequency units pass between occurrences: 2 with a weekly frequency is every other week.

recurrence_frequencystring or null

The unit the series repeats in.

dayweekmonthyear

New values may be added.

recurrence_patternstring or null

How a monthly or yearly series positions its occurrence within the month. Ignored for a daily or weekly frequency.

day_of_monthweekday_occurrence

New values may be added.

recurrence_starttimestamp (YYYY-MM-DDThh:mm:ssZ) or null

First moment the series may generate an occurrence.

recurrence_endtimestamp (YYYY-MM-DDThh:mm:ssZ) or null

Last moment the series may generate an occurrence; null for an open-ended series.

selected_weekdaysarray of string or nullDetail only

Weekdays a recurring event falls on. Applies to a weekly frequency; ignored otherwise.

monday
tuesday
wednesday
thursday
friday
saturday
sunday

New values may be added.

recurrence_exceptionsarray of string or nullDetail only

Dates on which this recurrence does not occur. plnnrly adds one whenever a single occurrence is separated or deleted.

created_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Creation timestamp.

updated_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Last-write timestamp; use for incremental sync.

deleted_attimestamp (YYYY-MM-DDThh:mm:ssZ) or null

When the event was deleted, or null while it is live. Reach a deleted event with trashed=with and undo it with POST events/{event}/actions/restore.