Create a team

Creates a new team in your organization. Needs a global API token that isn't read-only. The team starts with no members, so invite team members 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.

POST https://betterstack.com/api/v2/teams

Headers

Authorization
required string
Content-Type
required string

Body parameters

name
required string
incident_grouping_period
integer
incident_grouping_metadata_scope
array
notify_about_all_incidents_in_a_group
boolean
reporting_enabled
boolean
opened_emails_tracking_enabled
boolean
on_call_reminder_lead_time
integer
on_call_reminder_sms
boolean
on_call_reminder_email
boolean
on_call_reminder_push
boolean
201

Response 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
    }
  }
}
401

Response body

{
  "errors": "We could not authenticate your request. Please provide a valid Global API token or Better Stack OAuth token."
}
403

Response body

{
  "errors": "This API token is read-only and cannot be used for write operations."
}
409

Response body

{
  "errors": "Another change is in progress. Please try again in a moment."
}
422

Response body

{
  "errors": "Team quota reached. Please upgrade your plan."
}
422

Response body

{
  "errors": "Please upgrade your account to enable reporting."
}
503

Example cURL

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"]
  }'