Teams

Teams own alerts and define how those alerts are routed: who is a member, how alerts escalate, and who is on call through rotations and overrides. Every account has a Default team whose id equals your account ID.

Keys with the Read Only role can call the GET endpoints. Keys with the Admin role can call all of them. The list endpoint is paginated, see Pagination.

The Team Object

Name	Type	Description
accountId	number	The account ID.
id	number	The team ID.
name	string	The team name.
createdBy	string	Who created the team. Teams created with an API key show apikey:<keyId>.
timezone	string	An IANA time zone name, for example America/Chicago.
members	array of strings	Usernames of the team’s members.
mute	number	Mute expiry in epoch seconds, when the team is muted.
muteUser	string	Who muted the team.
escalations	array	Escalation steps. See below.
overrides	array	On-call overrides. See below.
rotations	array	On-call rotations. See below.

escalations items:

Name	Type	Description
time	number	Minutes after the alert fires before this step runs. 1 to 1440.
type	string	all, next, previous, random, team, or user.
value	string	A username when type is user, or a team ID when type is team. Not used for other types.

overrides items:

Name	Type	Description
username	string	The user who takes over on call.
start	number	Start of the override, in epoch seconds.
end	number	End of the override, in epoch seconds.

rotations items:

Name	Type	Description
name	string	Rotation name, 2 to 100 characters.
start	number	When the rotation starts, in epoch seconds.
type	string	hourly, daily, or weekly.
length	number	Length of each shift in units of type. 1 to 23.
order	array of strings	Usernames, in rotation order.
activePeriod	array	When the rotation is active. Each item has a start and end, given as half-hour offsets within the week, from 0 to 168.

List Teams

GET /account/{accountId}/team

Required role
Admin or Read Only

Path parameters

Name	Type	Required	Description
accountId	number	Yes	Your account ID.

Query parameters

Name	Type	Required	Description
limit	number	No	Page size. Defaults to 20. Any whole number from 1 to 100. Any other value is treated as 20.
id	number	No	Pagination cursor. Pass the pk.id value from the previous response.

Response

Status 200.

Name	Type	Description
items	array	Team objects, as described in The Team Object.
pk	object	Present only when more results exist. Contains id, the cursor for the next page.

Errors

Status	When
400	id is not numeric.

Notes

• Teams are sorted by ID, lowest first. There is no order parameter.
• A page can contain fewer than limit items while pk is still present. Keep requesting pages until pk is absent.

Create Team

POST /account/{accountId}/team

Required role
Admin

Path parameters

Name	Type	Required	Description
accountId	number	Yes	Your account ID.

Request body

Send Content-Type: application/json.

Name	Type	Required	Description
name	string	Yes	Team name, 1 to 100 characters. Default is not allowed.
timezone	string	Yes	An IANA time zone name.

Response

Status 200. Returns the new team, as described in The Team Object.

Errors

Status	When
400	The time zone is invalid.
409	The account has reached its maximum number of teams.

Notes

• createdBy is set to apikey:<keyId>.
• An audit log entry of type team-create is written with your API key as the actor.

Get Team

GET /account/{accountId}/team/{teamId}

Required role
Admin or Read Only

Path parameters

Name	Type	Required	Description
accountId	number	Yes	Your account ID.
teamId	number	Yes	The team ID.

Response

Status 200. Returns the team, as described in The Team Object.

Update Team

PATCH /account/{accountId}/team/{teamId}

Required role
Admin

Path parameters

Name	Type	Required	Description
accountId	number	Yes	Your account ID.
teamId	number	Yes	The team ID.

Request body

Send Content-Type: application/json. Include at least one field. Fields use the same shapes as in The Team Object.

Name	Type	Required	Description
name	string	No	New team name.
timezone	string	No	New IANA time zone.
escalations	array	No	Replaces all escalation steps.
overrides	array	No	Replaces all overrides.
rotations	array	No	Replaces all rotations.

Response

Status 200 with an empty object.

Errors

Status	When
400	You rename the Default team.
400	The time zone is invalid.
400	You set rotations, escalations, or overrides on a team with no members.
400	A referenced user is not a member of the team.
400	A rotation, escalation, or override breaks the rules listed in the notes.
404	The team does not exist.
409	An escalation refers to a team that does not exist.

Notes

• Arrays replace the existing value. To add a single rotation, send the full list including the existing ones.
• Escalation time values must not decrease from one step to the next. A user step needs a username and a team step needs a team ID.
• Rotation active periods need start less than end and must not overlap.
• Overrides need start less than end, must be sequential, and start must not be in the past.
• The Default team cannot be renamed.

Delete Team

DELETE /account/{accountId}/team/{teamId}

Required role
Admin

Path parameters

Name	Type	Required	Description
accountId	number	Yes	Your account ID.
teamId	number	Yes	The team ID.

Response

Status 200 with an empty object.

Errors

Status	When
403	The team is the Default team.
404	The team does not exist.

Notes

• The team is also removed from every user who belonged to it.
• The Default team cannot be deleted.

Add Team Member

POST /account/{accountId}/team/{teamId}/member

Required role
Admin

Path parameters

Name	Type	Required	Description
accountId	number	Yes	Your account ID.
teamId	number	Yes	The team ID.

Request body

Send Content-Type: application/json.

Name	Type	Required	Description
username	string	Yes	Username of the user to add, 1 to 128 characters.

Response

Status 200 with an empty object.

Errors

Status	When
404	The team or user does not exist.
409	The user is already a member.

Remove Team Member

DELETE /account/{accountId}/team/{teamId}/member/{username}

Required role
Admin

Path parameters

Name	Type	Required	Description
accountId	number	Yes	Your account ID.
teamId	number	Yes	The team ID.
username	string	Yes	Username of the member, URL-encoded.

Response

Status 200 with an empty object.

Errors

Status	When
404	The team or user does not exist.
409	The user is not a member, or is still assigned to a rotation, escalation, or override on the team.

Notes

• Remove the user from the team’s rotations, escalations, and overrides first by updating the team.

Not Available on v1

Muting and unmuting a team is not available through the API. Use the OpsFusion app.

Related

• Alerts
• Users
• Audit Logs
• Pagination
• Errors