REST API

/api/v0/teams

GET /api/v0/teams

Search for team names. Allows filtering based on a number of parameters, detailed below. Returns list of matching team names. If “active” parameter is unspecified, defaults to True (only displaying undeleted teams)

Query Parameters:  

• name – team name
• name__eq – team name
• name__contains – team name contains param
• name__startswith – team name starts with param
• name__endswith – team name ends with param
• id – team id
• id__eq – team id
• active – team active/deleted (1 and 0, respectively)

Example request:

GET /api/v0/teams?name__startswith=team-  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    "team-foo",
    "team-bar"
]

POST /api/v0/teams

Endpoint for team creation. The user who creates the team is automatically added as a team admin. Because of this, this endpoint cannot be called using an API key, otherwise a team would have no admins, making many team operations impossible.

Teams can specify a number of attributes, detailed below:

• name: the team’s name. Teams must have unique names.
• email: email address for the team.
• slack_channel: slack channel for the team. Must start with ‘#’
• iris_plan: Iris escalation plan that incidents created from the Oncall UI will follow.

If iris plan integration is not activated, this attribute can still be set, but its value is not used.

Teams must specify name and scheduling_timezone; other parameters are optional.

Example request:

POST api/v0/teams   HTTP/1.1
Content-Type: application/json

{
    "name": "team-foo",
    "scheduling_timezone": "US/Pacific",
    "email": "team-foo@example.com",
    "slack_channel": "#team-foo",
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

Status Codes:

• 201 Created – Successful create
• 400 Bad Request – Error in creating team. Possible errors: API key auth not allowed, invalid attributes, missing required attributes
• 422 Unprocessable Entity – Duplicate team name

GET /api/v0/teams/{team}

Get team info by name. By default, only finds active teams. Allows selection of fields, including: users, admins, services, and rosters. If no fields is specified in the query string, it defaults to all fields.

Example request

GET /api/v0/teams/team-foo  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "admins": [
        {
            "name": "jdoe"
        }
    ],
    "email": "foo@example.com",
    "id": 5501,
    "iris_plan": null,
    "name": "team-foo",
    "rosters": {
        "roster-foo": {
            "id": 4186,
            "schedules": [
                {
                    "advanced_mode": 0,
                    "auto_populate_threshold": 21,
                    "events": [
                        {
                            "duration": 604800,
                            "start": 7200
                        }
                    ],
                    "id": 2222,
                    "role": "primary",
                    "role_id": 1,
                    "roster": "roster-foo",
                    "roster_id": 4186,
                    "team": "team-foo",
                    "team_id": 5501,
                    "timezone": "US/Pacific"
                }
            ],
            "users": [
                {
                    "in_rotation": true,
                    "name": "jdoe"
                }
            ]
        }
    },
    "scheduling_timezone": "US/Pacific",
    "services": [
        "service-foo"
    ],
    "slack_channel": "#foo",
    "users": {
        "jdoe": {
            "active": 1,
            "contacts": {
                "call": "+1 111-111-1111",
                "email": "jdoe@example.com",
                "im": "jdoe",
                "sms": "+1 111-111-1111"
            },
            "full_name": "John Doe",
            "id": 1234,
            "name": "jdoe",
            "photo_url": "image.example.com",
            "time_zone": "US/Pacific"
        }
    }
}

PUT /api/v0/teams/{team}

Edit a team’s information. Allows edit of: name, slack_channel, email, scheduling_timezone, iris_plan.

Example request:

PUT /api/v0/teams/team-foo HTTP/1.1
Content-Type: application/json

{
    "name": "team-bar",
    "slack_channel": "roster-bar",
    "email": 28,
    "scheduling_timezone": "US/Central"
}

Status Codes:

• 200 OK – Successful edit
• 400 Bad Request – Invalid team name/iris escalation plan
• 422 Unprocessable Entity – Duplicate team name

DELETE /api/v0/teams/{team}

Soft delete for teams. Does not remove data from the database, but sets the team’s active param to false. Note that this means deleted teams’ names remain in the namespace, so new teams cannot be created with the same name a sa deleted team.

Example request:

DELETE /api/v0/teams/team-foo HTTP/1.1

Status Codes:

• 200 OK – Successful delete
• 404 Not Found – Team not found

GET /api/v0/teams/{team}/summary

Endpoint to get a summary of the team’s oncall information. Returns an object containing the fields current and next, which then contain information on the current and next on-call shifts for this team. current and next are objects keyed by role (if an event of that role exists), with values of lists of event/user information. This list will have multiple elements if multiple events with the same role are currently occurring, or if multiple events with the same role are starting next in the future at the same time.

If no event with a given role exists, that role is excluded from the current or next object. If no events exist, the current and next objects will be empty objects.

Example request:

