Log time

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

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

Books minutes against a project on one calendar day and returns the entry with a Location header.

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: Needs 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: Log two and a half hours on a work item

curl -X POST \
  'https://<your-url>/api/v2/worklogs' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-key-0001' \
  -d '{
    "project_id": 12,
    "work_item_id": 41,
    "task_id": 88,
    "date": "2026-09-10",
    "minutes": 150,
    "description": "Reviewed the invoice export and fixed the rounding"
  }'

const response = await fetch('https://<your-url>/api/v2/worklogs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'example-key-0001',
  },
  body: JSON.stringify({
    "project_id": 12,
    "work_item_id": 41,
    "task_id": 88,
    "date": "2026-09-10",
    "minutes": 150,
    "description": "Reviewed the invoice export and fixed the rounding"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', 'example-key-0001')
    ->post('https://<your-url>/api/v2/worklogs', [
        'project_id' => 12,
        'work_item_id' => 41,
        'task_id' => 88,
        'date' => '2026-09-10',
        'minutes' => 150,
        'description' => 'Reviewed the invoice export and fixed the rounding',
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/worklogs',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': 'example-key-0001'},
    json={'project_id': 12, 'work_item_id': 41, 'task_id': 88, 'date': '2026-09-10', 'minutes': 150, 'description': 'Reviewed the invoice export and fixed the rounding'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "date": "2026-09-10",
    "minutes": 150,
    "description": "Reviewed the invoice export and fixed the rounding",
    "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/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."
    }
  ]
}

13 more fields, listed under Response

user_id is not accepted: the hours belong to the authenticated user unless on_behalf_of_user_id names someone else, and logging time for another user additionally requires times::update_others, enforced by that field. Every check inside the write (whether that person may log time on the project, owns the task and may log time on the work item) is evaluated against the person the hours are for, not against you, so is_overtime is dropped when they lack times::write_overtime even if you hold it. One exception, which plnnrly's own form shares: the check that project, task and budget fit together weighs the task against you, so filing hours on somebody else's task needs times::write_on_others_tasks from the caller as well. A task or work item that does not belong to the submitted project is a 422 on its own field; a task or work item you may read but may not book against is a 403. budget_id is derived from the task and never accepted. is_not_billable is inferred from the task when omitted; sending a value that differs from the inference requires billable_change_reason, answering 422 on /billable_change_reason without it. Sending a reason marks the entry as exceeding its budget whether or not exceeded_budget is sent alongside. Either an exceeded budget or a billability override puts the entry in a reviewer's queue, and while it sits there every write to it by anyone but its author or a reviewer answers 409. Idempotency-Key is required here: a retried time entry is real, invoiced damage. The API is stricter than plnnrly here: a task is accepted only if you can also see it on the tasks collection, so a caller holding times::write_on_others_tasks but not kanban::manage_for_others gets a 422 exists for a task plnnrly would accept.

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≤ 255Required

A caller-chosen key that makes this POST safe to retry. Required on this operation: omitting it is 400 idempotency-key-required.

Request body

Unknown keys are refused with 422, naming the key.

project_idinteger → Project.idRequired

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

datedate (YYYY-MM-DD)Required

The calendar day the work happened.

minutesinteger1 to 1440Required

Duration in minutes, between 1 and 1440.

descriptionstring≤ 255Required

What the employee worked on.

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.

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 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.

on_behalf_of_user_idinteger → User.id

Write-only, on create only: the employee to file the hours for. Omit it to file them for yourself. Naming anyone else requires the times::update_others permission, and every check inside the write (whether that person may log on the project and on that task, and whether overtime may be recorded) is then evaluated against them, not against you.

Response 201

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

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.