Create a schedule

POST

schedules

curl --request POST \
  --url https://api.shiftkeeper.io/schedules/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "name": "Incident responders",
  "description": "Incident responders",
  "time_zone": "Europe/Berlin",
  "layers": [
    {
      "name": "Main",
      "rotation_start": "2024-01-01T00:00:00Z",
      "concurrent_oncall_users": 1,
      "user_references": [
        {
          "type": "email",
          "value": "rick@example.org"
        },
        {
          "type": "email",
          "value": "dena@example.org"
        },
        {
          "type": "email",
          "value": "lily@example.org"
        }
      ],
      "shift_length": {
        "amount": 1,
        "unit": "weeks"
      }
    }
  ],
  "team_ids": [
    "tea_VJ4sYEOOXVvJBXqFjRzpm"
  ]
}'

{
  "schedule": {
    "name": "Incident responders",
    "description": "Incident responders",
    "time_zone": "Europe/Berlin",
    "layers": [
      {
        "name": "Main",
        "rotation_start": "2024-01-01T00:00:00Z",
        "concurrent_oncall_users": 1,
        "users": [
          {
            "id": "usr_bq7CmsOKLmkMeZkUUu1hy",
            "name": "Rick",
            "email": "rick@example.org",
            "time_zone": "Europe/Paris",
            "role": "owner",
            "seat": "member",
            "slack_id": "U082KENSEQ3"
          },
          {
            "id": "usr_C0GwCFdk0I4pBMRny4qYV",
            "name": "Dena",
            "email": "dena@example.org",
            "role": "standard",
            "seat": "member",
            "slack_id": "U082GMAFR1T"
          },
          {
            "id": "usr_YlxrjoB1JqUsollScfFYT",
            "name": "Lily",
            "email": "lily@example.org",
            "time_zone": "America/New_York",
            "role": "standard",
            "seat": "viewer",
            "slack_id": "U0529FWNCG2"
          }
        ],
        "shift_length": {
          "amount": 1,
          "unit": "weeks"
        },
        "restriction_intervals": []
      }
    ],
    "current_revision": 1,
    "current_revision_valid_from": "2024-12-01T00:00:00Z",
    "current_oncall_shift": {
      "users": [
        {
          "id": "usr_bq7CmsOKLmkMeZkUUu1hy",
          "name": "Rick",
          "email": "rick@example.org",
          "time_zone": "Europe/Paris",
          "role": "owner",
          "seat": "member",
          "slack_id": "U082KENSEQ3"
        }
      ],
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-01T01:00:00Z"
    },
    "next_oncall_shift": {
      "users": [
        {
          "id": "usr_C0GwCFdk0I4pBMRny4qYV",
          "name": "Dena",
          "email": "dena@example.org",
          "role": "standard",
          "seat": "member",
          "slack_id": "U082GMAFR1T"
        }
      ],
      "start": "2024-01-01T01:00:00Z",
      "end": "2024-01-01T02:00:00Z"
    },
    "users": [
      {
        "id": "usr_bq7CmsOKLmkMeZkUUu1hy",
        "name": "Rick",
        "email": "rick@example.org",
        "time_zone": "Europe/Paris",
        "role": "owner",
        "seat": "member",
        "slack_id": "U082KENSEQ3"
      },
      {
        "id": "usr_C0GwCFdk0I4pBMRny4qYV",
        "name": "Dena",
        "email": "dena@example.org",
        "role": "standard",
        "seat": "member",
        "slack_id": "U082GMAFR1T"
      },
      {
        "id": "usr_YlxrjoB1JqUsollScfFYT",
        "name": "Lily",
        "email": "lily@example.org",
        "time_zone": "America/New_York",
        "role": "standard",
        "seat": "viewer",
        "slack_id": "U0529FWNCG2"
      }
    ],
    "teams": [
      {
        "id": "tea_VJ4sYEOOXVvJBXqFjRzpm",
        "name": "Payments",
        "description": "All about payments and billing"
      }
    ]
  }
}

Authorizations

x-api-key

string

header

required

Enter your API key which starts with 'keeper_'

Body

application/json

name

string

required

The name of the schedule.

Required string length: 1 - 60

time_zone

string

required

The time zone of the schedule. Must be a valid IANA time zone. Note that the time zone cannot be changed after the schedule is created.

layers

object[]

required

The layers of the schedule. Currently, schedules can have only one layer.

team_ids

string[]

required

The teams to link to the schedule.

description

string

The description of the schedule.