GET api/v0/teams/team-foo/summary   HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "current": {
        "manager": [
            {
                "end": 1495760400,
                "full_name": "John Doe",
                "photo_url": "example.image.com",
                "role": "manager",
                "start": 1495436400,
                "user": "jdoe",
                "user_contacts": {
                    "call": "+1 111-111-1111",
                    "email": "jdoe@example.com",
                    "im": "jdoe",
                    "sms": "+1 111-111-1111"
                },
                "user_id": 1234
            }
        ],
        "primary": [
            {
                "end": 1495760400,
                "full_name": "Adam Smith",
                "photo_url": "example.image.com",
                "role": "primary",
                "start": 1495350000,
                "user": "asmith",
                "user_contacts": {
                    "call": "+1 222-222-2222",
                    "email": "asmith@example.com",
                    "im": "asmith",
                    "sms": "+1 222-222-2222"
                },
                "user_id": 1235
            }
        ]
    },
    "next": {
        "manager": [
            {
                "end": 1496127600,
                "full_name": "John Doe",
                "photo_url": "example.image.com",
                "role": "manager",
                "start": 1495436400,
                "user": "jdoe",
                "user_contacts": {
                    "call": "+1 111-111-1111",
                    "email": "jdoe@example.com",
                    "im": "jdoe",
                    "sms": "+1 111-111-1111"
                },
                "user_id": 1234
            }
        ],
        "primary": [
            {
                "end": 1495760400,
                "full_name": "Adam Smith",
                "photo_url": "example.image.com",
                "role": "primary",
                "start": 1495350000,
                "user": "asmith",
                "user_contacts": {
                    "call": "+1 222-222-2222",
                    "email": "asmith@example.com",
                    "im": "asmith",
                    "sms": "+1 222-222-2222"
                },
                "user_id": 1235
            }
        ]
    }
}

GET /api/v0/teams/{team}/oncall

Get current active event for team based on given role.

Example request:

GET /api/v0/teams/team_ops/oncall/primary HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "user": "foo",
    "start": 1487426400,
    "end": 1487469600,
    "full_name": "Foo Icecream",
    "contacts": {
      "im": "foo",
      "sms": "+1 123-456-7890",
      "email": "foo@example.com",
      "call": "+1 123-456-7890"
    }
  },
  {
    "user": "bar",
    "start": 1487426400,
    "end": 1487469600,
    "full_name": "Bar Dog",
    "contacts": {
      "im": "bar",
      "sms": "+1 123-456-7890",
      "email": "bar@example.com",
      "call": "+1 123-456-7890"
    }
  }
]

Status Codes:

• 200 OK – no error

GET /api/v0/teams/{team}/oncall/{role}

Get current active event for team based on given role.

Example request:

GET /api/v0/teams/team_ops/oncall/primary HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "user": "foo",
    "start": 1487426400,
    "end": 1487469600,
    "full_name": "Foo Icecream",
    "contacts": {
      "im": "foo",
      "sms": "+1 123-456-7890",
      "email": "foo@example.com",
      "call": "+1 123-456-7890"
    }
  },
  {
    "user": "bar",
    "start": 1487426400,
    "end": 1487469600,
    "full_name": "Bar Dog",
    "contacts": {
      "im": "bar",
      "sms": "+1 123-456-7890",
      "email": "bar@example.com",
      "call": "+1 123-456-7890"
    }
  }
]

Status Codes:

• 200 OK – no error

GET /api/v0/teams/{team}/admins

Get list of admin usernames for a team

Example request

GET /api/v0/teams/team-foo/admins  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    "jdoe",
    "asmith"
]

POST /api/v0/teams/{team}/admins

Add user as a team admin. Responds with that user’s info (similar to user GET). Subscribes this user to default notifications for the team, and adds the user to the team (if needed).

Example request

POST /api/v0/teams/team-foo/admins  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "active": 1,
    "contacts": {
        "call": "+1 111-111-1111",
        "email": "jdoe@example.com",
        "im": "jdoe",
        "sms": "+1 111-111-1111"
    },
    "full_name": "John Doe",
    "id": 9535,
    "name": "jdoe",
    "photo_url": "image.example.com",
    "time_zone": "US/Pacific"
}

Status Codes:

• 201 Created – Successful admin added
• 400 Bad Request – Missing name attribute in request
• 422 Unprocessable Entity – Invalid team/user, or user is already a team admin

DELETE /api/v0/teams/{team}/admins/{user}

Delete team admin user. Removes admin from the team if he/she is not a member of any roster.

Example request:

DELETE /api/v0/teams/team-foo/admins/jdoe HTTP/1.1

Status Codes:

• 200 OK – Successful delete
• 404 Not Found – Team admin not found

GET /api/v0/teams/{team}/users

Get list of usernames for all team members. A user is a member of a team when he/she is a team admin or a member of one of the team’s rosters. Accepts an active parameter in the query string that filters inactive (deleted) teams.

Example request:

GET /api/v0/teams/team-foo/users   HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    "jdoe",
    "asmith"
]

POST /api/v0/teams/{team}/users

Add user to a team. Deprecated; used only for testing purposes.

DELETE /api/v0/teams/{team}/users/{user}

Delete user from a team

Example request:

DELETE /api/v0/teams/team-foo/users/jdoe HTTP/1.1

Status Codes:

• 200 OK – Successful delete
• 404 Not Found – User not found in team

GET /api/v0/teams/{team}/rosters

Get roster info for a team. Returns a JSON object with roster names as keys, and info as values. This info includes the roster id, any schedules associated with the rosters, and roster users (along with their status as in/out of rotation).

Example request:

