# Create an on-call schedule rotation

Creates an on-call rotation. This creates consecutive on-call events for specified users, rotating through them until reaching the end date. This only creates events that end after 0:00 UTC today and removes any existing non-override events within this range.

[endpoint]
base_url = "https://uptime.betterstack.com"
path = "/api/v2/on-calls/{schedule_id}/rotation"
method = "POST"

[[path_param]]
name = "schedule_id"
description = "The ID of the on-call schedule you want to create the event for. Use `default` to refer to the default on-call schedule for the team."
required = true
type = "string"

[[body_param]]
name = "team_name"
description = "Required if using [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) to specify the team which should own the resource."
type = "string"

[[body_param]]
name = "users"
description = "List of email addresses of users to include in the on-call rotation schedule"
required = true
type = "array"

[[body_param]]
name = "rotation_length"
description = "The length of the specified rotation period, must be an integer"
required = true
type = "number"

[[body_param]]
name = "rotation_period"
description = "The rotation period, must be one of: `hour`, `day`, `week`"
required = true
type = "string"

[[body_param]]
name = "start_rotations_at"
description = "Start time of the rotations"
required = true
type = "date"

[[body_param]]
name = "end_rotations_at"
description = "End time of the rotations"
required = true
type = "date"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[/endpoint]

[responses]
[[response]]
status = 200
description = '''Rotation was created'''
body = '''{
  "rotation_length": 8,
  "rotation_interval": "hour",
  "start_rotations_at": "2025-02-01T07:00:00.000Z",
  "end_rotations_at": "2027-02-01T07:00:00.000Z",
  "users": [
    "bob@betterstack.com",
    "alice@betterstack.com"
  ]
}'''
[/responses]

#### Example cURL

```shell
[label Example]
curl --request POST \
  --url "https://uptime.betterstack.com/api/v2/on-calls/default/rotation" \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "users": ["bob@betterstack.com", "alice@betterstack.com"],
    "rotation_length": 8,
    "rotation_interval": "hour",
    "start_rotations_at": "2025-02-01T07:00:00Z",
    "end_rotations_at": "2027-02-01T07:00:00Z"
  }'
```