Upsert a work item

POST/api/v2/workspaces/{slug}/projects/{project_id}/work-items/upsert/

Create a work item, or update the existing one with the same (external_source, external_id) pair. Work items are the issues, tasks, and epics in a project.

Both external_source and external_id are required. Without them there is nothing to match on, and the request returns 400.
A created record returns 201 with X-Plane-Upsert: created, and an updated one returns 200 with X-Plane-Upsert: updated. Branch on the header instead of guessing from the status.
Upsert is safe for sequential importers. Two simultaneous upserts of the same key can each miss and each create, so serialize your writes per key.

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

The project the resource belongs to. Accepts the project UUID or its bare identifier, for example ENG.

Body parameters

name:requiredstring

Display name.

Maximum 255 characters.

assignee_ids:optionalarray of string (uuid)

Ids of the assignees to associate. Replaces the current set.

assignees:optionalarray of string (email)

Member email addresses to assign, instead of assignee_ids.

cycle_id:optionalstring (uuid)

Id of the related cycle.

Nullable.

description_html:optionalstring

Rich-text body as HTML. The Plane editor reads and writes this field.

Nullable.

estimate:optionalstring

The estimate point's value, instead of estimate_point_id.

Nullable.

estimate_point_id:optionalstring (uuid)

Id of the related estimate point.

Nullable.

external_id:optionalstring

Your system's identifier for this record, for sync and import correlation.

Maximum 255 characters. Nullable.

external_source:optionalstring

The system external_id came from, for example github or jira.

Maximum 255 characters. Nullable.

label_ids:optionalarray of string (uuid)

Ids of the labels to associate. Replaces the current set.

labels:optionalarray of string

Label names, instead of label_ids.

module_ids:optionalarray of string (uuid)

Ids of the modules to associate. Replaces the current set.

parent:optionalstring

The parent's identifier, instead of parent_id.

Nullable.

parent_id:optionalstring (uuid)

Id of the parent work item.

Nullable.

priority:optionalstring

The work item's priority. One of none, low, medium, high, urgent.

start_date:optionalstring (date)

Planned start date, as YYYY-MM-DD.

Nullable.

state:optionalstring

The state's name, instead of state_id.

Nullable.

state_id:optionalstring (uuid)

Id of the related state.

Nullable.

target_date:optionalstring (date)

Planned due date, as YYYY-MM-DD.

Nullable.

type:optionalstring

The work item type's name, instead of type_id.

Nullable.

type_id:optionalstring (uuid)

Id of the work item type.

Nullable.

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. id is always included. Pass all to get every requestable field. An unknown field name returns 400. See Sparse fields.

Requestable here: archived_at, assignee_ids, completed_at, created_at, created_by_id, custom_fields, cycle_id, description_html, estimate_point_id, external_id, external_source, id, identifier, is_draft, label_ids, module_ids, name, parent_id, priority, project_id, sequence_id, sort_order, start_date, state_id, target_date, type_id, updated_at, updated_by_id.

expand:optionalstring

Comma-separated relations to embed: assignees, cycle, estimate_point, labels, modules, parent, state, type.

Expanded objects get their own key: ?expand=state keeps state_id and adds a state object next to it. ?fields= and ?expand= work independently. Naming a relation in ?fields= returns 400, and field filtering never removes an expanded object. See Expanding relations.

Scopes

projects.work_items:write

Errors

Status	Code	Cause
`400`	`invalid_request`	The request body or a query parameter failed validation.
`401`	`unauthorized`	Missing or invalid credentials.
`402`	`payment_required`	The feature this endpoint belongs to isn't enabled on your plan or is switched off.
`403`	`forbidden`	Your role or token scope doesn't allow this.
`404`	`not_found`	No such resource, or it's outside your tenant.
`406`	`not_acceptable`	The `Accept` header asks for a representation the API can't produce.
`409`	`conflict`	A business rule blocks the write.
`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.

Upsert a work item

bash

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/upsert/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_source": "jira",
  "external_id": "PAY-2041",
  "name": "Checkout fails for saved cards",
  "description_html": "<p>Imported from Jira. Payment step returns a 500 for cards saved before the migration.</p>",
  "priority": "urgent",
  "state": "In Progress"
}'

python

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/upsert/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "external_source": "jira",
        "external_id": "PAY-2041",
        "name": "Checkout fails for saved cards",
        "description_html": "<p>Imported from Jira. Payment step returns a 500 for cards saved before the migration.</p>",
        "priority": "urgent",
        "state": "In Progress",
    },
)
print(response.headers["X-Plane-Upsert"], response.json())

javascript

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/upsert/",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      external_source: "jira",
      external_id: "PAY-2041",
      name: "Checkout fails for saved cards",
      description_html:
        "<p>Imported from Jira. Payment step returns a 500 for cards saved before the migration.</p>",
      priority: "urgent",
      state: "In Progress",
    }),
  },
);
const data = await response.json();

Response200

json

{
  "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
  "name": "Checkout fails for saved cards",
  "description_html": "<p>Imported from Jira. Payment step returns a 500 for cards saved before the migration.</p>",
  "identifier": "PROJ-157",
  "sequence_id": 157,
  "priority": "urgent",
  "project_id": "4af68566-94a4-4eb3-94aa-50dc9427067b",
  "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
  "type_id": null,
  "assignee_ids": [],
  "label_ids": [],
  "cycle_id": null,
  "module_ids": [],
  "parent_id": null,
  "estimate_point_id": null,
  "start_date": null,
  "target_date": null,
  "is_draft": false,
  "sort_order": 95535.0,
  "completed_at": null,
  "archived_at": null,
  "external_id": "PAY-2041",
  "external_source": "jira",
  "created_at": "2026-01-16T08:12:55.301742Z",
  "updated_at": "2026-01-21T14:37:09.884120Z",
  "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "custom_fields": {}
}

Upsert a work item ​

Path parameters ​

Body parameters ​

Response shaping ​

Scopes ​

Errors ​

Upsert a work item

Path parameters

Body parameters

Response shaping

Scopes

Errors