GET /api/v0/teams/team-foo/rosters  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

    {
        "roster-foo": {
            "id": 2923,
            "schedules": [
                {
                    "advanced_mode": 0,
                    "auto_populate_threshold": 30,
                    "events": [
                        {
                            "duration": 604800,
                            "start": 266400
                        }
                    ],
                    "id": 1788,
                    "role": "primary",
                    "role_id": 1,
                    "roster": "roster-foo",
                    "roster_id": 2923,
                    "team": "team-foo",
                    "team_id": 2122,
                    "timezone": "US/Pacific"
                }
            ],
            "users": [
                {
                    "in_rotation": true,
                    "name": "jdoe"
                },
                {
                    "in_rotation": true,
                    "name": "asmith"
                }
            ]
        }
    }

Status Codes:

• 422 Unprocessable Entity – Invalid team

POST /api/v0/teams/{team}/rosters

Create a roster for a team

Example request:

POST /v0/teams/team-foo/rosters  HTTP/1.1
Content-Type: application/json

{
    "name": "roster-foo",
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

Status Codes:

• 201 Created – Succesful roster creation
• 422 Unprocessable Entity – Invalid character in roster name/Duplicate roster name

GET /api/v0/teams/{team}/rosters/{roster}

Get user and schedule info for a roster

Example request:

GET /api/v0/teams/foo-sre/rosters HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Managers": {
    "id": 2730,
    "users": [
      {
        "in_rotation": true,
        "name": "foo"
      }
    ],
    "schedules": [
      {
        "auto_populate_threshold": 0,
        "roster": "Managers",
        "advanced_mode": 0,
        "role": "manager",
        "team": "foo-sre",
        "events": [
          {
            "duration": 604800,
            "start": 367200
          }
        ],
        "id": 1704
      }
    ]
  }
}

Status Codes:

• 200 OK – no error

PUT /api/v0/teams/{team}/rosters/{roster}

Change roster name. Must have team admin privileges.

Example request:

PUT /api/v0/teams/team-foo/rosters/roster-foo HTTP/1.1
Content-Type: application/json

{
    "name": "roster-bar",
}

Status Codes:

• 400 Bad Request – Invalid roster name, disallowed characters
• 422 Unprocessable Entity – Duplicate roster name for team

DELETE /api/v0/teams/{team}/rosters/{roster}

Delete roster

GET /api/v0/teams/{team}/rosters/{roster}/users

Get all users for a team’s roster

Example request:

GET /api/v0/teams/team-foo/rosters/roster-foo/users  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

["jdoe", "asmith"]

POST /api/v0/teams/{team}/rosters/{roster}/users

Add user to a roster for a team. On successful creation, returns that user’s information. This includes id, contacts, etc, similar to the /api/v0/users GET endpoint.

Example request:

POST /v0/teams/team-foo/rosters/roster-foo/users   HTTP/1.1
Content-Type: application/json

{
    "name": "jdoe"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "active": 1,
    "contacts": {
        "email": "jdoe@example.com",
        "im": "jdoe",
        "sms": "+1 111-111-1111",
        "call": "+1 111-111-1111"
    },
    "full_name": "John Doe",
    "id": 1,
    "name": "jdoe",
    "photo_url": "example.image.com",
    "time_zone": "US/Pacific"
}

Status Codes:

• 201 Created – Roster user added
• 400 Bad Request – Missing “name” parameter
• 422 Unprocessable Entity – Invalid team/user or user is already in roster.

PUT /api/v0/teams/{team}/rosters/{roster}/users/{user}

Put a user into/out of rotation within a given roster

Example request:

PUT /v0/api/teams/team_foo/rosters/best_coast/users/user1 HTTP/1.1
Content-Type: application/json

{"in_rotation": false}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[]

Status Codes:

• 200 OK – no error, user status udpated.
• 400 Bad Request – invalid request, missing field “in_rotation”.

DELETE /api/v0/teams/{team}/rosters/{roster}/users/{user}

Delete user from roster

Example request:

DELETE /v0/api/teams/team_foo/rosters/best_coast/users/user1 HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[]

Status Codes:

• 200 OK – no error, user deleted from roster.
• 404 Not Found – roster not found.

GET /api/v0/teams/{team}/rosters/{roster}/schedules

Get schedules for a given roster. Information on schedule attributes is detailed in the schedules POST endpoint documentation. Schedules can be filtered with the following parameters passed in the query string:

Query Parameters:  

• id – id of the schedule
• id__eq – id of the schedule
• id__gt – id greater than
• id__ge – id greater than or equal
• id__lt – id less than
• id__le – id less than or equal
• name – schedule name
• name__eq – schedule name
• name__contains – schedule name contains param
• name__startswith – schedule name starts with param
• name__endswith – schedule name ends with param
• role – schedule role name
• role__eq – schedule role name
• role__contains – schedule role name contains param
• role__startswith – schedule role name starts with param
• role__endswith – schedule role name ends with param
• team – schedule team name
• team__eq – schedule team name
• team__contains – schedule team name contains param
• team__startswith – schedule team name starts with param
• team__endswith – schedule team name ends with param
• team_id – id of the schedule’s team
• roster_id – id of the schedule’s roster

Example request:

GET /api/v0/teams/team-foo/rosters/roster-foo/schedules  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "advanced_mode": 1,
        "auto_populate_threshold": 30,
        "events": [
            {
                "duration": 259200,
                "start": 0
            }
        ],
        "id": 2065,
        "role": "primary",
        "role_id": 1,
        "roster": "roster-foo",
        "roster_id": 2922,
        "team": "team-foo",
        "team_id": 2121,
        "timezone": "US/Pacific"
    }
]

