Using the API
Schedules
- GETList schedules
- POSTCreate a schedule
- GETGet a schedule
- DELDelete a schedule
- PATCHUpdate a schedule
- GETList schedule shifts
- GETGet the Slack user group for a schedule
- PUTAttach or update the Slack user group for a schedule
- DELDetach the Slack user group from a schedule
- GETList linked schedule Slack channels
- PUTLink a Slack channel to a schedule
- DELUnlink a Slack channel from a schedule
Overrides
Coverage
Create a schedule
Create a new 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"
}
]
}
}Authorizations
Enter your API key which starts with 'keeper_'
Body
The name of the schedule.
1 - 60The 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.
The layers of the schedule. Currently, schedules can have only one layer.
The name of the schedule layer.
1 - 60The start date and time of the rotation. ISO 8601 format, UTC timezone.
The number of concurrent on-call users for this layer.
1 < x < 4Determines 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.
The day of the restriction interval.
monday, tuesday, wednesday, thursday, friday, saturday, sunday The start time of the restriction interval.
The end time of the restriction interval.
The teams to link to the schedule.
The description of the schedule.
200Response
The name of the schedule.
1 - 60The IANA time zone of the schedule.
The layers of the schedule.
The name of the schedule layer.
1 - 60The start date and time of the rotation. ISO 8601 format, UTC timezone.
The number of concurrent on-call users for this layer.
1 < x < 4The 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.
The ID of the user.
The name of the user.
The email of the user.
The role of the user. Learn more about roles in our docs.
owner, standard The seat of the user. Learn more about seat in our docs.
viewer, member The preferred time zone of the user. If not set, the organization's time zone will be used.
The Slack ID of the user.
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.
The day of the restriction interval.
monday, tuesday, wednesday, thursday, friday, saturday, sunday The start time of the restriction interval.
The end time of the restriction interval.
The current revision of the schedule. A new revision is created every time the schedule layer configuration is changed.
x > 0The timestamp that marks the start of the current revision.
The users in the schedule. The order does not necessarily match rotation order.
The ID of the user.
The name of the user.
The email of the user.
The role of the user. Learn more about roles in our docs.
owner, standard The seat of the user. Learn more about seat in our docs.
viewer, member The preferred time zone of the user. If not set, the organization's time zone will be used.
The Slack ID of the user.
The description of the schedule.
200The current on-call shift for the schedule.
The users on-call for this shift.
The ID of the user.
The name of the user.
The email of the user.
The role of the user. Learn more about roles in our docs.
owner, standard The seat of the user. Learn more about seat in our docs.
viewer, member The preferred time zone of the user. If not set, the organization's time zone will be used.
The Slack ID of the user.
The start time of the on-call shift.
The end time of the on-call shift.
The next on-call shift for the schedule.
The users on-call for this shift.
The ID of the user.
The name of the user.
The email of the user.
The role of the user. Learn more about roles in our docs.
owner, standard The seat of the user. Learn more about seat in our docs.
viewer, member The preferred time zone of the user. If not set, the organization's time zone will be used.
The Slack ID of the user.
The start time of the on-call shift.
The end time of the on-call shift.
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"
}
]
}
}