Guides
Log InStart Free Trial
Start typing to search…

Schedule Rotation API

🚧

If using the EU instance of Opsgenie, the URL needs to be https://api.eu.opsgenie.com for requests to be successful.

General Information

📘

Create anAPI Integration and obtain your apiKey to make requests listed above. Please make sure that the integration is not restricted to access configurations.

📘

All requests ofSchedule Rotation API work under Schedule domain. It means that; If you are using apiKey belongs to a team integration, that team must allowed to access given schedule. Otherwise, we would respond with 403 - Forbidden (Unauthorized) with 40301 internal code Response

Create Schedule Rotation

Create schedule rotation request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

HTTP Method

URL

POST

https://api.opsgenie.com/v2/schedules/:scheduleIdentifier/rotations

In-Line Parameters

Referred Name

Description

scheduleIdentifier

Identifier of the schedule

Query Parameters

Parameter

Mandatory

Description

scheduleIdentifierType

false

Type of the schedule identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

JSON Body Fields

Fields

Mandatory

Description

name

false

Name of rotation

startDate

true

This parameter takes a date format as (yyyy-MM-dd'T'HH:mm:ssZ) (e.g. 2017-01-15T08:00:00+02:00). Minutes may take 0 or 30 as value. Otherwise they will be converted to nearest 0 or 30 automatically

endDate

false

This parameter takes a date format as (yyyy-MM-dd'T'HH:mm:ssZ) (e.g. 2017-01-15T08:00:00+02:00) Minutes may take 0 or 30 as value. Otherwise they will be converted to nearest 0 or 30 automatically

type

true

Type of rotation. May be one of daily, weekly and hourly

length

false

Length of the rotation with default value 1

participants

true

List of escalations, teams, users or the reserved word none which will be used in schedule. Each of them can be used multiple times and will be rotated in the order they given. The possible values for participants are:

  • user
  • escalation
  • team
  • none
    You can refer below for example values

timeRestriction

false

You can refer Time Restriction for detailed information about time restriction and its fields

🚧

If participants' type is escalation or team, you can use name or id fields for referring. Otherwise (type is user), we use username or id for referencing

participants field example:

{
    "participants": [
        {
            "type": "team",
            "id": "b3578948-55b3-4acc-9bf1-2ce2db3alpa2"
        },
        {
            "type": "user",
            "username": "[email protected]"
        },
        {
            "type": "none"
        }
    ]
}

Sample Requests

curl -X POST  'https://api.opsgenie.com/v2/schedules/ScheduleName/rotations?scheduleIdentifierType=name'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'
    --header 'Content-Type: application/json'
    --data
'{
	"name": "Second Rotation",
	"startDate": "2017-02-06T05:00:00Z",
	"endDate": "2017-02-23T06:00:00Z",
	"type": "hourly",
	"length": 6,
	"participants": [
		{
			"type": "user",
			"username": "[email protected]"
		},
		{
			"type": "user",
			"username": "[email protected]"
		},
		{
			"type": "user",
			"id": "4a9alp7-b5d2-4ecb-b82c-e3b5286829cf"
		}
	],
	"timeRestriction": {
		"type" : "weekday-and-time-of-day",
		"restrictions" : [
			{
    			"startDay" : "monday",
    			"startHour" : 8,
    			"startMin" : 0,
    			"endDay" : "tuesday",
    			"endHour" : 18,
    			"endMin" : 30
			},
			{
    			"startDay" : "wednesday",
    			"startHour" : 8,
    			"startMin" : 0,
    			"endDay" : "thursday",
    			"endHour" : 18,
    			"endMin" : 30
			}
		]
	}
}'

Response:

{
    "result": "Created",
    "data": {
        "id": "af962100-c958-48cd-98ca-fc09c5alp5c9",
        "name": "Second Rotation"
    },
    "took": 1.02,
    "requestId": "24aa11a2-alp3-4645-a7b2-9b6ad978830c"
}

Get Schedule Rotation

HTTP Method

URL

GET

https://api.opsgenie.com/v2/schedules/:scheduleIdentifier/rotations/:id

In-Line Parameters

Referred Name

Description

scheduleIdentifier

Identifier of the schedule

id

Id of the schedule rotation

Query Parameters

Parameter

Mandatory

Description

scheduleIdentifierType

false

Type of the schedule identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

Sample Request

curl -X GET  'https://api.opsgenie.com/v2/schedules/ScheduleName/rotations/13a3alp1-5f0c-4370-a033-87a7f3be5d0e?scheduleIdentifierType=name'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response:

{
    "data": {
        "id": "af962100-c958-48cd-98ca-fc09alp4e5c9",
        "name": "Second Rotation",
        "startDate": "2017-02-06T05:00:00Z",
        "endDate": "2017-02-23T06:00:00Z",
        "type": "hourly",
        "length": 6,
        "participants": [
            {
                "type": "user",
                "id": "a9514028-2bca-4510-a51f-4b65alp33a56",
                "username": "[email protected]"
            },
            {
             "type": "user",
            "id": "00564944-balp-4b95-a882-ee9a5aaab9bb",
            "username": "[email protected]"
            }
        ],
        "timeRestriction": {
            "type": "weekday-and-time-of-day",
            "restrictions": [
                {
                    "startDay": "monday",
                    "endDay": "tuesday",
                    "startHour": 8,
                    "endHour": 18,
                    "startMin": 0,
                    "endMin": 30
                },
                {
                    "startDay": "wednesday",
                    "endDay": "thursday",
                    "startHour": 8,
                    "endHour": 18,
                    "startMin": 0,
                    "endMin": 30
                }
            ]
        },
        "_parent": {
            "id": "d875e654-9b4e-4219-a803-0c2693alp8de",
            "name": "ScheduleName",
            "enabled": true
        }
    },
    "took": 0.118,
    "requestId": "072ealp38-427c-4c41-897d-d336831cf3a5"
}

Update Schedule Rotation (Partial)

Update schedule rotation request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

HTTP Method

URL

PATCH

https://api.opsgenie.com/v2/schedules/:scheduleIdentifier/rotations/:id

In-Line Parameters

Referred Name

Description

scheduleIdentifier

Identifier of the schedule

id

Id of the schedule rotation

Query Parameters

Parameter

Mandatory

Description

scheduleIdentifierType

false

Type of the schedule identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

JSON Body Fields

Fields

Mandatory

Description

name

false

Name of rotation

startDate

false

This parameter takes a date format as (yyyy-MM-dd'T'HH:mm:ssZ) (e.g. 2017-01-15T08:00:00+02:00). Minutes may take 0 or 30 as value. Otherwise they will be converted to nearest 0 or 30 automatically

endDate

false

This parameter takes a date format as (yyyy-MM-dd'T'HH:mm:ssZ) (e.g. 2017-01-15T08:00:00+02:00) Minutes may take 0 or 30 as value. Otherwise they will be converted to nearest 0 or 30 automatically

type

false

Type of rotation. May be one of daily, weekly and hourly

length

false

Length of the rotation with default value 1

participants

false

List of escalations, teams, users or the reserved word none which will be used in schedule. Each of them can be used multiple times and will be rotated in the order they given. The possible values for participants are:

  • user
  • escalation
  • team
  • none
    You can refer below for example values

timeRestriction

false

You can refer Time Restriction for detailed information about time restriction and its fields

participants field example

{
    "participants": [
        {
            "type": "team",
            "id": "b3578948-55b3-4acc-9bf1-2ce2db3alpa2"
        },
        {
            "type": "user",
            "username": "[email protected]"
        },
        {
            "type": "none"
        }
    ]
}

Sample Request

curl -X PATCH 'https://api.opsgenie.com/v2/schedules/ScheduleName/rotations/13a3alp1-5f0c-4370-a033-87a7f3be5d0e?scheduleIdentifierType=name'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "name": "First Rotation",
    "startDate": "2017-02-06T05:00:00Z",
    "endDate": "2017-02-23T06:00:00Z",
    "type": "hourly",
    "length": 6,
    "participants": [
        {
            "type": "none",
        },
        {
            "type": "user",
            "username": "[email protected]"
        },
        {
            "type": "user",
            "username": "[email protected]"
        }
    ],
    "timeRestriction": {
        "type" : "time-of-day",
        "restriction" :
        {
            "startHour" : 8,
            "startMin" : 0,
            "endHour" : 18,
            "endMin" : 30
        }
    }
}'

Response:

{
    "result": "Updated",
    "data": {
        "id": "13a3alp1-5f0c-4370-a033-87a7f3be5d0e",
        "name": "First Rotation"
    },
    "took": 0.721,
    "requestId": "0ac8b003-af24-4e7c-9d52-41b177d9alpb"
}

Delete Schedule Rotation

Delete schedule rotation request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management

HTTP Method

URL

DELETE

https://api.opsgenie.com/v2/schedules/:scheduleIdentifier/rotations/:id

In-Line Parameters

Referred Name

Description

scheduleIdentifier

Identifier of the schedule

id

Id of the schedule rotation

Query Parameters

Parameter

Mandatory

Description

scheduleIdentifierType

false

Type of the schedule identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

Sample Request

curl -X DELETE 'https://api.opsgenie.com/v2/schedules/ScheduleName/rotations/13a3alp1-5f0c-4370-a033-87a7f3be5d0e?scheduleIdentifierType=name'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'

Response:

{
    "result": "Deleted",
    "took": 0.229,
    "requestId": "0367a2e8-3b9f-4f00-acf0-alp1df5489f0"
}

List Schedule Rotations

HTTP Method

URL

GET

https://api.opsgenie.com/v2/schedules/:scheduleIdentifier/rotations

In-Line Parameters

Referred Name

Description

scheduleIdentifier

Identifier of the schedule

Query Parameters

Parameter

Mandatory

Description

scheduleIdentifierType

false