POST /api/v0/teams/{team}/rosters/{roster}/schedules

Schedule create endpoint. Schedules are templates for the auto-scheduler to follow that define how it should populate a certain period of time. This template is followed repeatedly to populate events on a team’s calendar. Schedules are associated with a roster, which defines the pool of users that the scheduler selects from. Similarly, the schedule’s role indicates the role that the populated events shoud have. The auto_populate_threshold parameter defines how far into the future the scheduler populates.

Finally, each schedule has a list of events, each defining start and duration. start represents an offset from Sunday at 00:00 in the team’s scheduling timezone, in seconds. For example, denote DAY and HOUR as the number of seconds in a day/hour, respectively. An event with start of (DAY + 9 * HOUR) starts on Monday, at 9:00 am. Duration is also given in seconds.

The scheduler will start at Sunday 00:00 in the team’s scheduling timezone, choose a user, and populate events on the calendar according to the offsets defined in the events list. It then repeats this process, moving to the next Sunday 00:00 after the events it has created.

advanced_mode acts as a hint to the frontend on how the schedule should be displayed, defining whether the advanced mode toggle on the schedule edit action should be set on or off. Because of how the frontend displays simple schedules, a schedule can only have advanced_mode = 0 if its events have one of 4 formats:

1. One event that is one week long
2. One event that is two weeks long
3. Seven events that are 12 hours long
4. Fourteen events that are 12 hours long

See below for sample JSON requests.

Assume these schedules’ team defines US/Pacific as its scheduling timezone.

Weekly 7*24 shift that starts at Monday 6PM PST:

{
    'role': 'primary'
    'auto_populate_threshold': 21,
    'events':[
        {'start': SECONDS_IN_A_DAY + 18 * SECONDS_IN_AN_HOUR,
         'duration': SECONDS_IN_A_WEEK}
    ],
    'advanced_mode': 0
}

Weekly 7*12 shift that starts at Monday 8AM PST:

{
    'role': 'oncall',
    'events':[
        {'start': SECONDS_IN_A_DAY + 8 * SECONDS_IN_AN_HOUR,
         'duration': 12 * SECONDS_IN_AN_HOUR},
        {'start': 2 * SECONDS_IN_A_DAY + 8 * SECONDS_IN_AN_HOUR,
         'duration': 12 * SECONDS_IN_AN_HOUR} ... *5 more*
    ],
    'advanced_mode': 1
}

Example Request

POST /v0/teams/team-foo/rosters/roster-foo/schedules   HTTP/1.1
Content-Type: application/json

{
    "advanced_mode": 0,
    "auto_populate_threshold": "21",
    "events": [
        {
            "duration": 604800,
            "start": 129600
        }
    ],
    "role": "primary",
}

Example response:

HTTP/1.1 201 OK
Content-Type: application/json

{
    "id": 2221
}

Status Codes:

• 201 Created – Successful schedule create. Response contains created schedule’s id.
• 400 Bad Request – Missing required parameters
• 422 Unprocessable Entity – Invalid roster specified

GET /api/v0/teams/{team}/services

Get list of services mapped to a team

Example request:

GET /api/v0/teams/team-foo/services  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    "service-foo",
    "service-bar"
]

POST /api/v0/teams/{team}/services

Create team to service mapping. Takes an object defining “name”, then maps that service to the team specified in the URL. Note that this endpoint does not create a service; it expects this service to already exist.

Example request:

POST api/v0/teams/team-foo/services   HTTP/1.1
Content-Type: application/json

