Skip to content

API reference

My shifts

A person's own published shifts, open shifts to claim, swap and give-away requests, when they can't work and their shift emails (calendar feeds are created in the app).

7 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.

My shifts#

POST/v1/shifts/my.listRead

Your published shifts from today to 4 weeks ahead (drafts never show), with who else is on that day (names only), what changed in the last publish and the reason recorded when it changed inside the notice window; your next shift; open shifts on your rotas you can ask to claim; your open requests; whether you get shift emails.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
shifts_my_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

7 fields
  • todaystringrequired
  • nextobject | nullrequired

    Your next shift (it may have started already today).

    15 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • break_minutesintegerrequired
    • minutesintegerrequired
    • starts_atstringrequired

      The instant it starts (ISO, UTC).

    • rotaobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • locationstring | nullrequired
      • timezonestringrequired
    • weekstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • notestring | nullrequired
    • colleaguesobject[]required

      Others on the same rota that day (names only).

      2 fields
      • idstringrequired
      • namestringrequired
    • changedbooleanrequired

      Changed in the last publish of its week.

    • reason"agreed" | "asked" | "force_majeure" | "short_change" | "other"required

      The reason recorded when it changed inside the notice window.

    • reason_notestring | nullrequired

      Always null: an "other" reason's free text stays with the rota's editors and HR (the history).

  • shiftsobject[]required

    Your published shifts, today to 4 weeks ahead.

    15 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • break_minutesintegerrequired
    • minutesintegerrequired
    • starts_atstringrequired

      The instant it starts (ISO, UTC).

    • rotaobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • locationstring | nullrequired
      • timezonestringrequired
    • weekstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • notestring | nullrequired
    • colleaguesobject[]required

      Others on the same rota that day (names only).

      2 fields
      • idstringrequired
      • namestringrequired
    • changedbooleanrequired

      Changed in the last publish of its week.

    • reason"agreed" | "asked" | "force_majeure" | "short_change" | "other"required

      The reason recorded when it changed inside the notice window.

    • reason_notestring | nullrequired

      Always null: an "other" reason's free text stays with the rota's editors and HR (the history).

  • open_shiftsobject[]required

    Open published shifts on your rotas you can ask to claim.

    12 fields
    • idstringrequired
    • datestringrequired
    • startstringrequired
    • endstringrequired
    • break_minutesintegerrequired
    • minutesintegerrequired
    • starts_atstringrequired

      The instant it starts (ISO, UTC).

    • rotaobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • locationstring | nullrequired
      • timezonestringrequired
    • weekstringrequired
    • positionobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • colorstring (enum)required

        One of: teal, rose, violet, slate, amber, blue, green, orange, pink, indigo.

    • notestring | nullrequired
    • requestedbooleanrequired
  • rotasobject[]required

    The rotas you are on.

    2 fields
    • idstringrequired
    • namestringrequired
  • requestsintegerrequired

    Your open shift requests and offers to you.

  • emailsbooleanrequired

    Whether you get shift emails (the inbox and push always).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/my.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "today": "2026-11-12",
    "next": {
      "id": "sh_1",
      "date": "2026-11-16",
      "start": "12:00",
      "end": "20:00",
      "break_minutes": 60,
      "minutes": 420,
      "starts_at": "2026-11-16T12:00:00.000Z",
      "rota": {
        "id": "r1",
        "name": "Kitchen",
        "location": "Lisbon shop",
        "timezone": "Europe/Lisbon"
      },
      "week": "2026-W47",
      "position": {
        "id": "pos1",
        "name": "Till",
        "color": "amber"
      },
      "note": "Opens the kitchen",
      "colleagues": [
        {
          "id": "p2",
          "name": "Bea Lima"
        }
      ],
      "changed": true,
      "reason": "agreed",
      "reason_note": null
    },
    "shifts": [
      {
        "id": "sh_1",
        "date": "2026-11-16",
        "start": "12:00",
        "end": "20:00",
        "break_minutes": 60,
        "minutes": 420,
        "starts_at": "2026-11-16T12:00:00.000Z",
        "rota": {
          "id": "r1",
          "name": "Kitchen",
          "location": "Lisbon shop",
          "timezone": "Europe/Lisbon"
        },
        "week": "2026-W47",
        "position": {
          "id": "pos1",
          "name": "Till",
          "color": "amber"
        },
        "note": "Opens the kitchen",
        "colleagues": [
          {
            "id": "p2",
            "name": "Bea Lima"
          }
        ],
        "changed": true,
        "reason": "agreed",
        "reason_note": null
      }
    ],
    "open_shifts": [
      {
        "id": "sh_2",
        "date": "2026-11-18",
        "start": "09:00",
        "end": "17:00",
        "break_minutes": 60,
        "minutes": 420,
        "starts_at": "2026-11-18T09:00:00.000Z",
        "rota": {
          "id": "r1",
          "name": "Kitchen",
          "location": "Lisbon shop",
          "timezone": "Europe/Lisbon"
        },
        "week": "2026-W47",
        "position": null,
        "note": null,
        "requested": false
      }
    ],
    "rotas": [
      {
        "id": "r1",
        "name": "Kitchen"
      }
    ],
    "requests": 1,
    "emails": true
  }
}