Maximum length: 200

Response

200

application/json

Default Response

schedule

object

required

schedule.name

string

required

The name of the schedule.

Required string length: 1 - 60

schedule.time_zone

string

required

The IANA time zone of the schedule.

schedule.layers

object[]

required

The layers of the schedule.

schedule.layers.name

string

required

The name of the schedule layer.

Required string length: 1 - 60

schedule.layers.rotation_start

string

required

The start date and time of the rotation. ISO 8601 format, UTC timezone.

schedule.layers.concurrent_oncall_users

integer

required

The number of concurrent on-call users for this layer.

Required range: 1 <= x <= 4

schedule.layers.users

object[]

required

The rotation users in the schedule layer. The order of the users in the array determines the round-robin rotation order. A user can appear multiple times in the rotation.

schedule.layers.shift_length

object

required

Determines how often shifts are rotated.

schedule.layers.restriction_intervals

object[]

Determines the time intervals that the layer is restricted to. Useful if you want to limit the on-call hours to specific times, e.g., only during business hours. If not provided, the layer is unrestricted and covers everyday of the week.

schedule.teams

object[]

required

The teams linked to the schedule.

schedule.current_revision

integer

required

The current revision of the schedule. A new revision is created every time the schedule layer configuration is changed.

Required range: x >= 0

schedule.current_revision_valid_from

string

required

The timestamp that marks the start of the current revision.

schedule.users

object[]

required

The users in the schedule. The order does not necessarily match rotation order.

schedule.description

string

The description of the schedule.

Maximum length: 200

schedule.current_oncall_shift

object

The current on-call shift for the schedule.

schedule.next_oncall_shift

object

The next on-call shift for the schedule.

Example:

{
  "name": "Incident responders",
  "description": "Incident responders",
  "time_zone": "Europe/Berlin",
  "layers": [
    {
      "name": "Main",
      "rotation_start": "2024-01-01T00:00:00Z",
      "concurrent_oncall_users": 1,
      "users": [
        {
          "id": "usr_bq7CmsOKLmkMeZkUUu1hy",
          "name": "Rick",
          "email": "rick@example.org",
          "time_zone": "Europe/Paris",
          "role": "owner",
          "seat": "member",
          "slack_id": "U082KENSEQ3"
        },
        {
          "id": "usr_C0GwCFdk0I4pBMRny4qYV",
          "name": "Dena",
          "email": "dena@example.org",
          "role": "standard",
          "seat": "member",
          "slack_id": "U082GMAFR1T"
        },
        {
          "id": "usr_YlxrjoB1JqUsollScfFYT",
          "name": "Lily",
          "email": "lily@example.org",
          "time_zone": "America/New_York",
          "role": "standard",
          "seat": "viewer",
          "slack_id": "U0529FWNCG2"
        }
      ],
      "shift_length": { "amount": 1, "unit": "weeks" },
      "restriction_intervals": []
    }
  ],
  "current_revision": 1,
  "current_revision_valid_from": "2024-12-01T00:00:00Z",
  "current_oncall_shift": {
    "users": [
      {
        "id": "usr_bq7CmsOKLmkMeZkUUu1hy",
        "name": "Rick",
        "email": "rick@example.org",
        "time_zone": "Europe/Paris",
        "role": "owner",
        "seat": "member",
        "slack_id": "U082KENSEQ3"
      }
    ],
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-01T01:00:00Z"
  },
  "next_oncall_shift": {
    "users": [
      {
        "id": "usr_C0GwCFdk0I4pBMRny4qYV",
        "name": "Dena",
        "email": "dena@example.org",
        "role": "standard",
        "seat": "member",
        "slack_id": "U082GMAFR1T"
      }
    ],
    "start": "2024-01-01T01:00:00Z",
    "end": "2024-01-01T02:00:00Z"
  },
  "users": [
    {
      "id": "usr_bq7CmsOKLmkMeZkUUu1hy",
      "name": "Rick",
      "email": "rick@example.org",
      "time_zone": "Europe/Paris",
      "role": "owner",
      "seat": "member",
      "slack_id": "U082KENSEQ3"
    },
    {
      "id": "usr_C0GwCFdk0I4pBMRny4qYV",
      "name": "Dena",
      "email": "dena@example.org",
      "role": "standard",
      "seat": "member",
      "slack_id": "U082GMAFR1T"
    },
    {
      "id": "usr_YlxrjoB1JqUsollScfFYT",
      "name": "Lily",
      "email": "lily@example.org",
      "time_zone": "America/New_York",
      "role": "standard",
      "seat": "viewer",
      "slack_id": "U0529FWNCG2"
    }
  ],
  "teams": [
    {
      "id": "tea_VJ4sYEOOXVvJBXqFjRzpm",
      "name": "Payments",
      "description": "All about payments and billing"
    }
  ]
}