{
    "name": "service-foo",
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

Status Codes:

• 201 Created – Successful create
• 422 Unprocessable Entity – Mapping creation failed; Possible errors: Invalid service/team name, service already mapped to the team, service mapped to another team

DELETE /api/v0/teams/{team}/services/{service}

Delete service team mapping. Only allowed for team admins.

Example request:

DELETE /api/v0/teams/team-foo/services/service-foo HTTP/1.1

Status Codes:

• 200 OK – Successful delete
• 404 Not Found – Team-service mapping not found

/api/v0/schedules

GET /api/v0/schedules/{schedule_id}

Get schedule information. Detailed information on schedule parameters is provided in the POST method for /api/v0/team/{team_name}/rosters/{roster_name}/schedules.

Example request:

GET /api/v0/schedules/1234  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

    {
        "advanced_mode": 1,
        "auto_populate_threshold": 30,
        "events": [
            {
                "duration": 259200,
                "start": 0
            }
        ],
        "id": 1234,
        "role": "primary",
        "role_id": 1,
        "roster": "roster-foo",
        "roster_id": 2922,
        "team": "asdf",
        "team_id": 2121,
        "timezone": "US/Pacific"
    }

PUT /api/v0/schedules/{schedule_id}

Update a schedule. Allows editing of role, team, roster, auto_populate_threshold, events, and advanced_mode. Only allowed for team admins. Note that simple mode schedules must conform to simple schedule restrictions (described in documentation for the /api/v0/team/{team_name}/rosters/{roster_name}/schedules GET endpoint). This is checked on both “events” and “advanced_mode” edits.

Example request:

PUT /api/v0/schedules/1234 HTTP/1.1
Content-Type: application/json

{
    "role": "primary",
    "team": "team-bar",
    "roster": "roster-bar",
    "auto_populate_threshold": 28,
    "events":
        [
            {
                "start": 0,
                "duration": 100
            }
        ]
    "advanced_mode": 1
}

DELETE /api/v0/schedules/{schedule_id}

Delete a schedule by id. Only allowed for team admins.

Example request:

DELETE /api/v0/schedules/1234 HTTP/1.1

Status Codes:

• 200 OK – Successful delete
• 404 Not Found – Schedule not found

POST /api/v0/schedules/{schedule_id}/populate

Run the scheduler on demand from a given point in time. Deletes existing schedule events if applicable. Given the start param, this will find the first schedule start time after start, then populate out to the schedule’s auto_populate_threshold. It will also clear the calendar of any events associated with the chosen schedule from the start of the first event it created onward. For example, if start is Monday, May 1 and the chosen schedule starts on Wednesday, this will create events starting from Wednesday, May 3, and delete any events that start after May 3 that are associated with the schedule.

Example request:

POST api/v0/   HTTP/1.1
Content-Type: application/json

Status Codes:

• 200 OK – Successful populate
• 400 Bad Request – Validation checks failed

GET /api/v0/schedules/{schedule_id}/preview

Run the scheduler on demand from a given point in time. Unlike populate it doen’t permanently delete or insert anything.

/api/v0/services

GET /api/v0/services

Find services, filtered by params

Query Parameters:  

• id – id of the service
• id__eq – id of the service
• id__gt – id greater than
• id__ge – id greater than or equal
• id__lt – id less than
• id__le – id less than or equal
• name – service name
• name__eq – service name
• name__contains – service name contains param
• name__startswith – service name starts with param
• name__endswith – service name ends with param

Example request

GET /api/v0/services?name__startswith=service  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    "service-foo"
]

GET /api/v0/services/{service}

Get service id by name

Example request

GET /api/v0/services/service-foo  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1234,
    "name": "service-foo"
}

PUT /api/v0/services/{service}

Change name for a service. Currently unused/debug only.

DELETE /api/v0/services/{service}

Delete a service. Currently unused/debug only.

GET /api/v0/services/{service}/oncall

Get the current user on-call for a given service/role. Returns event start/end, contact info, and user name.

Example request

GET /api/v0/services/service-foo/oncall/primary  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "contacts": {
            "call": "+1 111-111-1111",
            "email": "jdoe@example.com",
            "im": "jdoe",
            "sms": "+1 111-111-1111"
        },
        "end": 1495695600,
        "start": 1495263600,
        "user": "John Doe"
    }
]

GET /api/v0/services/{service}/oncall/{role}

Get the current user on-call for a given service/role. Returns event start/end, contact info, and user name.

Example request

GET /api/v0/services/service-foo/oncall/primary  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "contacts": {
            "call": "+1 111-111-1111",
            "email": "jdoe@example.com",
            "im": "jdoe",
            "sms": "+1 111-111-1111"
        },
        "end": 1495695600,
        "start": 1495263600,
        "user": "John Doe"
    }
]

GET /api/v0/services/{service}/teams

Get list of team mapped to a service

Example request

GET /api/v0/services/service-foo/teams  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    "team-foo"
]

/api/v0/roles

GET /api/v0/roles

Role search.

Example request:

GET /api/v0/roles?name__startswith=pri HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "name": "primary",
        "display_order": 1
    }
]

Query Parameters:  

• id – id of the role
• id__eq – id of the role
• id__gt – id greater than
• id__ge – id greater than or equal
• id__lt – id less than
• id__le – id less than or equal
• name – role name
• name__eq – role name
• name__contains – role name contains param
• name__startswith – role name starts with param
• name__endswith – role name ends with param

/api/v0/events

GET /api/v0/events

Search for events. Allows filtering based on a number of parameters, detailed below.

Example request:

GET /api/v0/events?team=foo-sre&end__gt=1487466146&role=primary HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "start": 1488441600,
        "end": 1489132800,
        "team": "foo-sre",
        "link_id": null,
        "schedule_id": null,
        "role": "primary",
        "user": "foo",
        "full_name": "Foo Icecream",
        "id": 187795
    },
    {
        "start": 1488441600,
        "end": 1489132800,
        "team": "foo-sre",
        "link_id": "8a8ae77b8c52448db60c8a701e7bffc2",
        "schedule_id": 123,
        "role": "primary",
        "user": "bar",
        "full_name": "Bar Apple",
        "id": 187795
    }
]

Query Parameters:  

• team – team name
• user – user name
• role – role name
• id – id of the event
• start – start time (unix timestamp) of event
• end – end time (unix timestamp) of event
• start__gt – start time (unix timestamp) greater than
• start__ge – start time (unix timestamp) greater than or equal
• start__lt – start time (unix timestamp) less than
• start__le – start time (unix timestamp) less than or equal
• end__gt – end time (unix timestamp) greater than
• end__ge – end time (unix timestamp) greater than or equal
• end__lt – end time (unix timestamp) less than
• end__le – end time (unix timestamp) less than or equal
• role__eq – role name
• role__contains – role name contains param
• role__startswith – role name starts with param
• role__endswith – role name ends with param
• team__eq – team name
• team__contains – team name contains param
• team__startswith – team name starts with param
• team__endswith – team name ends with param
• team_id – team id
• user__eq – user name
• user__contains – user name contains param
• user__startswith – user name starts with param
• user__endswith – user name ends with param