When I can't work#

POST/v1/shifts/my.availability.listRead

The times you said you can't work: weekly (e.g. Wednesdays after 16:00) and dated days, with your private notes (in the app only: an API key or AI app never sees them). Editors see them as a warning when planning, never the notes; it is not an approval.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
Keys and apps
Never the private notes.
MCP tool
shifts_my_availability_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    6 fields
    • idstringrequired
    • weekdayinteger | nullrequired
    • datestring | nullrequired
    • fromstring | nullrequired
    • tostring | nullrequired
    • notestring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/my.availability.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "av1",
        "weekday": 3,
        "date": null,
        "from": "16:00",
        "to": null,
        "note": "Childcare"
      }
    ]
  }
}

Set when I can't work#

POST/v1/shifts/my.availability.setWrite

Replaces the times you can't work (items, the whole list, at most 50): weekday (1 Monday … 7 Sunday) or date, from and to (HH:MM; both left out: the whole day), and an optional private note (in the app only: an API key or AI app neither reads nor writes notes, and keeps existing ones). Past dated days are dropped. Editors see them as a warning when planning (Código do Trabalho art. 221 n.º 2: shifts follow preferences as far as possible); it is not a request.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
Keys and apps
Notes are neither read nor written; existing notes are kept.
MCP tool
shifts_my_availability_set on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • itemsobject[]required

    Up to 50 items.

    5 fields
    • weekdayinteger | null

      Every week on this day (1 Monday … 7 Sunday).

      From 1 to 7.

    • datestring | null

      Or one dated day.

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • fromstring | null

      Pattern ^([01]\d|2[0-3]):[0-5]\d$.

    • tostring | null

      Leave both out for the whole day; from alone: from then on.

      Pattern ^([01]\d|2[0-3]):[0-5]\d$.

    • notestring | null

      Private: you and HR, in the app.

      Up to 200 characters.

Returns

  • itemsobject[]required
    6 fields
    • idstringrequired
    • weekdayinteger | nullrequired
    • datestring | nullrequired
    • fromstring | nullrequired
    • tostring | nullrequired
    • notestring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/my.availability.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "items": [
    {
      "weekday": 3,
      "from": "16:00",
      "note": "Childcare"
    },
    {
      "date": "2026-11-27",
      "from": null,
      "to": null,
      "note": null
    }
  ]
}'
Response
{
  "data": {
    "items": [
      {
        "id": "av1",
        "weekday": 3,
        "date": null,
        "from": "16:00",
        "to": null,
        "note": "Childcare"
      }
    ]
  }
}

My shift emails#

POST/v1/shifts/my.settings.updateWrite

Turns your shift emails on or off (emails). The inbox notice and push on your phone stay.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
shifts_my_settings_update on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • emailsbooleanrequired

Returns

  • emailsbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/my.settings.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"emails":false}'
Response
{
  "data": {
    "emails": false
  }
}

My shift calendar feeds#

POST/v1/shifts/feeds.listRead

Your shift calendar feeds (private ICS links in Google, Outlook or Apple Calendar): last 4 characters, when created and last read. The links are shown only once, when created.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
shifts_feeds_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    4 fields
    • idstringrequired
    • last4stringrequired
    • created_atstringrequired
    • last_used_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/feeds.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "f1",
        "last4": "x9Qa",
        "created_at": "2026-11-10T10:00:00.000Z",
        "last_used_at": null
      }
    ]
  }
}

Create a shift calendar feed#

POST/v1/shifts/feeds.createWrite

Creates a private calendar link (ICS) of your published shifts, from a month back to 8 weeks ahead, each titled "Shift · <rota>" (never notes). Shown once: keep it private, revoke it any time. At most 5. In the app only.

Web app only
Refused for API keys and connected apps. Calendar feed links are created in the app (the link is a secret).
MCP tool
shifts_feeds_create on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

No input: send {}.

Returns

  • idstringrequired
  • urlstringrequired

    The feed address (contains its secret; shown only now).

  • last4stringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/feeds.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
Response
{
  "data": {
    "id": "f1",
    "url": "https://api.bizisy.test/feeds/shifts/bzsh_org1234567_secret.ics",
    "last4": "x9Qa"
  }
}

Revoke a shift calendar feed#

POST/v1/shifts/feeds.revokeDestructive

Turns a shift calendar feed off: its link stops working at once. Your own; owners, admins and HR any.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
shifts_feeds_revoke on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • feed_idstringrequired

    1–100 characters.

Returns

  • idstringrequired
  • revokedtruerequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/shifts/feeds.revoke \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"feed_id":"f1"}'
Response
{
  "data": {
    "id": "f1",
    "revoked": true
  }
}

Something missing or wrong on this page? Write to hello@bizisy.com.

Developer docs