Update an absence

PATCHhttps://<your-url>/api/v2/absences/{absence}

MCP id absences.updateAlso on this path: GET Read an absence, DELETE Delete an absence

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

Token scope: api:write:absences
Without it: 403 insufficient-token-scope.
Permission: absences::manage
Without it: 403 insufficient-permission.
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: Close a running absence

curl -X PATCH \
  'https://<your-url>/api/v2/absences/1' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: *' \
  -d '{
    "end": "2026-03-06T17:00:00Z"
  }'

const response = await fetch('https://<your-url>/api/v2/absences/1', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'If-Match': '*',
  },
  body: JSON.stringify({
    "end": "2026-03-06T17:00:00Z"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('If-Match', '*')
    ->patch('https://<your-url>/api/v2/absences/1', [
        'end' => '2026-03-06T17:00:00Z',
    ]);

import requests
response = requests.request(
    'PATCH',
    'https://<your-url>/api/v2/absences/1',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'If-Match': '*'},
    json={'end': '2026-03-06T17:00:00Z'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "user_id": 1,
    "user": {
      "id": 1
    },
    "manager_id": 1,
    "manager": null,
    "start": "2026-03-02T08:00:00Z",
    "end": "2026-03-06T17:00:00Z",
    "created_at": "2026-03-04T09:15:00Z",
    "updated_at": "2026-03-04T09:15:00Z",
    "links": {
      "self": "https://<your-url>/api/v2/work-items/1"
    }
  }
}

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

Send end to close a running absence, or end: null to reopen one; send manager_id: null to detach the manager. user_id may be moved to another employee. start and end are stored exactly as sent, with no timezone conversion. Naming a user_id or manager_id additionally requires read access to users (users::read) and a token covering that prefix. Note: end is only checked against start when both are sent in the same request, so sending end alone can leave it before the stored start; an absence in that state counts as zero minutes everywhere it is read. 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, so two writes inside the same second are indistinguishable.

Path parameters

absenceintegerRequired

The Absence'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.

user_idinteger → User.id

The employee this absence is for. Writing it requires the absences::manage permission.

manager_idinteger or null → User.id

Manager who filed or approved the absence, or null when none was recorded. The foreign key nulls on delete, so removing the manager leaves the absence behind unattributed.

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

When the absence begins. RFC 3339 UTC.

endtimestamp (YYYY-MM-DDThh:mm:ssZ) or null

When the absence ends, or null while it is still running. An ongoing absence reaches through now everywhere it is read (planning capacity and reporting both count it), and that reach is uncapped, so an absence nobody closed keeps consuming capacity. RFC 3339 UTC.

Must be on or after start.

Response 200

Returns a Absence 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