Status Codes:

• 200 OK – no error
• 400 Bad Request – bad request

POST /api/v0/events

Endpoint for creating event. Responds with event id for created event. Events must specify the following parameters:

• start: Unix timestamp for the event start time (seconds)
• end: Unix timestamp for the event end time (seconds)
• user: Username for the event’s user
• team: Name for the event’s team
• role: Name for the event’s role

All of these parameters are required.

Example request:

POST api/v0/events   HTTP/1.1
Content-Type: application/json

{
    "start": 1493667700,
    "end": 149368700,
    "user": "jdoe",
    "team": "team-foo",
    "role": "primary",
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

1

Status Codes:

• 201 Created – Event created
• 400 Bad Request – Event validation checks failed
• 422 Unprocessable Entity – Event creation failed: nonexistent role/event/team

GET /api/v0/events/{event_id}

Get event by id.

Example request:

GET /api/v0/events/1234 HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "end": 1428336000,
    "full_name": "John Doe",
    "id": 1234,
    "link_id": null,
    "role": "primary",
    "schedule_id": 4321,
    "start": 1427731200,
    "team": "team-foo",
    "user": "jdoe"
}

Status Codes:

• 200 OK – no error
• 404 Not Found – Event not found

PUT /api/v0/events/{event_id}

Update an event by id; anyone can update any event within the team

Example request:

PUT /api/v0/events/1234 HTTP/1.1
Content-Type: application/json

{
    "start": 1428336000,
    "end": 1428338000,
    "user": "asmith",
    "role": "secondary"
}

Status Codes:

• 200 OK – Successful update

DELETE /api/v0/events/{event_id}

Delete an event by id, anyone on the team can delete that team’s events

Example request:

DELETE /api/v0/events/1234 HTTP/1.1

Status Codes:

• 200 OK – Successful delete
• 403 Forbidden – Delete not allowed; logged in user is not a team member
• 404 Not Found – Event not found

POST /api/v0/events/swap

Swap events. Takes an object specifying the 2 events to be swapped. Swap can take either single events or event sets, depending on the value of the “linked” attribute. If “linked” is True, the API interprets the “id” attribute as a link_id. Otherwise, it’s assumed to be an event_id. Note that this allows swapping a single event with a linked event.

Example request:

POST api/v0/events/swap   HTTP/1.1
Content-Type: application/json

{
    "events":
    [
        {
            "id": 1,
            "linked": false
        },
        {
            "id": "da515a45e2b2467bbdc9ea3bc7826d36",
            "linked": true
        }
    ]
}

Status Codes:

• 200 OK – Successful swap
• 400 Bad Request – Validation checks failed

POST /api/v0/events/override

Override/substitute existing events. For example, if the current on-call is unexpectedly busy from 3-4, another user can override that event for that time period and take over the shift. Override may delete or edit existing events, and may create new events. The API’s response contains the information for all undeleted events that were passed in the event_ids param, along with the events created by the override.

Params:

• start: Start time for the event substitution
• end: End time for event substitution
• event_ids: List of event ids to override
• user: User who will be taking over

Example request:

POST api/v0/events/override   HTTP/1.1
Content-Type: application/json

{
    "start": 1493677400,
    "end": 1493678400,
    "event_ids": [1],
    "user": "jdoe"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "end": 1493678400,
        "full_name": "John Doe",
        "id": 3,
        "role": "primary",
        "start": 1493677400,
        "team": "team-foo",
        "user": "jdoe"
    }
]

POST /api/v0/events/link

Endpoint for creating linked events. Responds with event ids for created events. Linked events can be swapped in a group, and users are reminded only on the first event of a linked series. Linked events have a link_id attribute containing a uuid. All events with an equivalent link_id are considered “linked together” in a single set. Editing any single event in the set will break the link for that event, clearing the link_id field. Otherwise, linked events behave the same as any non-linked event.

Example request:

POST /api/v0/events/link HTTP/1.1
Content-Type: application/json

[
    {
        "start": 1493667700,
        "end": 149368700,
        "user": "jdoe",
        "team": "team-foo",
        "role": "primary",
    },
    {
        "start": 1493677700,
        "end": 149387700,
        "user": "jdoe",
        "team": "team-foo",
        "role": "primary",
    }
]

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "link_id": "123456789abcdef0123456789abcdef0",
    "event_ids": [1, 2]
}

Status Codes:

• 201 Created – Event created
• 400 Bad Request – Event validation checks failed
• 422 Unprocessable Entity – Event creation failed: nonexistent role/event/team

PUT /api/v0/events/link/{link_id}

Update an event by link_id; anyone can update any event within the team. Only username can be updated using this endpoint.

Example request:

PUT /api/v0/events/link/1234 HTTP/1.1
Content-Type: application/json

{
    "user": "asmith",
}

Status Codes:

• 200 OK – Successful update

DELETE /api/v0/events/link/{link_id}

Delete a set of linked events using the link_id, anyone on the team can delete that team’s events

Example request:

DELETE /api/v0/events/link/1234 HTTP/1.1

Status Codes:

