> 🚧 If using the EU instance of Opsgenie, the URL needs to be [https://api.eu.opsgenie.com](https://api.eu.opsgenie.com) for requests to be successful. ## General Information * [API Rate Limiting](doc:api-rate-limiting) * [API Access Management](doc:api-access-management) * [Authentication](doc:authentication) * [Response](doc:response) * [Pagination](doc:pagination) ## Domains * [Rotation API](doc:schedule-rotation-api) * [Overrides API](doc:schedule-override-api) * [Who is On Call API](doc:who-is-on-call-api) > 📘 *Create an[API Integration](doc:api-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](doc:api-access-management)

HTTP Method	URL
POST	[https://api.opsgenie.com/v2/schedules](https://api.opsgenie.com/v2/schedules)

**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](doc:supported-timezone-ids) for available timezones. More information about timezones can be found in [Time Constraints](doc: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](doc:schedule-api#section-schedule-rotation-fields) 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: ```json { "ownerTeam": { "name":"network_team" } } ``` ```json { "ownerTeam": { "id":"8418d193-2alp-4490-b331-8c02cdd196b7" } } ``` Sample Requests ```curl 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": "user@opsgenie.com" }, { "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 ```json { "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:

HTTP Method	URL
GET	[https://api.opsgenie.com/v2/schedules/:identifier](https://api.opsgenie.com/v2/schedules/:identifier)

**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 curl -X GET 'https://api.opsgenie.com/v2/schedules/ScheduleName?identifierType=name' --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889' ``` Response ```json { "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": "user@opsgenie.com" }, { "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](doc:api-access-management)

HTTP Method	URL
PATCH	[https://api.opsgenie.com/v2/schedules/:identifier](https://api.opsgenie.com/v2/schedules/:identifier)

**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](https://support.atlassian.com/opsgenie/docs/supported-locale-ids/) for available timezones. More information about timezones can be found in [Time Constraints and Timezones ](https://support.atlassian.com/opsgenie/docs/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](doc:schedule-api#section-create-schedule) for example values
rotations	false	List of schedule rotations. You can refer to [Schedules Rotaton](doc:schedule-api#section-schedule-rotation-fields) for detailed information about rotations and their fields	At least one rotation

Sample Request ```curl 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 ```json { "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](doc:api-access-management)

HTTP Method	URL
DELETE	[https://api.opsgenie.com/v2/schedules/:identifier](https://api.opsgenie.com/v2/schedules/:identifier)

**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 curl -X DELETE 'https://api.opsgenie.com/v2/schedules/ScheduleName?identifierType=name' --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889' ``` Response: ```json { "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:

HTTP Method	URL
GET	[https://api.opsgenie.com/v2/schedules](https://api.opsgenie.com/v2/schedules)

**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 curl -X GET 'https://api.opsgenie.com/v2/schedules' --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889' ``` Response: ```json { "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": "user@opsgenie.com" }, { "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

HTTP Method	URL
GET	[https://api.opsgenie.com/v2/schedules/:identifier/timeline](https://api.opsgenie.com/v2/schedules/:identifier/timeline)

**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 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: ```json { "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": "user2@opsgenie.com" } }, { "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": "user3@opsgenie.com" } } ] } ] }, "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": "user3@opsgenie.com" } } { "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": "user2@opsgenie.com" } }, { "startDate": "2017-05-17T05:30:00Z", "endDate": "2017-05-18T05:30:00Z", "type": "default", "recipient": { "id": "a951alp8-2bca-4510-a51f-4b65f2c33a56", "type": "user", "name": "user@opsgenie.com" } }, { "startDate": "2017-05-18T05:30:00Z", "endDate": "2017-05-19T05:30:00Z", "type": "default", "recipient": { "id": "4fb3alpe-348d-4b7c-b71b-149efb8361e4", "type": "user", "name": "user4@opsgenie.com" } }, { "startDate": "2017-05-19T05:30:00Z", "endDate": "2017-05-19T15:30:00Z", "type": "default", "recipient": { "id": "1f2alp91-bca3-4ae2-bdea-b02e94d10953", "type": "user", "name": "user3@opsgenie.com" } } ] } ] }, "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": "user2@opsgenie.com" } } ] } ] }, "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": "user5@opsgenie.com" } } ] } ] } }, "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:

HTTP Method	URL
GET	[https://api.opsgenie.com/v2/schedules/:identifier.ics](https://api.opsgenie.com/v2/schedules/:identifier.ics)

**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 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](doc:schedule-api#section-schedule-rotation-fields) for example values
timeRestriction	false	You can refer [Time Restriction](doc:schedule-api#section-time-restriction-fields) 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: ```json { "participants": [ { "type": "team", "id": "b3578948-55b3-4acc-9bf1-2ce2db3alpa2" }, { "type": "user", "username": "user@opsgenie.com" }, { "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](doc:schedule-api#section-time-restriction-fields) . 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: ```json { "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](doc:schedule-api#section-fields-of-restrictions-object)

**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: ```json { "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 } ] } } ```