API Reference

Shifts

Clock in and out, query shift status, and manage scheduled shifts and time entries. Protected endpoints are available to any authenticated staff member; admin-only endpoints require administrator privileges.

Staff Endpoints

Available to any authenticated user. Each staff member can manage their own clock-in status.

Clock In

POST/api/shifts/clock-inProtected

Records the current timestamp as the start of the staff member's shift.

bash

curl -X POST https://api.possfer.com/api/shifts/clock-in \
  -H "Authorization: Bearer <token>"

json

{
  __PH0__: {
    __PH1__: "te-a1b2c3d4-5678-90ab-cdef-444444444444",
    __PH3__: "u-550e8400-e29b-41d4-a716-446655440000",
    __PH5__: "2026-03-20T08:00:00Z",
    __PH7__: null,
    __PH8__: 0
  }
}

Warning

A staff member cannot clock in if they already have an open shift. The API will return 409 Conflict in that case.

Clock Out

POST/api/shifts/clock-outProtected

Closes the staff member's current open shift. Optionally specify break minutes.

Request Body (optional)

Name	Type	Required	Description
`break_minutes`	`integer`	Optional	Total break time in minutes taken during this shift. Defaults to 0.

bash

curl -X POST https://api.possfer.com/api/shifts/clock-out \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "break_minutes": 30 }'

json

{
  __PH0__: {
    __PH1__: "te-a1b2c3d4-5678-90ab-cdef-444444444444",
    __PH3__: "u-550e8400-e29b-41d4-a716-446655440000",
    __PH5__: "2026-03-20T08:00:00Z",
    __PH7__: "2026-03-20T16:30:00Z",
    __PH9__: 30
  }
}

My Shift Status

GET/api/shifts/my-statusProtected

Check whether the authenticated user is currently clocked in.

bash

curl https://api.possfer.com/api/shifts/my-status \
  -H "Authorization: Bearer <token>"

json

{
  __PH0__: true,
  __PH1__: {
    __PH2__: "te-a1b2c3d4-5678-90ab-cdef-444444444444",
    __PH4__: "2026-03-20T08:00:00Z",
    __PH6__: null,
    __PH7__: 0
  }
}

Admin Endpoints

Manage scheduled shifts and view time entries across all staff members. Requires administrator privileges.

List Shifts

GET/api/shiftsAdmin Only

Retrieve scheduled shifts, optionally filtered by date range.

Query Parameters

Name	Type	Required	Description
`date_from`	`string (YYYY-MM-DD)`	Optional	Start date for the filter range (inclusive).
`date_to`	`string (YYYY-MM-DD)`	Optional	End date for the filter range (inclusive).

bash

curl __PH1__Authorization: Bearer <token>"

json

{
  __PH0__: [
    {
      __PH1__: "sh-b2c3d4e5-6789-01ab-cdef-555555555555",
      __PH3__: "u-550e8400-e29b-41d4-a716-446655440000",
      __PH5__: "Max Mustermann",
      __PH7__: "2026-03-20",
      __PH9__: "08:00",
      __PH11__: "16:00",
      __PH13__: 30,
      __PH14__: "waiter",
      __PH16__: "confirmed",
      __PH18__: null,
      __PH19__: "2026-03-10T14:00:00Z"
    }
  ]
}

Create Shift

POST/api/shiftsAdmin Only

Schedule a new shift for a staff member.

Request Body

Name	Type	Required	Description
`user_id`	`string (UUID)`	Required	ID of the staff member to assign.
`shift_date`	`string (YYYY-MM-DD)`	Required	Date the shift takes place.
`start_time`	`string (HH:MM)`	Required	Scheduled start time (24-hour format).
`end_time`	`string (HH:MM)`	Required	Scheduled end time (24-hour format).
`break_minutes`	`integer`	Optional	Planned break duration in minutes.
`role`	`string`	Optional	Role during this shift, e.g. "waiter", "cook", "cashier".
`notes`	`string`	Optional	Free-text notes visible to the staff member.

bash

curl -X POST https://api.possfer.com/api/shifts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "u-550e8400-e29b-41d4-a716-446655440000",
    "shift_date": "2026-03-21",
    "start_time": "10:00",
    "end_time": "18:00",
    "break_minutes": 30,
    "role": "waiter",
    "notes": "Training day - shadow senior staff"
  }'

Update Shift

PUT/api/shifts/:idAdmin Only

Partially update a scheduled shift. Only included fields are changed.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	Unique identifier of the shift.

bash

curl -X PUT https://api.possfer.com/api/shifts/sh-b2c3d4e5-6789-01ab-cdef-555555555555 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "end_time": "20:00",
    "notes": "Extended shift - busy evening expected"
  }'

Update Shift Status

PATCH/api/shifts/:id/statusAdmin Only

Change the status of a scheduled shift (e.g. confirm, cancel).

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	Unique identifier of the shift.

Request Body

Name	Type	Required	Description
`status`	`"pending" \| "confirmed" \| "cancelled"`	Required	The new status for the shift.

bash

curl -X PATCH https://api.possfer.com/api/shifts/sh-b2c3d4e5-6789-01ab-cdef-555555555555/status \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "confirmed" }'

Delete Shift

DELETE/api/shifts/:idAdmin Only

Remove a scheduled shift. Returns 204 No Content on success.

Path Parameters

Name	Type	Required	Description
`id`	`string (UUID)`	Required	Unique identifier of the shift to delete.

bash

curl -X DELETE https://api.possfer.com/api/shifts/sh-b2c3d4e5-6789-01ab-cdef-555555555555 \
  -H "Authorization: Bearer <token>"

List Time Entries

Retrieve clock-in/clock-out records across all staff for a given date.

GET/api/time-entriesAdmin Only

Returns all time entries for the restaurant, filtered by date.

Query Parameters

Name	Type	Required	Description
`date`	`string (YYYY-MM-DD)`	Optional	Filter entries to a specific date. Defaults to today.

bash

curl __PH1__Authorization: Bearer <token>"

json

{
  __PH0__: [
    {
      __PH1__: "te-a1b2c3d4-5678-90ab-cdef-444444444444",
      __PH3__: "u-550e8400-e29b-41d4-a716-446655440000",
      __PH5__: "Max Mustermann",
      __PH7__: "2026-03-20T08:00:00Z",
      __PH9__: "2026-03-20T16:30:00Z",
      __PH11__: 30,
      __PH12__: 8.0
    }
  ]
}