• 200 OK – Successful delete
• 403 Forbidden – Delete not allowed; logged in user is not a team member
• 404 Not Found – Events not found

/api/v0/users

GET /api/v0/users

Get users filtered by params. Returns a list of user info objects for all users matching filter parameters.

Query Parameters:  

• id – id of the user
• id__eq – id of the user
• id__gt – id greater than
• id__ge – id greater than or equal
• id__lt – id less than
• id__le – id less than or equal
• name – username
• name__eq – username
• name__contains – username contains param
• name__startswith – username starts with param
• name__endswith – username ends with param
• full_name – full name
• full_name__eq – username
• full_name__contains – full name contains param
• full_name__startswith – full name starts with param
• full_name__endswith – full name ends with param
• active – whether user has been deactivated (deleted)

Example request:

GET /api/v0/users?name=jdoe   HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "active": 1,
        "contacts": {
            "call": "+1 111-111-1111",
            "email": "jdoe@example.com",
            "im": "jdoe",
            "sms": "+1 111-111-1111"
        },
        "full_name": "John Doe",
        "id": 1234,
        "name": "jdoe",
        "photo_url": "image.example.com",
        "time_zone": "US/Pacific"
    }
]

POST /api/v0/users

Create user. Currently used only in debug mode.

GET /api/v0/users/{user_name}

Get user info by name. Retrieved fields can be filtered with the fields query parameter. Valid fields:

• id - user id
• name - username
• contacts - user contact information
• full_name - user’s full name
• time_zone - user’s preferred display timezone
• photo_url - URL of user’s thumbnail photo
• active - bool indicating whether the user is active in Oncall. Users can be marked inactive after leaving the company to preserve past event information.

If no fields is provided, the endpoint defaults to returning all fields.

Example request:

GET /api/v0/users/jdoe  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "active": 1,
    "contacts": {
        "call": "+1 111-111-1111",
        "email": "jdoe@example.com",
        "im": "jdoe",
        "sms": "+1 111-111-1111"
    },
    "full_name": "John Doe",
    "id": 1234,
    "name": "jdoe",
    "photo_url": "image.example.com",
    "time_zone": "US/Pacific"
}

PUT /api/v0/users/{user_name}

Update user info. Allows edits to:

• contacts
• name
• full_name
• time_zone
• photo_url
• active

Takes an object specifying the new values of these attributes. contacts acts slightly differently, specifying an object with the contact mode as key and new values for that contact mode as values. Any contact mode not specified will be unchanged. Similarly, any field not specified in the PUT will be unchanged.

Example request:

PUT /api/v0/users/jdoe  HTTP/1.1
Content-Type: application/json

{
    "contacts": {
        "call": "+1 222-222-2222",
        "email": "jdoe@example2.com"
    }
    "name": "johndoe",
    "full_name": "Johnathan Doe",
}

Status Codes:

• 204 No Content – Successful edit
• 404 Not Found – User not found

DELETE /api/v0/users/{user_name}

Delete user by name

Example request:

DELETE /api/v0/users/jdoe HTTP/1.1

Status Codes:

• 200 OK – Successful delete
• 404 Not Found – User not found

GET /api/v0/users/{user_name}/teams

Get active teams by user name. Note that this does not return any deleted teams that this user is a member of.

Example request:

GET /api/v0/users/jdoe/teams  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    "team-foo",
    "team-bar"
]

GET /api/v0/users/{user_name}/notifications

Get all notification settings for a user by name.

Example request:

GET /api/v0/users/jdoe/notifications  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 21830,
        "mode": "email",
        "only_if_involved": null,
        "roles": [
            "primary",
            "secondary",
            "shadow",
            "manager"
        ],
        "team": "team-foo",
        "time_before": 86400,
        "type": "oncall_reminder"
    },
    {
        "id": 21831,
        "mode": "email",
        "only_if_involved": null,
        "roles": [
            "primary",
            "secondary",
            "shadow",
            "manager"
        ],
        "team": "team-foo",
        "time_before": 604800,
        "type": "oncall_reminder"
    }
]

POST /api/v0/users/{user_name}/notifications

Endpoint to create notification settings for a user. Responds with an object denoting the created setting’s id. Requests to create notification settings must define the following:

• team
• roles
• mode
• type

Users will be notified via $mode if a $type action occurs on the $team calendar that modifies events having a role contained in $roles. In addition to these parameters, notification settings must define one of time_before and only_if_involved, depending on whether the notification type is a reminder or a notification. Reminders define a time_before and reference the start/end time of an event that user is involved in. There are two reminder types: “oncall_reminder” and “offcall_reminder”, referencing the start and end of on-call events, respectively. time_before is specified in seconds and denotes how far in advance the user should be reminded of an event.

Notifications are event-driven, and created when a team’s calendar is modified. By default, the notification types are:

• event_created
• event_edited
• event_deleted
• event_swapped
• event_substituted

Non-reminder settings must define only_if_involved which determines whether the user will be notified on all actions of the given typ or only on ones in which they are involved. Note that time_before must not be specified for a non-reminder setting, and only_if_involved must not be specified for reminder settings.

An authoritative list of notification types can be obtained from the /api/v0/notification_types GET endpoint, which also details whether the type is a reminder. This will obtain all notification type data from the database, and is an absolute source of truth for Oncall.

Example request:

