Create a work item

POSThttps://<your-url>/api/v2/work-items

MCP id work-items.storeAlso on this path: GET List work items

Creates a work item and returns it in the detail view with a Location header.

Token scope: api:write:project_management
Without it: 403 insufficient-token-scope.
Permission: project_management::manage_work_items
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 high-priority item in the backlog

curl -X POST \
  'https://<your-url>/api/v2/work-items' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "project_id": 1,
    "title": "Portal login rejects SSO users",
    "priority": "high",
    "estimation": 240,
    "label_ids": [
      1
    ]
  }'

const response = await fetch('https://<your-url>/api/v2/work-items', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "project_id": 1,
    "title": "Portal login rejects SSO users",
    "priority": "high",
    "estimation": 240,
    "label_ids": [
      1
    ]
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/work-items', [
        'project_id' => 1,
        'title' => 'Portal login rejects SSO users',
        'priority' => 'high',
        'estimation' => 240,
        'label_ids' => [1],
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/work-items',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'project_id': 1, 'title': 'Portal login rejects SSO users', 'priority': 'high', 'estimation': 240, 'label_ids': [1]},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "issue_key": "ACM-123",
    "title": "Portal login rejects SSO users",
    "description": "<p>…</p>",
    "priority": "high",
    "due_date": "2026-03-04",
    "estimation": 240,
    "remaining_estimate": 1,
    "location_name": "…",
    "location_address": "…",
    "location_latitude": "45.00",
    "location_longitude": "90.00"
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/state-conflict",
  "title": "State conflict",
  "status": 409,
  "detail": "The target status is not reachable from this work item's current status.",
  "instance": "/api/v2/work-items/812/actions/transition",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "conflict": {
    "reason": "illegal_transition",
    "from_workflow_status_id": 3,
    "to_workflow_status_id": 9
  }
}

{
  "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."
    }
  ]
}

28 more fields, listed under Response

The issue key is generated from the project's customer code and a per-customer sequence; order places the item last in its sprint or backlog. reporter_id is always the authenticated user: there is no way to file on somebody else's behalf. Omit workflow_status_id and work_type_id and the server picks both; in an organisation with no work types, or a project whose workflow has no statuses, that is a 409 state-conflict with conflict.reason unconfigured rather than a validation error about a key you never sent; the fix is an admin action. label_ids replaces the label set outright, and drive_item_ids the set of linked drive documents; each id must name a document the caller may open, and attaching one additionally requires the project_drive prefix's access permission and a token scope covering it. task_id must name a task in the project, and an item placed in the running sprint of a sprint project needs one; a simple-mode project does not. A work item cannot be moved between projects afterwards, so pick the project carefully.

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.

project_idinteger → Project.idRequired

Project this work item belongs to. It cannot change: the issue key was allocated from the project's customer code.

titlestring≤ 255Required

Work item title. The other field ?q= searches.

descriptionstring or null

Work item description. HTML from the rich editor, sanitised on read and on write. Mention spans are preserved verbatim, so pass them back unchanged. Detail view only.

prioritystring or null

Relative priority. Defaults to normal on create; null only on a legacy item that was never prioritised.

highest: Drop everything: work on this ahead of anything else.
high: Take this before normal work, but not ahead of the current task.
normal: The default: ordinary sprint or backlog work.
low: Pick this up once higher-priority work is clear.
lowest: Nice to have, with no expectation it is scheduled at all.

New values may be added.

due_datedate (YYYY-MM-DD) or null

Due date, a zone-free calendar date. Null when no date was set.

estimationinteger or null≥ 0

Original estimate, in minutes.

remaining_estimateinteger or null≥ 0

Remaining estimate, in minutes. Null where none was entered, in which case plnnrly derives one from the estimate and the logged time.

location_namestring or null≤ 255

Name of the place the work happens, as picked from the address search in plnnrly. Null when no location was set. Send it together with location_latitude and location_longitude; null all three to clear the location. Detail view only.

Required when location_latitude, location_longitude is present.

location_addressstring or null≤ 255

Formatted address of the location, when the place has one. Detail view only.

location_latitudenumber or null-90 to 90

Latitude of the location in decimal degrees, -90 to 90. Detail view only.

Required when location_name, location_longitude is present.

location_longitudenumber or null-180 to 180

Longitude of the location in decimal degrees, -180 to 180. Detail view only.

Required when location_name, location_latitude is present.

work_type_idinteger or null → WorkType.id

