Update a recurring work item

PATCH/api/v2/workspaces/{slug}/projects/{project_id}/recurring-work-items/{pk}/

Change a schedule, its blueprint, or both in one request. Blueprint changes apply only to future runs. Work items the schedule already created don't change.

PATCH is partial. Send only the fields you want to change. Anything you omit keeps its current value.

Path parameters

slug:requiredstring

The workspace slug. It appears in your Plane URLs. In https://app.plane.so/my-team/projects/, the slug is my-team.

project_id:requiredstring (uuid)

The project the schedule belongs to.

pk:requiredstring (uuid)

The id of the schedule to update.

Body parameters

Every field is optional. Send the subset you are changing.

The schedule:

start_at:optionalstring (date or date-time)

A new first run date. Only the date counts, and Plane pins it to 00:05 in the project's timezone. Send a plain date (YYYY-MM-DD). If you send a date-time, Plane converts it to your user profile's timezone and keeps that date, which can be a day off from the one you wrote. Changing it recalculates next_scheduled_at.

end_at:optionalstring (date or date-time) or null

A new last run date, sent as a plain date as for start_at and pinned to 23:59:59 in the project's timezone, or null to remove the end. It must be after start_at, and the check uses the stored start_at when you don't send one. To stop future runs, set it to the last date you want a run on.

interval_type:optionalstring

One of daily, weekly, monthly, or yearly. Changing it recalculates next_scheduled_at.

interval_count:optionalinteger

How many intervals between runs. At least 1. Changing it recalculates next_scheduled_at.

The blueprint:

name:optionalstring

The title each created work item gets. Maximum 255 characters.

description_html:optionalstring

The description each created work item gets, as HTML. An empty string resets it to <p></p>.

priority:optionalstring

One of none, low, medium, high, or urgent.

state_id:optionalstring (uuid) or null

The state each created work item starts in, or null to clear it. It must be a state of the path project. In a workspace with governance turned on, states belong to the workspace catalog, so any state_id returns 400.

type_id:optionalstring (uuid) or null

The work item type each created work item gets, or null to clear it. It must be one of the path project's work item types.

assignee_ids:optionalarray of string (uuid)

Replaces the assignee list. Each id must be an active member of the path project. Send [] to clear it.

label_ids:optionalarray of string (uuid)

Replaces the label list. Each id must be a label of the path project. Send [] to clear it. In a workspace with governance turned on, labels belong to the workspace catalog, so any label id returns 400.

module_ids:optionalarray of string (uuid)

Replaces the module list. Each id must be a module of the path project. Send [] to clear it.

enabled can't be changed here

enabled is read-only, and there is no pause or resume operation. A PATCH that sends enabled returns 200 and leaves the value as it was. To stop a schedule, set end_at or delete it.

Response shaping

fields:optionalstring

Comma-separated list of fields to return. Fields you don't request are left out of the response instead of coming back as null, so a missing key means you didn't ask for it and null means the value is null. id is always included, whether or not you name it.

Pass all to get every requestable field. An unknown field name returns 400 with the list of valid names and the closest match, so a typo is caught instead of being silently ignored.

Requestable here: assignee_ids, created_at, created_by_id, description_html, enabled, end_at, id, interval_count, interval_type, label_ids, last_run_at, module_ids, name, next_scheduled_at, priority, schedule_description, start_at, state_id, type_id, updated_at, updated_by_id, work_item_blueprint_id.

See Sparse fields.

Scopes

projects.recurring_work_items:write

Errors

Status	Code	Cause
400	invalid_request	end_at not after start_at, a bad interval_type or interval_count, or an id that doesn't belong to the project.
401	unauthorized	Missing or invalid credentials.
402	payment_required	The workspace's plan doesn't include recurring work items.
403	forbidden	Your project role or token scope can't update recurring work items.
404	not_found	No such schedule, project, or workspace, or it's outside your tenant.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
409	governance_migration_in_progress	A governance migration is running, so the workspace is read-only. Retry after it finishes.
413	payload_too_large	The request body is over the size limit.
415	unsupported_media_type	The Content-Type isn't one this endpoint accepts.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Update a recurring work item

curl -X PATCH \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/recurring-work-items/f3a8c1d6-2e5b-4a79-8c04-1b7e9d6f2a53/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Fortnightly status report",
  "interval_count": 2
}'

import requests

response = requests.patch(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
    "/recurring-work-items/f3a8c1d6-2e5b-4a79-8c04-1b7e9d6f2a53/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "name": "Fortnightly status report",
        "interval_count": 2,
    },
)
print(response.json())

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
    "/recurring-work-items/f3a8c1d6-2e5b-4a79-8c04-1b7e9d6f2a53/",
  {
    method: "PATCH",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Fortnightly status report",
      interval_count: 2,
    }),
  },
);
const data = await response.json();

Response200

{
  "id": "f3a8c1d6-2e5b-4a79-8c04-1b7e9d6f2a53",
  "work_item_blueprint_id": "a9d2e6f1-7c3b-4085-b4e8-2f0c6a1d9e37",
  "name": "Fortnightly status report",
  "description_html": "<p>Summarize progress, risks, and next steps.</p>",
  "priority": "medium",
  "state_id": "2c4d16f8-9b3e-4a52-8d71-1f0e6c9a5b48",
  "type_id": null,
  "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
  "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
  "module_ids": [],
  "start_at": "2026-08-03T00:05:00Z",
  "end_at": "2026-12-31T23:59:59Z",
  "interval_type": "weekly",
  "interval_count": 2,
  "next_scheduled_at": "2026-08-17T00:05:00Z",
  "last_run_at": "2026-08-03T00:07:12.418520Z",
  "enabled": true,
  "schedule_description": "Every 2 weeks on Monday at 00:05",
  "created_at": "2026-07-28T09:22:41.478363Z",
  "updated_at": "2026-08-05T15:31:44.207936Z",
  "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
}