# Create a team

Creates a new team in your organization. Needs a [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) that isn't read-only. The team starts with no members, so [invite team members](https://betterstack.com/docs/uptime/api/team-members/invite/) next, with `team_name` set to the new team's name.

Settings you leave out start at their defaults. The team is created only if every setting is accepted. When one is refused, the request returns an error and no team is created. Changing a setting your plan doesn't include from its default returns `422`.

[endpoint]
base_url = "https://betterstack.com"
path = "/api/v2/teams"
method = "POST"

[[body_param]]
name = "name"
description = "The name of the team. Must be unique in your organization, ignoring case."
required = true
type = "string"

[[body_param]]
name = "incident_grouping_period"
description = "Group incidents triggered within this many seconds of each other, for example `300` for 5 minutes. `0` never groups incidents. Defaults to `300`."
required = false
type = "integer"

[[body_param]]
name = "incident_grouping_metadata_scope"
description = "Metadata keys that keep incidents apart: incidents whose values for these keys differ are never grouped, for example `[\"environment\"]` to separate staging and production incidents. Defaults to `[\"Origin\"]`."
required = false
type = "array"

[[body_param]]
name = "notify_about_all_incidents_in_a_group"
description = "Notify about every incident in a group. Set to `false` to be notified only about the first incident in a group. Defaults to `true`."
required = false
type = "boolean"

[[body_param]]
name = "reporting_enabled"
description = "Turn on reporting, which unlocks the reports in Incidents. Needs a plan with reporting. Defaults to `false`."
required = false
type = "boolean"

[[body_param]]
name = "opened_emails_tracking_enabled"
description = "Add an event to the incident timeline when a team member opens the incident e-mail. Turning it off needs a plan that lets you configure the incident timeline. Defaults to `true`."
required = false
type = "boolean"

[[body_param]]
name = "on_call_reminder_lead_time"
description = "How many seconds before their on-call shift starts responders get a reminder: `0` for never, `3600`, `21600`, `43200`, `86400`, `172800` or `604800`. Changing it to any value except `0` needs a plan with on-call scheduling. Defaults to `86400`."
required = false
type = "integer"

[[body_param]]
name = "on_call_reminder_sms"
description = "Send the on-call reminder by SMS. Needs a plan with on-call scheduling and SMS alerts. Defaults to `false`."
required = false
type = "boolean"

[[body_param]]
name = "on_call_reminder_email"
description = "Send the on-call reminder by e-mail. Needs a plan with on-call scheduling. Defaults to `true`."
required = false
type = "boolean"

[[body_param]]
name = "on_call_reminder_push"
description = "Send the on-call reminder by push notification. Needs a plan with on-call scheduling and push notifications. Defaults to `true`."
required = false
type = "boolean"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content-Type"
description = "application/json"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''The team was created.'''
body = '''{
  "data": {
    "id": "t123",
    "type": "team",
    "attributes": {
      "name": "Platform team",
      "created_at": "2026-11-16T09:00:00.000Z",
      "updated_at": "2026-11-16T09:00:00.000Z",
      "incident_grouping_period": 600,
      "incident_grouping_metadata_scope": ["environment"],
      "notify_about_all_incidents_in_a_group": true,
      "reporting_enabled": false,
      "opened_emails_tracking_enabled": true,
      "on_call_reminder_lead_time": 86400,
      "on_call_reminder_sms": false,
      "on_call_reminder_email": true,
      "on_call_reminder_push": true
    }
  }
}'''

[[response]]
status = 401
description = '''Returned for a missing or invalid token, or a token that isn't a global API token.'''
body = '''{
  "errors": "We could not authenticate your request. Please provide a valid Global API token or Better Stack OAuth token."
}'''

[[response]]
status = 403
description = '''Returned for a read-only global API token.'''
body = '''{
  "errors": "This API token is read-only and cannot be used for write operations."
}'''

[[response]]
status = 409
description = '''Another change to your organization's teams is in progress. Retry in a moment.'''
body = '''{
  "errors": "Another change is in progress. Please try again in a moment."
}'''

[[response]]
status = 422
description = '''Returned when `name` is empty, not a string, or already taken, or when your organization has reached its team quota. A missing `name` returns `required_attributes` instead.'''
body = '''{
  "errors": "Team quota reached. Please upgrade your plan."
}'''

[[response]]
status = 422
description = '''Returned when a setting has an invalid value or needs a plan your organization isn't on. No team is created.'''
body = '''{
  "errors": "Please upgrade your account to enable reporting."
}'''

[[response]]
status = 503
description = '''Try again later. No team is created.'''
body = ''''''
[/responses]

#### Example cURL

```shell
[label Example]
curl --request POST \
  --url https://betterstack.com/api/v2/teams \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Platform team",
    "incident_grouping_period": 600,
    "incident_grouping_metadata_scope": ["environment"]
  }'
```