Type of the schedule identifier that is provided as an in-line parameter. Possible values are id and name. Default value is id

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/schedules/ScheduleName/rotations?scheduleIdentifierType=name'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'

Response:

{
    "data": [
        {
            "id": "a47ed593-0541-4alp-bac6-4084cfa02d20",
            "name": "First Rotation",
            "startDate": "2017-02-06T05:00:00Z",
            "endDate": "2017-02-23T06:00:00Z",
            "type": "hourly",
            "length": 6,
            "participants": [
                {
                  "type": "none"
                }
            ],
            "timeRestriction": {
                "type": "weekday-and-time-of-day",
                "restrictions": [
                    {
                        "startDay": "monday",
                        "endDay": "tuesday",
                        "startHour": 8,
                        "endHour": 18,
                        "startMin": 0,
                        "endMin": 30
                    },
                    {
                        "startDay": "wednesday",
                        "endDay": "thursday",
                        "startHour": 8,
                        "endHour": 18,
                        "startMin": 0,
                        "endMin": 30
                    }
                ]
            }
        },
        {
            "id": "af962100-c958-48cd-98ca-fc09c5d4e5c9",
            "name": "Second Rotation",
            "startDate": "2017-02-06T05:00:00Z",
            "endDate": "2017-02-23T06:00:00Z",
            "type": "hourly",
            "length": 6,
            "participants": [
                {
                    "type": "user",
                    "id": "a9alp4028-2bca-4510-a51f-4b65f2c33a56",
                },
                {
                    "type": "user",
                    "username": "[email protected]"
                }
            ],
            "timeRestriction": {
                "type": "weekday-and-time-of-day",
                "restrictions": [
                    {
                        "startDay": "monday",
                        "endDay": "tuesday",
                        "startHour": 8,
                        "endHour": 18,
                        "startMin": 0,
                        "endMin": 30
                    },
                    {
                        "startDay": "wednesday",
                        "endDay": "thursday",
                        "startHour": 8,
                        "endHour": 18,
                        "startMin": 0,
                        "endMin": 30
                    }
                ]
            }
        }
    ],
    "took": 0.042,
    "requestId": "6f0fd5b0-9alp-48bd-a42e-4bf5c3c896c0"
}

Time Restriction Fields

Used to limit schedule rotation to certain day and time of the week, using multiple start and end times for each day of the week. This allows applying different scheduling rotations at different times.

Day Based Restriction

If the time restrictions will be configured as day based, this parameter should be used.
timeRestriction parameter for daily restrictions should have the following format:

Parameter

Mandatory

Description

type

true

This parameter should be set time-of-day

restriction

true

It is a restriction object which is described below. In this case startDay/endDay fields are not supported

Parameter of Restriction Object

Parameter

Mandatory

Description

startHour

true

Value of the hour that frame will start

startMin

true

Value of the minute that frame will start. Minutes may take 0 or 30 as value. Otherwise they will be converted to nearest 0 or 30 automatically

endHour

true

Value of the hour that frame will end

endMin

true

Value of the minute that frame will end. Minutes may take 0 or 30 as value. Otherwise they will be converted to nearest 0 or 30 automatically

restriction field example:

{
    "timeRestriction": {
        "type" : "time-of-day",
        "restriction" :
        {
            "startHour" : 8,
            "startMin" : 0,
            "endHour" : 18,
            "endMin" : 30
        }
    }
}

Week Based Restrictions

If the time restrictions will be configured as week based, this parameter should be used. timeRestriction parameter for weekly restrictions should have the following format:

Parameter

Mandatory

Description

type

true

This parameter should be set weekday-and-time-of-day

restrictions

true

It is a list of restriction objects which are described below.

Parameter of Restrictions Object

Parameter

Mandatory

Description

startDay

true

Name of day which time frame will start. May be one of monday, tuesday, wednesday, thursday, friday, saturday, sunday. Only used if type of restrictions is given weekday-and-time-of-day

startHour

true

Value of the hour that frame will start

startMin

true

Value of the minute that frame will start. Minutes may take 0 or 30 as value. Otherwise they will be converted to nearest 0 or 30 automatically

endDay

true

Name of day which time frame will end. May be one of monday, tuesday, wednesday, thursday, friday, saturday, sunday. Only used if type of restrictions is given weekday-and-time-of-day

endHour

true

Value of the hour that frame will end

endMin

true

Value of the minute that frame will end. Minutes may take 0 or 30 as value. Otherwise they will be converted to nearest 0 or 30 automatically

restrictions field example:

{
    "timeRestriction": {
        "type" : "weekday-and-time-of-day",
        "restrictions" : [
            {
                "startDay" : "monday",
                "startHour" : 8,
                "startMin" : 0,
                "endDay" : "tuesday",
                "endHour" : 18,
                "endMin" : 30
            },
            {
                "startDay" : "wednesday",
                "startHour" : 8,
                "startMin" : 0,
                "endDay" : "thursday",
                "endHour" : 18,
                "endMin" : 30
            }
        ]
    }
}

Updated 8 days ago