Work type of this item.

workflow_status_idinteger or null → WorkflowStatus.id

Current workflow status. Not writable through PATCH: moving between statuses is POST work-items/{work_item}/actions/transition, because the move is validated against the project workflow.

task_idinteger or null → Task.id

Kanban task this work item is booked against, when it is booked against one. It must belong to the item's project. A sprint project books the running sprint's hours through it, so an item in that project's running sprint needs one; a simple-mode project does not. Setting it also makes the task's owner the assignee. Follow it to /api/v2/tasks/{task}.

assignee_idinteger or null → User.id

User the work is assigned to. Null on an unassigned item. On a sprint project, setting it also moves the item to that user's only open task in the same budget, or in the project when the item has no task yet; with several or no candidates the task is left as it is.

sprint_idinteger or null → Sprint.id

Sprint the item sits in. Null means it is in the backlog.

parent_idinteger or null → WorkItem.id

Parent work item, for a sub-issue. Null on a top-level item.

label_idsarray of integer → Label.id≤ 50

Labels on this work item. label_ids takes at most 50 ids and replaces the whole set: a label you leave out is removed. Build it from links.labels, which lists every label while the Sprints feature is enabled, not from include=labels, which stops at 25.

drive_item_idsarray of integer → DriveItem.id≤ 25

Drive documents linked to this work item that you may open. drive_item_ids takes at most 25 ids and replaces the whole set: a document you leave out is unlinked, and so is every linked document you cannot open. Build it from links.drive_items, not from include=drive_items, which stops at 25. Expanding it additionally requires the project_drive prefix's access grant and a token scope covering it.

Response 201

Returns a WorkItem 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.

issue_keystring or null≤ 255Server-assigned

Human-readable key, e.g. ACM-123, allocated by the server from the project's customer code and a per-customer sequence. It also works in the path: GET work-items/ACM-123 works. This is one of the two fields ?q= searches.

titlestring≤ 255

Work item title. The other field ?q= searches.

descriptionhtml or nullDetail only

Work item description. HTML from the rich editor, sanitised on read and on write. Mention spans are preserved verbatim, so pass them back unchanged. Detail view only.

prioritystring or null

Relative priority. Defaults to normal on create; null only on a legacy item that was never prioritised.

highesthighnormallowlowest

New values may be added.

due_datedate (YYYY-MM-DD) or null

Due date, a zone-free calendar date. Null when no date was set.

estimationinteger or null

Original estimate, in minutes.

remaining_estimateinteger or null

Remaining estimate, in minutes. Null where none was entered, in which case plnnrly derives one from the estimate and the logged time.

location_namestring or null≤ 255Detail only

location_addressstring or null≤ 255Detail only

Formatted address of the location, when the place has one. Detail view only.

location_latitudedecimal (2 dp) or null-90 to 90patternDetail only

Latitude of the location in decimal degrees, -90 to 90. Detail view only.

location_longitudedecimal (2 dp) or null-180 to 180patternDetail only

Longitude of the location in decimal degrees, -180 to 180. Detail view only.

orderintegerServer-assigned

Position within the sprint or backlog, and the default sort. Not writable through PATCH: move an item with POST work-items/{work_item}/actions/move and list: backlog.

column_orderinteger or nullServer-assigned

Position within the board column. Not writable through PATCH: move a card with POST work-items/{work_item}/actions/move and list: board.

versioninteger

Revision counter, bumped once per write. It is the ETag's revision: send it back as If-Match to detect a concurrent edit, which answers 412.

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

Creation timestamp.

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

Last-write timestamp; use for incremental sync.

project_idinteger

Project this work item belongs to. It cannot change: the issue key was allocated from the project's customer code.

task_idinteger or null

workflow_status_idinteger

Current workflow status. Not writable through PATCH: moving between statuses is POST work-items/{work_item}/actions/transition, because the move is validated against the project workflow.

work_type_idinteger

Work type of this item.

sprint_idinteger or null

Sprint the item sits in. Null means it is in the backlog.

parent_idinteger or null

Parent work item, for a sub-issue. Null on a top-level item.

assignee_idinteger or null

reporter_idintegerServer-assigned

User who filed the work item. Always the authenticated user at create time; there is no way to file on somebody else's behalf.

web_urlstring

Absolute URL that opens this work item in plnnrly, on the organisation's own hostname. It is a stable link, safe to store: it redirects to the first of the project's backlog, all-work list or board the signed-in user may open, and opens the item there; it lands on the project page when none of them applies. Read-only.