List schedules Get a schedule

curl --request POST \
  --url https://api.shiftkeeper.io/schedules/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "name": "Incident responders",
  "description": "Incident responders",
  "time_zone": "Europe/Berlin",
  "layers": [
    {
      "name": "Main",
      "rotation_start": "2024-01-01T00:00:00Z",
      "concurrent_oncall_users": 1,
      "user_references": [
        {
          "type": "email",
          "value": "rick@example.org"
        },
        {
          "type": "email",
          "value": "dena@example.org"
        },
        {
          "type": "email",
          "value": "lily@example.org"
        }
      ],
      "shift_length": {
        "amount": 1,
        "unit": "weeks"
      }
    }
  ],
  "team_ids": [
    "tea_VJ4sYEOOXVvJBXqFjRzpm"
  ]
}'

{
  "schedule": {
    "name": "Incident responders",
    "description": "Incident responders",
    "time_zone": "Europe/Berlin",
    "layers": [
      {
        "name": "Main",
        "rotation_start": "2024-01-01T00:00:00Z",
        "concurrent_oncall_users": 1,
        "users": [
          {
            "id": "usr_bq7CmsOKLmkMeZkUUu1hy",
            "name": "Rick",
            "email": "rick@example.org",
            "time_zone": "Europe/Paris",
            "role": "owner",
            "seat": "member",
            "slack_id": "U082KENSEQ3"
          },
          {
            "id": "usr_C0GwCFdk0I4pBMRny4qYV",
            "name": "Dena",
            "email": "dena@example.org",
            "role": "standard",
            "seat": "member",
            "slack_id": "U082GMAFR1T"
          },
          {
            "id": "usr_YlxrjoB1JqUsollScfFYT",
            "name": "Lily",
            "email": "lily@example.org",
            "time_zone": "America/New_York",
            "role": "standard",
            "seat": "viewer",
            "slack_id": "U0529FWNCG2"
          }
        ],
        "shift_length": {
          "amount": 1,
          "unit": "weeks"
        },
        "restriction_intervals": []
      }
    ],
    "current_revision": 1,
    "current_revision_valid_from": "2024-12-01T00:00:00Z",
    "current_oncall_shift": {
      "users": [
        {
          "id": "usr_bq7CmsOKLmkMeZkUUu1hy",
          "name": "Rick",
          "email": "rick@example.org",
          "time_zone": "Europe/Paris",
          "role": "owner",
          "seat": "member",
          "slack_id": "U082KENSEQ3"
        }
      ],
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-01T01:00:00Z"
    },
    "next_oncall_shift": {
      "users": [
        {
          "id": "usr_C0GwCFdk0I4pBMRny4qYV",
          "name": "Dena",
          "email": "dena@example.org",
          "role": "standard",
          "seat": "member",
          "slack_id": "U082GMAFR1T"
        }
      ],
      "start": "2024-01-01T01:00:00Z",
      "end": "2024-01-01T02:00:00Z"
    },
    "users": [
      {
        "id": "usr_bq7CmsOKLmkMeZkUUu1hy",
        "name": "Rick",
        "email": "rick@example.org",
        "time_zone": "Europe/Paris",
        "role": "owner",
        "seat": "member",
        "slack_id": "U082KENSEQ3"
      },
      {
        "id": "usr_C0GwCFdk0I4pBMRny4qYV",
        "name": "Dena",
        "email": "dena@example.org",
        "role": "standard",
        "seat": "member",
        "slack_id": "U082GMAFR1T"
      },
      {
        "id": "usr_YlxrjoB1JqUsollScfFYT",
        "name": "Lily",
        "email": "lily@example.org",
        "time_zone": "America/New_York",
        "role": "standard",
        "seat": "viewer",
        "slack_id": "U0529FWNCG2"
      }
    ],
    "teams": [
      {
        "id": "tea_VJ4sYEOOXVvJBXqFjRzpm",
        "name": "Payments",
        "description": "All about payments and billing"
      }
    ]
  }
}

Using the API

Schedules

Overrides

Coverage

Shifts

Users

Teams

Authorizations

Body

Response