Create a free day

POSThttps://<your-url>/api/v2/free-days

MCP id free-days.storeAlso on this path: GET List free days

Creates one free day and returns it with a Location header.

Token scope: api:write:free_days
Without it: 403 insufficient-token-scope.
Permission: free_days::manage
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 manually added closure day

curl -X POST \
  'https://<your-url>/api/v2/free-days' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "description": "Office closed for the annual outing",
    "date": "2026-07-03"
  }'

const response = await fetch('https://<your-url>/api/v2/free-days', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "description": "Office closed for the annual outing",
    "date": "2026-07-03"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/free-days', [
        'description' => 'Office closed for the annual outing',
        'date' => '2026-07-03',
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/free-days',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'description': 'Office closed for the annual outing', 'date': '2026-07-03'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "description": "Office closed for the annual outing",
    "date": "2026-07-03",
    "holiday_id": 1,
    "holiday": null,
    "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/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."
    }
  ]
}

description is required and is not derived from holiday_id: for a holiday-derived day plnnrly copies the holiday name into it at creation time and the two drift independently, so send the label you want. Nothing enforces one free day per date: plnnrly's year generation skips an already-used date, but this endpoint does not, and a duplicate date is a plain 201. To generate a year of free days from the recurring holidays, call this endpoint once per holiday.

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.

descriptionstring≤ 255Required

Label for the free day, e.g. Christmas Day. For a holiday-derived day this is a copy of the holiday name taken when the free day was created, so renaming the holiday does not rewrite it.

datedate (YYYY-MM-DD)Required

Calendar date the organisation is closed.

holiday_idinteger or null → Holiday.id

Recurring holiday this free day instantiates, or null for a day added by hand. The foreign key nulls on delete, so removing the holiday leaves the free day behind as a manual day still carrying the copied label.

Response 201

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