Correct a worklog

PATCHhttps://<your-url>/api/v2/worklogs/{worklog}

MCP id worklogs.updateAlso on this path: GET Read a worklog, DELETE Delete a worklog

Partially updates a worklog: absent keys are untouched, an empty body is rejected.

Token scope: api:write:times
Without it: 403 insufficient-token-scope.
Permission: None. The record's own rules still apply.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts If-Match. 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: Correct the minutes and the description

curl -X PATCH \
  'https://<your-url>/api/v2/worklogs/1' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: *' \
  -d '{
    "minutes": 90,
    "description": "Reviewed the invoice export (rounding fix split out)"
  }'

const response = await fetch('https://<your-url>/api/v2/worklogs/1', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'If-Match': '*',
  },
  body: JSON.stringify({
    "minutes": 90,
    "description": "Reviewed the invoice export (rounding fix split out)"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('If-Match', '*')
    ->patch('https://<your-url>/api/v2/worklogs/1', [
        'minutes' => 90,
        'description' => 'Reviewed the invoice export (rounding fix split out)',
    ]);

import requests
response = requests.request(
    'PATCH',
    'https://<your-url>/api/v2/worklogs/1',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'If-Match': '*'},
    json={'minutes': 90, 'description': 'Reviewed the invoice export (rounding fix split out)'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "date": "2026-09-10",
    "minutes": 90,
    "description": "Reviewed the invoice export (rounding fix split out)",
    "project_id": 12,
    "project": null,
    "budget_id": 1,
    "budget": null,
    "task_id": 88,
    "task": null,
    "work_item_id": 41,
    "work_item": null
  },
  "meta": {
    "warnings": [
      {
        "…": "6 fields of warnings"
      }
    ]
  }
}

{
  "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/precondition-failed",
  "title": "Precondition failed",
  "status": 412,
  "detail": "The record changed since the version named in If-Match. Re-read it and retry.",
  "instance": "/api/v2/work-items/812",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "current_version": 12
}

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

13 more fields, listed under Response

Changing another user's entry additionally requires times::update_others; without it, other people's entries are invisible to you. An entry awaiting review answers 409 with conflict.reason locked_by_review to anyone but its author or a reviewer, and an invoiced entry answers 409 locked_by_invoice: an invoiced entry can never be changed again. exceeded_budget is read-only here: it is what puts an entry in the reviewer's queue, and clearing it would withdraw the entry from that queue silently. reason stays writable until a reviewer has settled the entry; rewriting it afterwards answers 409 reason_reviewed. Sending task_id re-infers is_not_billable from the task, and sending is_not_billable with a value that differs from the inferred or current one requires billable_change_reason (422 on /billable_change_reason without it) and puts the entry back in the reviewer's queue, reopening one that was already settled. A new project_id must be one the entry's owner holds a task on, and a new task_id must be the owner's own task in the entry's project, so a manager holding times::update_others may move a colleague's hours onto that colleague's deadline in another project. Only the caller's times::write_on_others_tasks widens either rule, never the owner's; a refusal answers 403 forbidden-by-policy, and a task outside the project a 422 on /task_id. Moving the entry with project_id detaches a task or work item that cannot follow it and nulls budget_id with the task. Reassigning a worklog to another employee is not possible: that is a DELETE plus a POST. work_item_id is checked for existence, visibility and the same project, and moving the entry onto a different work item additionally requires that the entry's owner may log time on it, the same rule plnnrly and the create operation apply; otherwise it answers 403 forbidden-by-policy. Send If-Match with the ETag from your last read to detect a concurrent edit, which answers 412. Treat it as best-effort only: this resource carries no concurrency token, and updated_at is second-precision.

Path parameters

worklogintegerRequired

The Time's numeric id.

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.

If-Matchstring

The ETag a write is conditional on. A stale validator is 412 precondition-failed.

Request body

Unknown keys are refused with 422, naming the key.

datedate (YYYY-MM-DD)

The calendar day the work happened.

minutesinteger1 to 1440

Duration in minutes, between 1 and 1440.

descriptionstring≤ 255

What the employee worked on.

project_idinteger → Project.id

Project the hours are booked against; null once that project is deleted.

task_idinteger or null → Task.id

Task the hours are booked on; null when the entry is not attached to one, or once that task is deleted.

work_item_idinteger or null → WorkItem.id

Work item the hours are attached to; null when the entry is not attached to one, or once that work item is deleted.

is_overtimeboolean

Whether the hours count as overtime. Sending it without the times::write_overtime permission leaves it false and adds an input_ignored warning rather than failing the write.

is_not_billableboolean

Whether these hours are excluded from invoicing. Inferred from the task's is_billable flag (false without a task) on create and again whenever task_id is sent. Sending a value that differs from the inferred or current one requires billable_change_reason and puts the entry in a reviewer's queue; without it the write is a 422 on /billable_change_reason.

billable_change_reasonstring or null≤ 65535

Why the inferred billability was overridden. Required whenever is_not_billable is sent with a value that differs from the inferred or current one, on create and on PATCH alike; the override puts the entry in a reviewer's queue, reopening one a reviewer had already settled.

reasonstring or null≤ 65535

Why the budget overrun was accepted. Sending it on create marks the entry as exceeding its budget. Once a reviewer has settled the entry it can no longer be changed: a PATCH that does answers 409 reason_reviewed.

Response 200

Returns a Time in the detail view.

Headers

ETag: A strong validator of exactly this representation.
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.

datedate (YYYY-MM-DD)

The calendar day the work happened.

minutesinteger

Duration in minutes, between 1 and 1440.

descriptionstring≤ 255

What the employee worked on.

project_idinteger or null

Project the hours are booked against; null once that project is deleted.

projectRef or ProjectSummary or null

The project the hours are booked against, always expanded. Its customer_id is the customer to fetch with GET /api/v2/customers/{customer}; the customer itself is not nested.

budget_idinteger or nullServer-assigned

Budget the hours are invoiced against. Derived from the task, never accepted on a write; null when no task is set or the budget is deleted.

budgetRef or BudgetSummary or null

The budget the hours are invoiced against. Expanding it with ?include=budget additionally requires the budgets::read permission and a token scope covering the budgets prefix.

task_idinteger or null

Task the hours are booked on; null when the entry is not attached to one, or once that task is deleted.

taskRef or TaskSummary or null

The task the hours are booked on. Expanding it with ?include=task additionally requires the kanban::manage_self permission and a token scope covering the kanban prefix, and is limited to the tasks you can see on the tasks collection.

work_item_idinteger or null

Work item the hours are attached to; null when the entry is not attached to one, or once that work item is deleted.

work_itemRef or WorkItemSummary or null

The work item the hours are attached to, always expanded.

user_idinteger or nullServer-assigned

Employee the hours belong to. Assigned on create (from the authenticated user, or from on_behalf_of_user_id) and never writable afterwards; reassigning a worklog is a DELETE plus a POST.

userRef or UserSummary or null

The employee the hours belong to. Expanding it with ?include=user additionally requires the users::read permission and a token scope covering the users prefix.

is_not_billableboolean

is_overtimeboolean

Whether the hours count as overtime. Sending it without the times::write_overtime permission leaves it false and adds an input_ignored warning rather than failing the write.

exceeded_budgetboolean

Whether the entry was booked knowing it exceeds its budget. Set on create only, and true whenever a reason is sent; setting it puts the entry in a reviewer's queue.

reasonstring or nullDetail onlyMultiline

billable_change_reasonstring or nullDetail onlyMultiline

reviewed_byinteger or nullServer-assigned

The reviewer who settled the entry, once one has. Set by the review queue in plnnrly; this API exposes no way to write it.

invoice_idinteger or nullServer-assigned

The invoice these hours were billed on, once they have been. While it is set, the entry is locked: a write answers 409 with conflict.reason locked_by_invoice.

sales_invoice_row_idinteger or nullServer-assigned

The sales-invoice line these hours were billed on, once they have been. Set by the invoicing flow.

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

Creation timestamp.

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

Last-write timestamp; use for incremental sync.

linksTimeLinks

Show 1 child field

links.selfurl

The canonical URI of this record.

Errors

403 Forbidden.

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

forbidden-by-policy: You point the entry at something its owner may not log time on: a project_id where the owner holds no task, a task_id that is not one of the owner's own tasks, or a work_item_id the owner may not log time on. Holding times::write_on_others_tasks lifts the first two rules, never the third. You also get this answer on a colleague's entry when you hold times::delete_others but not times::update_others: either permission lets you see it, only times::update_others lets you change it.