Skip to main content

​
Overview

Creates a new team in your PagerDuty account with a name, optional description, and default role for new members.
This is a write tool that creates new resources in your PagerDuty account. It requires the --enable-write-tools flag to be enabled.

​
Parameters

​
name
string
required
The name of the team. Should be descriptive and unique.
​
description
string
Optional description explaining the team’s purpose or responsibilities.
​
default_role
string
default:"manager"
The default role assigned to new users added to the team. Options:
  • manager - Full management permissions for the team
  • none - No default role (must be specified when adding members)

​
Response

Returns the created team object including the assigned team ID.

​
Example Usage

​
Create a basic team

Create a team called "Backend Services"

​
Create with description

Create a team named "Platform Engineering" with description "Responsible for infrastructure and platform services"

​
Create with specific default role

Create a team called "Observers" with default role "none"

​
Understanding Team Roles

​
Default Role

The default_role parameter determines what permissions new members get when added to the team:
  • manager (default) - Team managers can:
    • View and modify team settings
    • Add or remove team members
    • Manage team-owned services and schedules
    • Assign services to the team
  • none - No automatic role assignment. When adding members, you must explicitly specify their role (observer, responder, or manager).
The default_role only applies when adding members to the team. It does not affect existing members or the initial creator of the team.

​
Team Member Roles

While default_role can only be “manager” or “none”, individual team members can have these roles:
  • observer - Read-only access to team resources
  • responder - Can respond to incidents for team services
  • manager - Full team management permissions
See manage_members for details on adding members with specific roles.

​
Common Use Cases

  • New team setup - Create teams for new departments or projects
  • Organizational restructuring - Set up teams when reorganizing
  • Service ownership - Create teams to own specific services
  • Access control - Group users by responsibility area
  • On-call management - Create teams for on-call rotations

​
Post-Creation Steps

After creating a team, you typically want to:
  1. Add members - Use add_team_member to add users
  2. Assign services - Associate services with the team
  3. Create schedules - Set up on-call schedules for the team
  4. Configure escalation - Create escalation policies for team services

​
Important Notes

Team names should be clear and descriptive. They appear throughout PagerDuty in service assignments, schedules, and escalation policies.
You cannot create duplicate team names. If a team with the same name exists, the creation will fail.

list_teams

View all teams

get_team

Get team details

add_team_member

Add members to the team

update_team

Modify team settings

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us