POST api/v0/events   HTTP/1.1
Content-Type: application/json

    {
        "team": "team-foo",
        "roles": ["primary", "secondary"],
        "mode": "email",
        "type": "event_created",
        "only_if_involved": true
    }

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

    {
        "id": 1234
    }

GET /api/v0/users/{user_name}/upcoming

Endpoint for retrieving a user’s upcoming shifts. Groups linked events into a single entity, with the number of events indicated in the num_events attribute. Non-linked events have num_events = 0. Returns a list of event information for each of that user’s upcoming shifts. Results can be filtered with the query string params below:

Query Parameters:  

• limit – The number of shifts to retrieve. Default is unlimited
• role – Filters results to return only shifts with the provided roles.

Example request:

GET /api/v0/users/jdoe/upcoming  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "end": 1496264400,
        "full_name": "John Doe",
        "id": 169877,
        "link_id": "7b3b96279bb24de8ac3fb7dbf06e5d1e",
        "num_events": 7,
        "role": "primary",
        "schedule_id": 1788,
        "start": 1496221200,
        "team": "team-foo",
        "user": "jdoe"
    }
]

GET /api/v0/users/{user_name}/pinned_teams

Get all pinned team names for a user

Example request:

GET /api/v0/users/jdoe/pinned_teams HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    "team-foo"
]

POST /api/v0/users/{user_name}/pinned_teams

Pin a team to the landing page for a user

Example request:

POST /api/v0/users/jdoe/pinned_teams HTTP/1.1
Host: example.com

{
    "team": "team-foo"
}

Status Codes:

• 201 Created – Successful team pin
• 400 Bad Request – Missing team parameter or team already pinned

DELETE /api/v0/users/{user_name}/pinned_teams/{team_name}

Delete a pinned team

Example request:

DELETE /api/v0/users/jdoe/pinned_teams/team-foo HTTP/1.1

Status Codes:

• 200 OK – Successful delete
• 403 Forbidden – Delete not allowed; logged in user does not match user_name
• 404 Not Found – Team not found in user’s pinned teams

/api/v0/notifications

PUT /api/v0/notifications/{notification_id}

Edit user notification settings. Allows editing of the following attributes:

• roles: list of role names
• team: team name
• mode: contact mode name

• type: string defining what event to notify on. Types are detailed in notification

  POST documentation

• time_before: in units of seconds (if reminder setting)
• only_if_involved: boolean (if notification setting)

Example request

PUT /api/v0/events/1234 HTTP/1.1
Content-Type: application/json

{
    "team": "team-bar",
    "mode": "call",
    "user": "asmith",
    "roles": ["secondary"]
}

Status Codes:

• 200 OK – Successful edit
• 400 Bad Request – Validation checks failed.

DELETE /api/v0/notifications/{notification_id}

Delete user notification settings by id.

Example request:

DELETE /api/v0/notifications/1234  HTTP/1.1

Status Codes:

• 200 OK – Successful delete
• 404 Not Found – Notification setting not found

/api/v0/notification_types

GET /api/v0/notification_types

Returns all notification types and whether they are reminder notifications.

Example request:

GET /api/v0/notification_types HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "name": "oncall_reminder",
        "is_reminder": 1
    }
]

/api/v0/modes

GET /api/v0/modes

Get all contact modes

/api/v0/search

GET /api/v0/search

Endpoint for searching for teams, services, users, and team users by keyword. Used for typeaheads in the frontend. Team/service search is done using substring matching, while user and team_user search is done with prefix matching. If no fields are provided, the endpoint defaults to [‘teams’, ‘services’]. A keyword parameter must be passed in the query string.

Example request

GET /api/v0/search?keyword=key  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

    {
        "services": [
                {
                    "service-key": "team-foo"
                },
                {
                    "service-key2": "team-bar"
                }
            ]
        "teams": [
                "team-key",
                "team-key2"
            ]
    }

An example for user search: Example request

GET /api/v0/search?keyword=key&fields=users  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "users":
        [
            {
                "full_name": "John Doe",
                "name": "jdoe"
            }
        ]
}

/api/v0/audit

GET /api/v0/audit

Search audit log. Allows filtering based on a number of parameters, detailed below. Returns an entry in the audit log, including the name of the associated team, action owner, and action type, as well as a timestamp and the action context. The context tracks different data based on the action, which may be useful in investigating. Audit logs are tracked for the following actions:

• admin_created
• event_created
• event_edited
• roster_created
• roster_edited
• roster_user_added
• roster_user_deleted
• team_created
• team_edited
• event_deleted
• event_swapped
• roster_user_edited
• team_deleted
• admin_deleted
• roster_deleted
• event_substituted

Example request:

GET /api/v0/audit?team=foo-sre&end=1487466146&action=event_created  HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "context":"{"new_event_id":441072,"request_body":{"start":1518422400,"end":1518595200,"role":"primary","user":jdoe","team":"foo-sre"}}"
        "timestamp": 1488441600,
        "team_name": "foo-sre",
        "owner_name": "jdoe"
        "action_name: "event_created"
    }
]

Query Parameters:  

• team – team name
• owner – action owner name
• action – name of action taken. If provided multiple action names,
• id – id of the event
• start – lower bound for audit entry’s timestamp (unix timestamp)
• end – upper bound for audit entry’s timestamp (unix timestamp)