# Accept or decline a coverage request
Source: https://docs.shiftkeeper.io/api-reference/coverage/accept-or-decline-a-coverage-request
https://api.shiftkeeper.io/openapi.json post /coverage_requests/events/
Take an action on a coverage request. The coverage request must be in `pending` state.
# Cancel a coverage request
Source: https://docs.shiftkeeper.io/api-reference/coverage/cancel-a-coverage-request
https://api.shiftkeeper.io/openapi.json delete /user/coverage_requests/{coverage_request_id}
Cancel a coverage request for the authenticated user. The coverage request must be in `pending` state.
# Get a coverage request
Source: https://docs.shiftkeeper.io/api-reference/coverage/get-a-coverage-request
https://api.shiftkeeper.io/openapi.json get /coverage_requests/{coverage_request_id}
Get a coverage request by its ID.
# List coverage requests
Source: https://docs.shiftkeeper.io/api-reference/coverage/list-coverage-requests
https://api.shiftkeeper.io/openapi.json get /coverage_requests/
List all coverage requests in your organization.
# List coverage requests for the authenticated user
Source: https://docs.shiftkeeper.io/api-reference/coverage/list-coverage-requests-for-the-authenticated-user
https://api.shiftkeeper.io/openapi.json get /user/coverage_requests/
List all coverage requests for the authenticated user.
# Request coverage
Source: https://docs.shiftkeeper.io/api-reference/coverage/request-coverage
https://api.shiftkeeper.io/openapi.json post /user/coverage_requests/
Create a new coverage request for the authenticated user.
# Errors
Source: https://docs.shiftkeeper.io/api-reference/errors
Understanding API errors and status codes
We follow standard HTTP status codes to indicate API response status:
| Status | Description |
| ------ | ---------------------------------------------------------------------- |
| `400` | Failed validating your request |
| `401` | There's an issue with your API key |
| `404` | The resource you're trying to access doesn't exist |
| `422` | The request cannot be processed, check the error code for more details |
| `429` | You've exceeded the rate limits |
| `500` | An internal error occurred in our system |
## Error shape
Errors are returned as JSON, with a top-level `error` object that includes `code`, `message`, `status` and optionally `docs_url`.
Here's an example:
```json theme={null}
{
"error": {
"code": "duplicate_team_name",
"docs_url": "http://docs.shiftkeeper.io/api-reference/teams/create-a-team",
"message": "A team with this name already exists",
"status": 422
}
}
```
## Error codes
This section provides a list of error codes that the API might return.
### `bad_request`
| | |
| --------------- | --------------------------------------------------- |
| **Status** | 400 |
| **Description** | Request is invalid. |
| **Remedy** | Adjust the request body & parameters and try again. |
### `unauthorized`
| | |
| --------------- | ----------------------------------------------------------------------------------- |
| **Status** | 401 |
| **Description** | Authorization failed. |
| **Remedy** | Verify that your API key is correct and you're passing it correctly in the request. |
### `not_found`
| | |
| --------------- | ----------------------- |
| **Status** | 404 |
| **Description** | Resource not found. |
| **Remedy** | Check the resource URL. |
### `coverage_request_not_pending`
| | |
| --------------- | ---------------------------------------------------------------------------- |
| **Status** | 422 |
| **Description** | Cannot take action on a coverage request that is not in the `pending` state. |
| **Remedy** | - |
### `coverage_request_self_owned`
| | |
| --------------- | ---------------------------------------------- |
| **Status** | 422 |
| **Description** | Cannot accept or decline own coverage request. |
| **Remedy** | - |
### `too_many_shifts_in_coverage_request`
| | |
| --------------- | ---------------------------------------------------------------------------------------------- |
| **Status** | 422 |
| **Description** | There are too many shifts in the coverage request you are trying to create. |
| **Remedy** | Adjust the time interval for the coverage request so that it contains no more than 500 shifts. |
### `override_already_finished`
| | |
| --------------- | ----------------------------------------------------------------------------------------- |
| **Status** | 422 |
| **Description** | Overrides that have already finished cannot be updated or deleted. They can only be read. |
| **Remedy** | - |
### `duplicate_schedule_name`
| | |
| --------------- | ----------------------------------------- |
| **Status** | 422 |
| **Description** | A schedule with this name already exists. |
| **Remedy** | Try a different name. |
### `invalid_user_reference`
| | |
| --------------- | ---------------------------------------------------------------------------------- |
| **Status** | 422 |
| **Description** | At least one of the provided user references refers to a user that does not exist. |
| **Remedy** | Adjust the user references and try again. |
### `duplicate_team_name`
| | |
| --------------- | ------------------------------------- |
| **Status** | 422 |
| **Description** | A team with this name already exists. |
| **Remedy** | Try a different name. |
### `slack_group_permission_denied`
| | |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Status** | 422 |
| **Description** | Missing permissions to create user groups. |
| **Remedy** | Check [our guide](/shiftkeeper/schedules/slack-user-groups#troubleshooting-permission-issues) to troubleshoot Slack permissions for user groups. |
### `slack_group_only_available_for_paid_teams`
| | |
| --------------- | --------------------------------------------------- |
| **Status** | 422 |
| **Description** | User groups are available only on paid Slack plans. |
| **Remedy** | Upgrade your Slack workspace to a paid plan. |
### `slack_group_duplicate_handle_name`
| | |
| --------------- | --------------------------------------------------- |
| **Status** | 422 |
| **Description** | A Slack user group with this handle already exists. |
| **Remedy** | Try a different handle. |
### `slack_group_duplicate_name`
| | |
| --------------- | ------------------------------------------------- |
| **Status** | 422 |
| **Description** | A Slack user group with this name already exists. |
| **Remedy** | Try a different name. |
### `too_many_requests`
| | |
| --------------- | --------------------------------- |
| **Status** | 429 |
| **Description** | Rate limit exceeded. |
| **Remedy** | Wait for the rate limit to reset. |
### `internal_server_error`
| | |
| --------------- | ----------------------------------------- |
| **Status** | 500 |
| **Description** | An internal error occurred in our system. |
| **Remedy** | Try again later. |
# Getting started
Source: https://docs.shiftkeeper.io/api-reference/getting-started
Learn how to use the Shiftkeeper API
This section helps you get started with our REST API.
## Authentication
All requests to the Shiftkeeper API must be authenticated using an `x-api-key` header with your API key.
Go to [Settings > API Keys](https://app.shiftkeeper.io/settings/api) to generate your API key.
## Content types
The API accepts JSON in the request body and returns JSON in the response body.
Make sure to include the `content-type: application/json` header in your requests.
## Response codes
The API uses standard HTTP status codes to indicate the success or failure of your request.
Generally `2xx` HTTP status codes indicate success, `4xx` codes indicate client errors and `5xx` indicate errors originating from Shiftkeeper servers.
Check out the [Errors page](/api-reference/errors) for a detailed list of errors.
## Rate limits
Responses include rate limit headers that indicate the number of requests you can make in a given time period.
| Header | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `x-ratelimit-limit` | Maximum number of requests allowed within a time window |
| `x-ratelimit-remaining` | Number of requests remaining in the current time window |
| `x-ratelimit-reset` | Time in seconds until the rate limit window resets |
| `retry-after` | Time in seconds you need to wait before making another request
(only present when rate limits are exceeded) |
Our API rate limits should comfortably accommodate normal usage.
If you're facing issues with rate limits, please [contact us](mailto:support@shiftkeeper.io).
## Examples
POST /schedules
GET /user/shifts
POST /user/coverage\_requests
# Delete a schedule override
Source: https://docs.shiftkeeper.io/api-reference/overrides/delete-a-schedule-override
https://api.shiftkeeper.io/openapi.json delete /schedules/{schedule_id}/overrides/{override_id}
Delete a schedule override. Overrides that have already finished cannot be deleted.
# Get a schedule override
Source: https://docs.shiftkeeper.io/api-reference/overrides/get-a-schedule-override
https://api.shiftkeeper.io/openapi.json get /schedules/{schedule_id}/overrides/{override_id}
Get a schedule override by its ID.
# List schedule overrides
Source: https://docs.shiftkeeper.io/api-reference/overrides/list-schedule-overrides
https://api.shiftkeeper.io/openapi.json get /schedules/{schedule_id}/overrides/
List all schedule overrides in your organization.
# Override a schedule shift
Source: https://docs.shiftkeeper.io/api-reference/overrides/override-a-schedule-shift
https://api.shiftkeeper.io/openapi.json post /schedules/{schedule_id}/overrides/
Create a new schedule override.
# Attach or update the Slack user group for a schedule
Source: https://docs.shiftkeeper.io/api-reference/schedules/attach-or-update-the-slack-user-group-for-a-schedule
https://api.shiftkeeper.io/openapi.json put /schedules/{schedule_id}/slack_user_group/
Attach a Slack user group to a schedule. If the schedule already has a Slack user group attached, it will be updated.
Note that user groups are available only in paid Slack plans.
# Create a schedule
Source: https://docs.shiftkeeper.io/api-reference/schedules/create-a-schedule
https://api.shiftkeeper.io/openapi.json post /schedules/
Create a new schedule.
# Delete a schedule
Source: https://docs.shiftkeeper.io/api-reference/schedules/delete-a-schedule
https://api.shiftkeeper.io/openapi.json delete /schedules/{schedule_id}
Delete a schedule. This also removes the attached Slack user group, if there is one.
# Detach the Slack user group from a schedule
Source: https://docs.shiftkeeper.io/api-reference/schedules/detach-the-slack-user-group-from-a-schedule
https://api.shiftkeeper.io/openapi.json delete /schedules/{schedule_id}/slack_user_group/
Detach the Slack user group from a schedule. The user group will be disabled, as Slack does not allow deleting user groups. If you attach a user group to the schedule in the future, the user group will be reused and re-enabled.
# Get a schedule
Source: https://docs.shiftkeeper.io/api-reference/schedules/get-a-schedule
https://api.shiftkeeper.io/openapi.json get /schedules/{schedule_id}
Get a schedule by its ID.
# Get the Slack user group for a schedule
Source: https://docs.shiftkeeper.io/api-reference/schedules/get-the-slack-user-group-for-a-schedule
https://api.shiftkeeper.io/openapi.json get /schedules/{schedule_id}/slack_user_group/
Get the Slack user group attached to the schedule.
# Link a Slack channel to a schedule
Source: https://docs.shiftkeeper.io/api-reference/schedules/link-a-slack-channel-to-a-schedule
https://api.shiftkeeper.io/openapi.json put /schedules/{schedule_id}/slack_channels/{channel_id}
Link a Slack channel to a schedule. Shift and schedule related notifications will be sent to the channel.
Currently only public channels are supported.
# List linked schedule Slack channels
Source: https://docs.shiftkeeper.io/api-reference/schedules/list-linked-schedule-slack-channels
https://api.shiftkeeper.io/openapi.json get /schedules/{schedule_id}/slack_channels/
List all Slack channels linked to a schedule.
# List schedule shifts
Source: https://docs.shiftkeeper.io/api-reference/schedules/list-schedule-shifts
https://api.shiftkeeper.io/openapi.json get /schedules/{schedule_id}/shifts/
List all shifts for a schedule within a given time interval.
# List schedules
Source: https://docs.shiftkeeper.io/api-reference/schedules/list-schedules
https://api.shiftkeeper.io/openapi.json get /schedules/
List all schedules in your organization.
# Unlink a Slack channel from a schedule
Source: https://docs.shiftkeeper.io/api-reference/schedules/unlink-a-slack-channel-from-a-schedule
https://api.shiftkeeper.io/openapi.json delete /schedules/{schedule_id}/slack_channels/{channel_id}
Unlink a Slack channel from a schedule. Once unlinked, schedule notifications will no longer be sent to that channel.
# Update a schedule
Source: https://docs.shiftkeeper.io/api-reference/schedules/update-a-schedule
https://api.shiftkeeper.io/openapi.json patch /schedules/{schedule_id}
Update a schedule. Changes to the schedule rotation settings do not affect shifts which have already finished.
# List on-call shifts for the authenticated user
Source: https://docs.shiftkeeper.io/api-reference/shifts/list-on-call-shifts-for-the-authenticated-user
https://api.shiftkeeper.io/openapi.json get /user/shifts/
List all on-call shifts from all schedules of the authenticated user.
# Add team member
Source: https://docs.shiftkeeper.io/api-reference/teams/add-team-member
https://api.shiftkeeper.io/openapi.json put /teams/{team_id}/members/{user_id}
Add a user to a team.
# Create a team
Source: https://docs.shiftkeeper.io/api-reference/teams/create-a-team
https://api.shiftkeeper.io/openapi.json post /teams/
Create a new team.
# Delete a team
Source: https://docs.shiftkeeper.io/api-reference/teams/delete-a-team
https://api.shiftkeeper.io/openapi.json delete /teams/{team_id}
Delete a team. Deleting a team does not remove the linked schedules.
# Get a team
Source: https://docs.shiftkeeper.io/api-reference/teams/get-a-team
https://api.shiftkeeper.io/openapi.json get /teams/{team_id}
Get a team by its ID.
# Get team member
Source: https://docs.shiftkeeper.io/api-reference/teams/get-team-member
https://api.shiftkeeper.io/openapi.json get /teams/{team_id}/members/{user_id}
Check if a user is a member of a team. A `204` response indicates that the user is a member of the team.
# List team members
Source: https://docs.shiftkeeper.io/api-reference/teams/list-team-members
https://api.shiftkeeper.io/openapi.json get /teams/{team_id}/members/
List all members of a team.
# List teams
Source: https://docs.shiftkeeper.io/api-reference/teams/list-teams
https://api.shiftkeeper.io/openapi.json get /teams/
List all teams in your organization.
# Remove team member
Source: https://docs.shiftkeeper.io/api-reference/teams/remove-team-member
https://api.shiftkeeper.io/openapi.json delete /teams/{team_id}/members/{user_id}
Remove a user from a team.
# Update a team
Source: https://docs.shiftkeeper.io/api-reference/teams/update-a-team
https://api.shiftkeeper.io/openapi.json patch /teams/{team_id}
Update the team's details.
# Get a user
Source: https://docs.shiftkeeper.io/api-reference/users/get-a-user
https://api.shiftkeeper.io/openapi.json get /users/{user_id}
Get a user by their ID.
# Get the authenticated user
Source: https://docs.shiftkeeper.io/api-reference/users/get-the-authenticated-user
https://api.shiftkeeper.io/openapi.json get /user/
Get the authenticated user who owns this API key.
# List users
Source: https://docs.shiftkeeper.io/api-reference/users/list-users
https://api.shiftkeeper.io/openapi.json get /users/
List all users in the organization.
# Versions
Source: https://docs.shiftkeeper.io/api-reference/versions
Learn about how we version our API
We version our API. This page describes the versioning strategy, version history,
and how to specify a version in your requests.
The API version name matches the date of the release of the API. This is often referred to as calendar versioning.
The first and current API version is `2024-12-01`.
Non-breaking changes will be released across all active versions. For example:
* adding optional fields to request schemas
* adding fields to response schemas
* adding new endpoints
* adding response headers
* adding new response status codes to an endpoint
* adding new error types to response schemas
* extending enum types in the request and response schemas, i.e., adding new values
Breaking changes will be released in a new version.
These are changes that might break the existing interface or potentially the way you are using the API. For example:
* removing or renaming fields in the request schemas
* adding required fields to request schemas
* removing or renaming fields in the response schemas
* removing endpoints
Generally we try to avoid breaking changes and rather extend the API in a compatible way.
## Specifying a version
Use the `x-shiftkeeper-api-version` request header to specify the API version, for example, `x-shiftkeeper-api-version: 2024-12-01`.
If no version is specified, the latest version will be used. We recommend always specifying the version in your requests to avoid any breaking changes.
Specifying a version that does not exist or is no longer supported will result in an HTTP `400` error.
## Version history
| Version | Description |
| ------------ | --------------- |
| `2024-12-01` | Initial release |
# Core Concepts
Source: https://docs.shiftkeeper.io/getting-started/core
A brief overview of the core concepts in Shiftkeeper
## Schedules
The [schedule](shiftkeeper/schedules/) is the most basic concept in Shiftkeeper. It determines who should be on-call for a given time period.
At its core, a schedule consists of a group of users and rotation settings. The rotation settings determine how often and when the schedule shifts are rotated
among the users in the rotation.
Schedules are typically used to rotate roles or responsibilities among a group of users. For example, you might use a schedule to rotate incident response responsibilities
or support hero duties.
### Shifts
A shift represents an interval of time during which a user is on-call for a given schedule.
### Overrides
[Overrides](shiftkeeper/schedules/overrides/) enable you to make one-off changes to a schedule, without disrupting your rotation settings.
This is useful when schedule members are unavailable for a shift they are assigned to, e.g., due to vacation, sick leave, etc.
## Coverage requests
[Coverage requests](/shiftkeeper/coverage) enable you to ask for coverage from your teammates without the back-and-forth.
You choose the time interval you need coverage for and Shiftkeeper takes care of notifying the right people.
## Teams
A [team](shiftkeeper/teams/) is a collection of users. Teams enable you to group and filter schedules.
They are also used to determine which users a coverage request should be sent to.
## Using Shiftkeeper
You interact with Shiftkeeper in multiple ways: in Slack, in the web app and via the API.
The guides in the documentation cover both Slack and the web app.
The [API reference](/api-reference/) describes the API endpoints and how to use them.
# Introduction
Source: https://docs.shiftkeeper.io/getting-started/introduction
Welcome to Shiftkeeper
## Overview
These documentation pages help you learn about Shiftkeeper's features and how to use them.
## Quick start
Learn about rotation types, restriction intervals, on-call group size and more.
View upcoming on-call shifts and see who is on-call for a schedule.
Learn how to easily ask teammates to cover your shifts when you are unavailable.
Attach a Slack user group to your schedule and Shiftkeeper keeps it in sync.
# Coverage
Source: https://docs.shiftkeeper.io/shiftkeeper/coverage
Request shift coverage from teammates without the back-and-forth
Coverage requests enable you to ask for coverage from your teammates without the back-and-forth.
You choose the time interval you need coverage for and Shiftkeeper takes care of notifying the right people.
Once someone accepts your coverage request, you will be notified and the shifts will be reassigned to that user.
## Creating a coverage request
1. Enter the `/keeper-cover` command anywhere in Slack.
2. Enter the time interval you need coverage for and the reason.
3. (Optional) Refine the selection of schedules you need coverage for. By default, all schedules are selected.
4. Submit your coverage request.
You can also request coverage from the Shiftkeeper *home tab* in Slack.
1. Go to [Coverage Requests](https://app.shiftkeeper.io/coverage) and click on `Ask for Coverage`.
2. Enter the time interval you need coverage for and the reason.
3. (Optional) Refine the selection of shifts you need coverage for. By default, all shifts within the selected time interval are selected.
4. Submit your coverage request.
### Who is notified about my coverage request?
Your coverage request is sent to all users who are part of the schedules selected in your request. The members of the teams linked to the schedules
are also notified.
## What happens when I accept a coverage request?
When you accept a coverage request, the shifts listed in the coverage request are automatically reassigned to you using overrides.
The user who requested coverage is notified that their request has been accepted.
## Coverage requests vs overrides
As you might have noticed, coverage requests and overrides serve a similar purpose:
they both enable you to substitute a schedule user when they are unavailable for their on-call shifts, but the approach is different.
Most of the time, you'll likely want to use coverage requests. They make the process of aligning with everyone involved easier.
While with overrides you typically need to align with the involved users and consider their availabilities manually, which can be time consuming.
Here a few tips to help you decide which one to use:
Use **Coverage requests** when:
* You are unavailable for a period of time and need someone to cover your shifts.
* It is not relevant who specifically covers your shifts, i.e., anyone can accept your coverage request.
* You need coverage for multiple shifts across multiple schedules.
Use **Overrides** when:
* You need to reassign certain shifts in a schedule to specific users.
* You need to extend a shift outside of the applied restriction intervals for that schedule.
# On-call shifts
Source: https://docs.shiftkeeper.io/shiftkeeper/oncalls
View your on-call shifts and export them to your calendar app
1. Go to the Shiftkeeper home tab.
2. Click on the `My shift calendar` button.
Simply go to the [On-call Shifts](https://app.shiftkeeper.io/oncalls) page.
The calendar view also enables to you take quick actions on a shift, e.g., [override a shift](/shiftkeeper/schedules/overrides) or [ask for coverage](/shiftkeeper/coverage).
## Calendar app integration
You can export your on-call shifts across all schedules to your calendar app, e.g., Google Calendar, Apple Calendar, Outlook, etc.
To export only a single schedule, refer to the [schedule shift calendar](/shiftkeeper/schedules/shift-calendar) guide instead.
### Exporting your on-call shifts to your calendar app
The guide below refers the Apple Calendar app. The flow is similar for other calendar apps.
1. Go to the Shiftkeeper home tab.
2. Click on the `My shift calendar` button to view your shifts and scroll down to the `⬆️ Export` section.
3. Click on the `Export` button and copy the displayed iCal URL.
4. Open the Apple Calendar app.
5. Choose `File > New Calendar Subscription`.
6. Enter the copied iCal URL, then click `Subscribe`.
7. Adjust the subscription settings as preferred and click `OK`.
1. Go to the [On-call Shifts](https://app.shiftkeeper.io/oncalls) page.
2. Click on the `Export` button.
3. Copy the displayed iCal URL.
4. Open the Apple Calendar app.
5. Choose `File > New Calendar Subscription`.
6. Enter the copied iCal URL, then click `Subscribe`.
7. Adjust the subscription settings as preferred and click `OK`.
Any changes to your on-call shifts will be reflected in the calendar feed automatically, no manual updates are needed.
Changes might take some time to be reflected in your calendar, depending on the auto-refresh period you have selected for the calendar subscription.
Shifts which have finished more than two months ago are not exposed in the calendar feed.
### Calendar alerts
By default, the calendar feed is setup to trigger a notification 15 minutes before your on-call shift starts. You can disable these notifications
when creating the calendar subscription.
### Calendar app subscription guides
Below you can find a few guides on how to create calendar subscriptions in popular calendar apps.
* [Apple Calendar](https://support.apple.com/guide/calendar/subscribe-to-calendars-icl1022/mac)
* [Google Calendar](https://support.google.com/calendar/answer/37100), under the `Use a link to add a public calendar` section
* [Outlook](https://support.microsoft.com/en-us/office/import-or-subscribe-to-a-calendar-in-outlook-com-or-outlook-on-the-web-cff1429c-5af6-41ec-a5b4-74f2c278e98c)
# Overrides
Source: https://docs.shiftkeeper.io/shiftkeeper/schedules/overrides
Quickly adjust schedule shifts ad-hoc
Overrides enable you to make one-off changes to a schedule, without disrupting your rotation settings.
This is useful when schedule members are unavailable for a shift they are assigned to, e.g., due to vacation, sick leave, etc.
## Creating an override
1. Go to the Shiftkeeper home tab.
2. In the schedule list, click on the `...` button and then `View calendar`.
3. Pick a shift to override, click on the `...` button and then `Override shift`.
4. Select the user(s) who should take over the shift.
5. (Optional) Adjust the override start and end time. By default, these correspond to the selected shift's start and end time.
6. Save the override.
1. Open a schedule from the [Schedules](https://app.shiftkeeper.io/schedules) page.
2. Click on a shift and then click on the `Override` button.
3. Select the user(s) who should take over the shift.
4. (Optional) Adjust the override start and end time. By default, these correspond to the selected shift's start and end time.
5. Save the override.
Shifts which have already finished cannot be overridden.
Once created, you can see the override in the schedule shift calendar as well as the updated final schedule.
If the override start is in the past, the override will be truncated to start at the current time.
If two or more overrides overlap, the more recent overrides take precedence.
## Deleting an override
If an override is no longer needed, you can simply delete it.
1. Go to the Shiftkeeper home tab.
2. In the schedule list, click on the `...` button and then `View calendar`.
3. Scroll down to the `Upcoming Overrides` section and click the `View all` button.
4. Select the override you want to delete and click the `Delete` button.
Overrides that have already finished cannot be deleted. Only present and upcoming overrides can be deleted.
## When should I use coverage requests instead?
Overrides and coverage requests serve a similar purpose, enabling you to substitute schedule users when they are unavailable for a shift.
However, overrides have a shortcoming due to the fact that you need to align with the involved users and consider their availabilities manually.
This can be time consuming, especially when there are many users involved. Coverage requests make this process easier.
Check out the [coverage request vs overrides section](/shiftkeeper/coverage#coverage-requests-vs-overrides) for a detailed comparison.
# Schedules
Source: https://docs.shiftkeeper.io/shiftkeeper/schedules/schedules
All about schedules and rotation settings in Shiftkeeper
## Overview
Schedules determine who should be on-call for a given time period.
At its core, a schedule consists of a group of users and rotation settings.
This guide will walk you through the process of creating schedules, editing them, and understanding how the rotation settings work.
## Creating a schedule
1. Enter the `/keeper-schedule` command anywhere in Slack.
2. Name your schedule and select the users who should be in the rotation.
3. Set the rotation settings, e.g., rotate shifts daily starting from today at 09:00.
4. Preview your schedule and save it.
You can also create schedules from the Shiftkeeper *home tab* in Slack.
1. Go to [Schedules](https://app.shiftkeeper.io/schedules) and click on `New Schedule`.
2. Name your schedule and select the users who should be in the rotation.
3. Set the rotation settings, e.g., rotate shifts daily starting from today at 09:00.
4. Save your schedule.
The schedule time zone is preselected based on your Slack profile time zone. If you would like to use a different one, simply pick another time zone from the dropdown.
### Rotation settings
Rotation settings determine how often and when schedule shifts rotate.
You can choose to rotate shifts daily, weekly, bi-weekly, or on a custom interval, e.g., every 12 hours.
The start date and time of the rotation determines when the first shift in the schedule starts.
When setting up the rotation, you'll a see a helpful hint that explicitly shows the shift handoff time and day.
If you set the rotation start in the past, the first shift will be truncated to start at the current time.
The shift handoff time is still based on the specified rotation start time.
The order of the users in the list determines the order in which they'll be on-call for the schedule.
A user can appear multiple times in the rotation order. This is useful in cases where you need to distribute the shifts unevenly across users.
#### Restriction intervals
By default, schedule shifts cover every day of the week. Restriction intervals allow you to restrict your schedule shifts to specific times, e.g., only business hours.
When creating a schedule in Slack, go to `Additional settings` to set up restriction intervals.
#### On-call group size
You can adjust the on-call group size for a schedule, which is by default set to one.
This enables you to have multiple responders on-call concurrently, without having to deal with multiple schedules.
When creating a schedule in Slack, go to `Additional settings` to change the on-call group size.
### Schedule preview
While creating a schedule, you can preview the shift calendar.
This enables you to check whether the rotation and schedule settings are correct.
### Notifications
Shiftkeeper sends Slack notifications to the on-call users at the beginning of a shift.
You can [link Slack channels](/shiftkeeper/schedules/slack-channels) to schedules to receive notifications about shift and schedule changes.
Shiftkeeper also enables you to [attach Slack user groups](/shiftkeeper/schedules/slack-user-groups) to schedules.
The member list of the user group is automatically updated to contain the users who are on-call for the schedule.
This way you can easily mention your on-call teammates across Slack.
## Editing a schedule
1. Go to the Shiftkeeper home tab.
2. In the schedule list, click on the `...` button and then `Edit settings`.
3. Apply the changes and save.
1. Go to [Schedules](https://app.shiftkeeper.io/schedules) or to a specific schedule.
2. Click on the `Edit` button.
3. Apply the changes and save.
Changes to the schedule rotation settings do not affect shifts which have already finished.
The schedule time zone cannot be changed after creation. We might remove this limitation in the future.
## Schedule examples
Here are a few practical examples of schedule configurations to help you get started.
### Weekly rotation with two concurrent on-call users
### Daily rotation restricted to business hours
### Custom rotation with a 12-hour interval
# Shift calendar
Source: https://docs.shiftkeeper.io/shiftkeeper/schedules/shift-calendar
View the shift calendar for a schedule
The schedule calendar displays all past and upcoming shifts for a schedule.
1. Go to the Shiftkeeper home tab.
2. In the schedule list, click on the `...` button and then `View calendar`.
Simply open any schedule from the [Schedules](https://app.shiftkeeper.io/schedules) page.
The calendar view also enables to you take quick actions on a shift, e.g., [override a shift](/shiftkeeper/schedules/overrides).
## Calendar app integration
You can export schedules to your calendar app, e.g., Google Calendar, Apple Calendar, Outlook, etc.
To export only your own on-call shifts, refer to the [on-call shifts](/shiftkeeper/oncalls) guide instead.
### Exporting a schedule to your calendar app
The guide below refers the Apple Calendar app. The flow is similar for other calendar apps.
1. Go to the Shiftkeeper home tab.
2. In the schedule list, click on the `...` button and then `Export`.
3. Copy the displayed iCal URL.
4. Open the Apple Calendar app.
5. Choose `File > New Calendar Subscription`.
6. Enter the copied iCal URL, then click `Subscribe`.
7. Adjust the subscription settings as preferred and click `OK`.
1. Go to your schedule via the [Schedules](https://app.shiftkeeper.io/schedules) page.
2. Click on the `Export` button.
3. Copy the displayed iCal URL.
4. Open the Apple Calendar app.
5. Choose `File > New Calendar Subscription`.
6. Enter the copied iCal URL, then click `Subscribe`.
7. Adjust the subscription settings as preferred and click `OK`.
Any changes to the schedule shifts will be reflected in the calendar feed automatically, no manual updates are needed.
Changes might take some time to be reflected in your calendar, depending on the auto-refresh period you have selected for the calendar subscription.
Shifts which have finished more than two months ago are not exposed in the calendar feed.
### Removing a schedule from your calendar app
To remove a schedule from your calendar app, simply delete the calendar subscription.
For example, in the Apple Calendar app, you can do this by right-clicking on the calendar from the list, and then choosing `Unsubscribe`.
### Calendar app subscription guides
Below you can find a few guides on how to create calendar subscriptions in popular calendar apps.
* [Apple Calendar](https://support.apple.com/guide/calendar/subscribe-to-calendars-icl1022/mac)
* [Google Calendar](https://support.google.com/calendar/answer/37100), under the `Use a link to add a public calendar` section
* [Outlook](https://support.microsoft.com/en-us/office/import-or-subscribe-to-a-calendar-in-outlook-com-or-outlook-on-the-web-cff1429c-5af6-41ec-a5b4-74f2c278e98c)
# Slack channels
Source: https://docs.shiftkeeper.io/shiftkeeper/schedules/slack-channels
Keep your team updated about shift and schedule changes
You can link Slack channels to schedules to receive notifications about shift and schedule changes.
Linked channels are currently limited to public channels only.
## Linking and unlinking channels to schedules
After creating a schedule, you will be prompted about linking Slack channels to the newly created schedule.
To link channels to an existing schedule:
1. Go to the Shiftkeeper home tab.
2. In the schedule list, click on the `...` button and then `Edit settings`.
3. Scroll down to the `Slack channels` section and add the channels.
1. Go to your schedule via the [Schedules](https://app.shiftkeeper.io/schedules) page.
2. Click on the `Edit` button and go to the `Notifications` tab.
3. Add the channels you would like to link and save the changes.
You can unlink schedule channels in a similar way.
# Slack user groups
Source: https://docs.shiftkeeper.io/shiftkeeper/schedules/slack-user-groups
Easily mention on-call teammates across Slack
Shiftkeeper enables you to attach a Slack user group to a schedule.
The member list of the user group is automatically updated to only contain the users who are on-call for the schedule at any given time.
This way you can easily mention your on-call teammates across Slack.
User groups are available only in paid Slack plans.
## Attaching a Slack user group to a schedule
After creating a schedule, you will be prompted about attaching a Slack user group to the newly created schedule.
The name, handle, and description of the user group are automatically given sensible defaults based on your schedule name.
Review the inputs and save.
To attach a user group to an existing schedule:
1. Go to the Shiftkeeper home tab.
2. In the schedule list, click on the `...` button and then `Edit settings`.
3. Scroll down to the `Slack user group` section and attach the user group.
1. Go to your schedule via the [Schedules](https://app.shiftkeeper.io/schedules) page.
2. Click on the `Attach Slack user group` button.
3. Review the inputs and save.
In case you are getting a permission-related error, check out the [Troubleshooting](#troubleshooting-permission-issues) section.
## Detaching the Slack user group from a schedule
1. Go to the Shiftkeeper home tab.
2. In the schedule list, click on the `...` button and then `Edit settings`.
3. Scroll down to the `Slack user group` section and detach the user group.
1. Go to your schedule via the [Schedules](https://app.shiftkeeper.io/schedules) page.
2. Click on the `Edit` button and go to the `Notifications` tab.
3. Deselect the `Attach a Slack user group` checkbox and save.
Once detached from the schedule, the user group will be disabled in Slack.
User groups in Slack cannot be deleted, only disabled.
## Behavior when no one is on-call
When no one is on-call for a given schedule, the user group (if one is attached) will contain the Shiftkeeper bot user.
This is a workaround to avoid disabling the user group in Slack.
Slack does not allow removing all members from a user group.
## Troubleshooting permission issues
By default, Slack restricts permissions to create and manage user groups to `workspace admins and owners only`.
If this is the case in your workspace, Shiftkeeper will impersonate the installing user to create and manage user groups.
You can check your workspace's user group settings [in Slack](https://slack.com/admin/settings#user_group_restrictions).
If you are getting a permission-related error, it is likely that the user who installed Shiftkeeper in your workspace does not have the necessary permissions to create and manage user groups.
In that case, please ask an admin in your Slack workspace who has the necessary permissions to re-install Shiftkeeper.
Alternatively, you can [change the user group restrictions](https://slack.com/admin/settings#user_group_restrictions) in your workspace to allow `everyone, except guests` to create and manage user groups.
If you're still getting an error, please [contact us](mailto:support@shiftkeeper.io).
### Using a Slack service account
When user group management is restricted to `workspace admins and owners only`, Shiftkeeper needs to impersonate the installing user to update
the user group member list in Slack. This might be a bit confusing, as it appears as if the installing user applied the changes to the user group.
To avoid this, you can use a separate Slack user account with admin permissions to install Shiftkeeper in your workspace.
This is often referred to as a `service account` or a `technical user account`. Note that Slack does not differentiate service accounts and normal accounts,
so the service account is still a normal user account. It does not affect your [Slack billing](https://slack.com/intl/en-gb/help/articles/218915077-Slacks-fair-billing-policy#how-inactive-deactivated-members-affect-billing).
To use a service account for Shiftkeeper:
1. [Invite a new user](https://slack.com/help/articles/201330256-Invite-new-members-to-your-workspace) to your Slack workspace.
You could use an email alias to avoid creating a new email address.
2. Set the name to something along the lines of `Shiftkeeper Service Account` for clarity.
3. [Make this user an admin](https://slack.com/intl/en-gb/help/articles/218124397-Change-a-member%E2%80%99s-role#manage-owner-and-admin-roles) in your Slack workspace.
4. Go to our [installation page](https://app.shiftkeeper.io/install) to re-install Shiftkeeper in your workspace using the service account (You need to be logged out from the Shiftkeeper web app).
Shiftkeeper will now use this service account to create and manage user groups.
Another advantage with using service accounts is that the app installation is not tied to a specific member in your Slack workspace.
This is useful because Slack automatically removes apps installed by users who leave the workspace, potentially causing disruptions.
We therefore recommend using the service account approach also for installing other apps in your Slack workspace.
# Teams
Source: https://docs.shiftkeeper.io/shiftkeeper/teams
Group and filter schedules
Teams enable you to group and filter schedules. They are also used to determine which users a coverage request should be sent to.
In the future, we might extend the functionality around teams, e.g., to enable fine-grained access control.
## Creating a team
1. Go to the Shiftkeeper home tab.
2. Click on the `Manage teams` button and then `New team`.
3. Enter the name & description of the team and save it.
4. Once created, you will be prompted to add members to the team.
1. Go to [Teams](https://app.shiftkeeper.io/teams) and click on `New team`.
2. Enter the name & description of the team and save it.
3. You can now add members to the teams.
Adding members to a team is also straightforward.
## Linking teams to schedules
You can link to teams during a schedule during the creation. Go to the `Additional settings` section and select the teams you would like to add.
To link teams to an existing schedule, simply edit the schedule settings.
# API
Source: https://docs.shiftkeeper.io/shiftkeeper/workspace/api
Build your own workflows with our API
The Shiftkeeper API enables you build your own integrations on top of Shiftkeeper.
Anything you can do in the web and Slack app, you can also do via the API.
## Getting started
First generate an API key by going to [Settings > API Keys](https://app.shiftkeeper.io/settings/api).
Then head over to the [API reference](/api-reference) to learn how to use the API.
# Billing and plans
Source: https://docs.shiftkeeper.io/shiftkeeper/workspace/billing-and-plans
Manage your billing information and plans
## Plans
Our [pricing page](https://shiftkeeper.io/pricing) contains all the information about the plans we offer.
## Free trial
All plans include a 14-day free trial, no credit card required. Once your free trial is over,
you need to upgrade to a paid plan to continue using Shiftkeeper.
## Billing
You are billed based on the number of [member](http://localhost:3000/shiftkeeper/workspace/users#member) seats in your workspace.
Users with the `viewer` seat do not incur any billing costs.
### Frequency
You can choose between monthly or annual billing.
You are billed on a monthly basis for the number of users with `member` seats in your workspace.
Adding or removing `member` seats in the middle of a month will not result in a charge or credit for the remaining days of the month.
The billing changes will take effect at the beginning of the following month.
You are billed on a yearly basis for the number of users with `member` seats in your workspace.
Your annual subscription is billed upfront based on the number of `member` seats in your workspace at the time your subscription starts.
Adding a `member` seat to your workspace results in a pro-rated charge for the remainder of the subscription year.
Similarly, removing a `member` seat results in a pro-rated credit. These billing adjustments are processed at the beginning of each month.
Any credits resulting from subscription changes will be applied against future charges and cannot be refunded.
You can switch between monthly and annual billing at any time. Any charges or credits resulting from the switch will be pro-rated.
### Manage your billing information
Go to [Settings > Billing and plans](https://app.shiftkeeper.io/settings/billing) to manage your billing information.
From this page you can view and manage your current plan, change your payment details, update the billing email address, etc...
Only owners can view and manage billing information.
### Cancelling your subscription
Go to [Settings > Billing and plans](https://app.shiftkeeper.io/settings/billing) to cancel your subscription.
Your subscription will remain active until the end of your current billing period.
We do not offer refunds for subscriptions cancelled before the end of the billing period.
### Refunds for VAT
We offer VAT refunds for European businesses and recognize tax-exempt organizations.
To avoid VAT charges in the first place, please enter your company details and VAT number during checkout.
If you've already completed the payment, you can request a VAT refund directly at [Paddle](https://paddle.net/), our payments processor.
Contact their support team at [assist@paddle.com](mailto:assist@paddle.com).
## Discounts for non-profit organizations
We are happy to offer a discount for non-profit organizations. [Contact us](mailto:support@shiftkeeper.io) and we will get you sorted.
# Users
Source: https://docs.shiftkeeper.io/shiftkeeper/workspace/users
Manage your Shiftkeeper workspace users
This page describes all you need to know about managing users in your Shiftkeeper workspace.
## Inviting users to Shiftkeeper
Users are automatically added to Shiftkeeper when they first interact with it through Slack or the web interface.
While manual invitations aren't necessary, you can still do so, for example,
if you want to invite a user to Shiftkeeper on the `owner` role right away.
To invite a user:
1. Go to [Settings > Users](https://app.shiftkeeper.io/settings/users) and click on `Invite user`.
2. Search the user by their name in Slack.
3. Select the role and the seat you want to assign to the user.
4. Click on `Invite`.
## Roles
There are currently two user roles in Shiftkeeper: `owner` and `standard`.
Users with the `owner` role can:
* view and change billing information
* manage user roles and seats
* perform all `standard` role actions
Users with the `standard` role can access all other Shiftkeeper features.
The user that first installs Shiftkeeper in your Slack workspace is automatically granted the `owner` role.
## Seats
Seats are mainly relevant for [billing](/shiftkeeper/workspace/billing-and-plans).
There are two types of seats in Shiftkeeper: `member` and `viewer`.
### Member
Users with `member` seats are users who are actively using Shiftkeeper. They can use all Shiftkeeper features.
### Viewer
Users with `viewer` seats can use Shiftkeeper, but not be part of any schedules or teams. As a viewer, you can:
* view schedules, shift calendars, coverage requests, etc...
* create teams, schedules, overrides, etc...
Users with this seat can only be assigned the `standard` role.
Users with the `viewer` seat do not incur any billing costs.
Users are automatically assigned a `member` seat when they are added to a schedule or team.
## Changing a user's role and seat
1. Go to [Settings > Users](https://app.shiftkeeper.io/settings/users).
2. Select a user from the list and click on the `Edit` button.
3. Select the role and the seat you want to assign to the user.
4. Save the changes.
Only owners can change user seats and roles.