Schedule 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

Domains

📘

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

Create Schedule

Create schedule request is used to add new schedules in Opsgenie and it 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

JSON Body Fields

Fields

Mandatory

Description

name

true

Name of the schedule

100 chars

description

false

The description of schedule

200 chars

timezone

false

Timezone of schedule. You can refer to Supported Timezone IDs for available timezones. More information about timezones can be found in Time Constraints document

enabled

false

Enable/disable state of schedule

ownerTeam

false

Owner team of the schedule, consisting id and/or name of the owner team

rotations

false

List of schedule rotations. You can refer to Schedules for detailed information about rotations and their fields

At least one rotation

🚧

If integration belongs to any team, it automatically overwrite ownerTeam object. Otherwise id or name fields should be specified in ownerTeam

ownerTeam field example:

{
    "ownerTeam": {
        "name":"network_team"
    }
}
{
    "ownerTeam": {
        "id":"8418d193-2alp-4490-b331-8c02cdd196b7"
    }
}

Sample Requests

curl -X POST 'https://api.opsgenie.com/v2/schedules'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "name": "ScheduleName",
    "description": "ScheduleDescription",
    "timezone": "Europe/Kirov",
    "enabled": true,
    "ownerTeam": {
    	"name": "ops_team"
    },
    "rotations": [
    	{
            "name": "First Rotation",
            "startDate": "2017-02-06T05:00:00Z",
            "endDate": "2017-02-23T06:00:00Z",
            "type": "hourly",
            "length": 6,
            "participants": [
                {
                    "type": "user",
                    "username": "[email protected]"
                },
                {
                    "type": "none"
                },
                {
                    "type": "user",
                    "id": "ac463592-dbd2-4ca3-alp1d-48fhf5j5c871"
                }
            ],
            "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

{
    "data": {
        "id": "4a9alp7-b5d2-4ecb-b82c-e3b5286829cf",
        "name": "ScheduleName",
        "enabled": true
    },
    "took": 0.853,
    "requestId": "f9d1f3f3-4da5-4cba-b1e1-ece0alp0ebdf"
}

Get Schedule

Get schedule request is used to search and retrieve schedules in Opsgenie. It takes the following parameters:

In-Line Parameters

Referred Name

Description

identifier

Identifier of the schedule

Query Parameters

Parameter

Mandatory

Description

identifierType

false

Type of the 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?identifierType=name'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response

{
    "data": {
        "id": "4a9e4b7c-b5d2-4ecb-b82c-e3b52alp829cf",
        "name": "ScheduleName",
        "description": "ScheduleDescription",
        "timezone": "Europe/Kirov",
        "enabled": true,
        "ownerTeam": {
            "id": "6c7be998-fad9-4491-a9a7-d99alp4c0ae5",
            "name": "ops_team"
        },
        "rotations": [
            {
                "id": "e1c575c4-7143-482c-8e83-4balp7d582d7",
                "name": "First Rotation",
                "startDate": "2017-02-06T05:00:00Z",
                "endDate": "2017-02-23T06:00:00Z",
                "type": "hourly",
                "length": 6,
                "participants": [
                    {
                        "type": "user",
                        "id": "96414alp-3ea5-41b1-a019-601598627d68",
                        "username": "[email protected]"
                    },
                    {
                        "type": "none",
                    }
                ],
                "timeRestriction": {
                    "type": "time-of-day",
                    "restrictions": [
                        {
                            "startHour": 8,
                            "endHour": 18,
                            "startMin": 0,
                            "endMin": 30
                        }
                    ]
                }
            }
        ]
    },
    "took": 0.051,
    "requestId": "13a3alp1-5f0c-4370-a033-87a7f3be5d0e"
}

Update Schedule (Partial)

Update schedule request is used to update schedules in partial manner and it 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

In-Line Parameters

Referred Name

Description

identifier

Identifier of the schedule

Query Parameters

Parameter

Mandatory

Description

identifierType

false

Type of the 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

Limit

name

false

The name of schedule

100 chars

description

false

The description of schedule

200 chars

timezone

false

Timezone of schedule. You can refer to Supported Locale IDs for available timezones. More information about timezones can be found in Time Constraints and Timezones document.

enabled

false

Enable/disable state of schedule

ownerTeam

false

Owner team of the schedule, consisting id and/or name of the owner team. You can refer here for example values

rotations

false

List of schedule rotations. You can refer to Schedules Rotaton for detailed information about rotations and their fields

At least one rotation

Sample Request

curl -X PATCH 'https://api.opsgenie.com/v2/schedules/ScheduleName?identifierType=name'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "name": "DisabledScheduleName",
    "enabled": false,
    "rotations": [
    	"startDate":"2019-01-15T08:00:00+02:00",
        "type":"daily",
        {
            "participants": [
                {
                
                    "type": "none"
                }
            ]
        }
    ]
}'

Response

{
    "data": {
        "id": "d875e654-9b4e-4219-alp3-0c26936d18de",
        "name": "DisabledScheduleName",
        "enabled": true
    },
    "took": 0.838,
    "requestId": "c96falp8-14fc-4414-a8ee-95eb7480f77d"
}

Delete Schedule

Delete schedule request is used to delete schedules in Opsgenie and it 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

In-Line Parameters

Referred Name

Description

identifier

Identifier of the schedule

Query Parameters

Parameter

Mandatory

Description

identifierType

false

Type of the 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?identifierType=name'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'

Response:

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

List Schedules

List schedules request is used to list schedules in Opsgenie. It takes the following parameters:

Query Parameters

Parameter

Mandatory

Description

expand

false

Returns more detailed response with expanding it. Possible value is rotation which is also returned with expandable field of response

Sample Request

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

Response:

{
    "data": [
        {
            "id": "d875e654-9b4e-4219-alp3-0c26936d18de",
            "name": "ScheduleName",
            "description": "ScheduleDescription",
            "timezone": "Europe/Kirov",
            "enabled": true,
            "ownerTeam": {
                "id": "90098alp-f0e3-41d3-a060-0ea895027630",
                "name": "ops_team"
            },
            "rotations": [
                {
                    "id": "a47alp93-0541-4aa3-bac6-4084cfa02d20",
                    "name": "First Rotation",
                    "startDate": "2017-05-14T21:00:00Z",
                    "type": "weekly",
                    "length": 1,
                    "participants": [
                        {
                            "type": "user",
                            "id": "a9514028-2bca-4510-alpf-4b65f2c33a56",
                            "username": "[email protected]"
                        },
                        {
                            "type": "team",
                            "id": "00564944-b42f-4b95-a882-ee9a5alpb9bb",
                            "name": "ops_team"
                        }
                    ]
                }
            ]
        }
    ],
    "expandable": [
        "rotation"
    ],
    "took": 0.096,
    "requestId": "663alpfc-e647-4759-8121-7d33e34c01c1"
}

Get Schedule Timeline

Get Schedule Timeline request is used to get the timeline of the given schedule that includes time and on-call recipient details. It takes the following parameters

In-Line Parameters

Referred Name

Description

identifier

Identifier of the schedule

Query Parameters

Parameter

Mandatory

Description

identifierType

false

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

expand

false

Returns more detailed response with expanding it. Possible values are base, forwarding, override which is also returned with expandable field of response

interval

false

Length of time as integer in intervalUnits to retrieve the timeline. Default value is 1

intervalUnit

false

Unit of the time to retrieve the timeline. Available values are days, weeks and months. Default value is weeks

date

false

Time to return future date on-call participants that will be provided in format as(yyyy-MM-dd'T'HH:mm:ssZ) (e.g. 2017-01-15T08:00:00+02:00). Default date is the moment of the time that request is received

🚧

You should escape the plus sign in your url with'%2B', if you are using console for curl requests

Sample Requests

curl -X GET 'https://api.opsgenie.com/v2/schedules/alp63592-dbd2-4ca3-a651d-48fhf5j5c871/timeline?expand=base,forwarding,override'
    --header 'Authorization: GenieKey eb243592-falp-4ba2-a551q-1alpf565c889'

Response:

{
    "data": {
        "_parent": {
            "id": "d875e654-9b4e-4219-a803-0c2693alp8de",
            "name": "ScheduleName",
            "enabled": true
        },
        "startDate": "2017-05-14T21:00:00Z",
        "endDate": "2017-05-21T21:00:00Z",
        "finalTimeline": {
            "rotations": [
                {
                    "id": "a47ed593-0541-4alp-bac6-4084cfa02d20",
                    "name": "First Rotation",
                    "order": 1,
                    "periods": [
                        {
                            "startDate": "2017-05-17T14:56:34.603Z",
                            "endDate": "2017-05-18T14:33:00Z",
                            "type": "override",
                            "recipient": {
                                "id": "00564944-b42f-4b95-a882-ee9a5alpb9bb",
                                "type": "user",
                                "name": "[email protected]"
                            }
                        },
                        {
                            "startDate": "2017-05-18T14:33:00Z",
                            "endDate": "2017-05-19T05:30:00Z",
                            "type": "default",
                            "recipient": {
                                "id": "c569c016-alp9-4e20-8a28-bd5dc33b798e",
                                "type": "team",
                                "name": "TeamName"
                            }
                        },
                        {
                            "startDate": "2017-05-19T05:30:00Z",
                            "endDate": "2017-05-19T15:30:00Z",
                            "type": "default",
                            "recipient": {
                                "id": "1f2alp91-bca3-4ae2-bdea-b02e94d10953",
                                "type": "user",
                                "name": "[email protected]"
                            }
                        }
                    ]
                }
            ]
        },
        "baseTimeline": {
            "rotations": [
                {
                    "id": "a47ed593-0541-4alp-bac6-4084cfa02d20",
                    "name": "First Rotation",
                    "order": 1,
                    "periods": [
                        {
                            "startDate": "2017-05-19T05:30:00Z",
                            "endDate": "2017-05-19T15:30:00Z",
                            "type": "default",
                            "recipient": {
                                "id": "1f2alp91-bca3-4ae2-bdea-b02e94d10953",
                                "type": "user",
                                "name": "[email protected]"
                            }
                        }
                        {
                            "startDate": "2017-05-17T14:56:34.603Z",
                            "endDate": "2017-05-18T14:33:00Z",
                            "type": "override",
                            "recipient": {
                                "id": "00564944-b42f-4b95-a882-ee9a5alpb9bb",
                                "type": "user",
                                "name": "[email protected]"
                            }
                        },
                        {
                            "startDate": "2017-05-17T05:30:00Z",
                            "endDate": "2017-05-18T05:30:00Z",
                            "type": "default",
                            "recipient": {
                                "id": "a951alp8-2bca-4510-a51f-4b65f2c33a56",
                                "type": "user",
                                "name": "[email protected]"
                            }
                        },
                        {
                            "startDate": "2017-05-18T05:30:00Z",
                            "endDate": "2017-05-19T05:30:00Z",
                            "type": "default",
                            "recipient": {
                                "id": "4fb3alpe-348d-4b7c-b71b-149efb8361e4",
                                "type": "user",
                                "name": "[email protected]"
                            }
                        },
                        {
                            "startDate": "2017-05-19T05:30:00Z",
                            "endDate": "2017-05-19T15:30:00Z",
                            "type": "default",
                            "recipient": {
                                "id": "1f2alp91-bca3-4ae2-bdea-b02e94d10953",
                                "type": "user",
                                "name": "[email protected]"
                            }
                        }
                    ]
                }
            ]
        },
        "overrideTimeline": {
            "rotations": [
                {
                    "id": "a47ed593-0541-4alp-bac6-4084cfa02d20",
                    "name": "First Rotation",
                    "order": 1,
                    "periods": [
                        {
                            "startDate": "2017-05-17T14:33:00Z",
                            "endDate": "2017-05-18T14:33:00Z",
                            "type": "override",
                            "recipient": {
                                "id": "00564944-b42f-4b95-a882-ee9a5alpb9bb",
                                "type": "user",
                                "name": "[email protected]"
                            }
                        }
                    ]
                }
            ]
        },
        "forwardingTimeline": {
            "rotations": [
                {
                    "id": "a47ed593-0541-4alp-bac6-4084cfa02d20",
                    "name": "",
                    "order": 0,
                    "periods": [
                        {
                            "startDate": "2017-05-17T05:30:00Z",
                            "endDate": "2017-05-18T05:30:00Z",
                            "type": "forwarding",
                            "fromUser": "a9514028-2bca-4510-a51f-4b65f2c33alp",
                            "recipient": {
                                "id": "bf687783-alp1-40e3-940c-ffde45656054",
                                "type": "user",
                                "name": "[email protected]"
                            }
                        }
                    ]
                }
            ]
        }
    },
    "expandable": [
        "base",
        "forwarding",
        "override"
    ],
    "took": 1.862,
    "requestId": "87alp184-50b4-49e0-974c-716e85cd18f0"
}

🚧

flattenedRecipients field is returned when the period is historical, (i.e. period must finished)

Export Schedule

Export schedule request is used to export a schedule to a .ics file. It takes the following parameters:

In-Line Parameters

Referred Name

Description

identifier

Identifier of the schedule

Query Parameters

Parameter

Mandatory

Description

identifierType

false

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

Sample Requests

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

Response:

Returns an .ics file with the name of the schedule or user

Schedule Rotation Fields

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 here 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"
        }
    ]
}

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:

Field

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

Fields of Restriction Object

Field

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:

Field

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

Fields of Restrictions Object

Field

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
            }
        ]
    }
}