workflow_statusRef or WorkflowStatusSummary

The workflow status this item currently sits in. Always present.

parentRef or WorkItemSummary or null

The parent work item, on a sub-issue.

assigneeRef or UserSummary or null

The user the work is assigned to. Expanding it additionally requires the users prefix's read grant and a token scope covering it.

reporterRef or UserSummary

The user who filed the work item. Expanding it additionally requires the users prefix's read grant and a token scope covering it.

work_typeRef or WorkTypeSummary

The work type of this item. Expanding it additionally requires the work_types prefix's read grant and a token scope covering it.

sprintRef or SprintSummary or null

The sprint this item sits in, when it is not in the backlog.

comments_countinteger≥ 0

Number of comments on this work item.

subtasks_countinteger≥ 0

Number of checklist subtasks on this work item.

attachments_countinteger≥ 0

Number of files attached to this work item.

child_work_items_countinteger≥ 0

Number of child work items (sub-issues).

labels_countinteger≥ 0

Number of labels on this work item.

drive_items_countinteger≥ 0

Number of linked drive documents the caller may open. Archived documents are not counted.

links_countinteger

Number of work items linked to this one, in either direction.

linksWorkItemLinks

Show 8 child fields

links.selfurl

The canonical URI of this record.

links.commentsurl

Comments on this work item.

links.subtasksurl

Checklist subtasks on this work item.

links.linksurl

Links between this work item and others, in either direction.

links.attachmentsurl

Files attached to this work item.

links.child_work_itemsurl

Child work items (sub-issues) of this work item.

links.labelsurl

Every label on this work item, paginated. Present only while the Sprints feature is enabled, as GET /labels is.

links.drive_itemsurl

Every drive document linked to this work item that you may open, paginated.

labelsarray of LabelSummary≤ 25Only with include

Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.

Show 3 child fields

labels.idinteger

Unique identifier.

labels.namestring≤ 255

Label name as shown on the chip.

labels.colorstring≤ 255

Six-digit hex colour, e.g. #ef4444.

drive_itemsarray of DriveItemSummary≤ 25Only with include

Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.

Show 5 child fields

drive_items.idinteger

Unique identifier.

drive_items.titlestring≤ 255

Item title.

drive_items.owner_typestring

The kind of record owner points at; it says which branch of owner applies.

projectcustomerorganizationuser

New values may be added.

drive_items.owner_idinteger

The id of the record owner points at.

drive_items.ownerRef

The project, customer, organisation or user whose drive this item lives in.

Which form you get depends on owner_type.

project: Ref
customer: Ref
organization: Ref
user: Ref

commentsarray of CommentSummary≤ 25Only with include

Comments on this work item, newest first, capped at 25. Follow links.comments for the rest.

Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.

Show 5 child fields

comments.idinteger

Unique identifier.

comments.author_typestring

The kind of record author points at; it says which branch of author applies.

user

New values may be added.

comments.author_idinteger

The id of the record author points at.

comments.authorRef or UserSummary

Who wrote the comment.

Which form you get depends on author_type.

user: UserSummary

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

When the comment was posted.

subtasksarray of SubtaskSummary≤ 25Only with include

Checklist subtasks on this work item, capped at 25. Follow links.subtasks for the rest.

Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.

Show 3 child fields

subtasks.idinteger

Unique identifier.

subtasks.titlestring≤ 255

Subtask title.

subtasks.is_resolvedboolean

Whether the subtask is ticked off.

Errors

403 Forbidden.

forbidden-by-policy insufficient-permission insufficient-token-scope

409 Conflict.

idempotency-key-in-flight idempotency-key-reused state-conflict

415 Unsupported media type.

unsupported-media-type

422 Unprocessable content.

unprocessable-relationship validation-failed

7 errors every operation can return: 400, 401, 404, 406, 429, 500, 503

400 Bad request.

idempotency-key-required invalid-cursor invalid-query-parameter malformed-request unsupported-parameter

401 Unauthenticated.

token-expired unauthenticated

404 Not found.

endpoint-not-found resource-not-found

406 Not acceptable.

not-acceptable

429 Too many requests.

rate-limit-exceeded

500 Server error.

internal-error

503 Service unavailable.

tenant-unavailable

This path allows GET, POST. Anything else answers 405.

Something wrong or missing on this page? Tell us

Access

Query parameters

Request headers

Request body

Response 201

Headers

Errors