v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Create a team

Creates a new team and returns the created team object. The authenticated user becomes the team's owner.

When app is supplied, the request is scoped to that app and the caller must hold the corresponding app scope. Omit org unless you want the team pinned to a specific organization. A default chat thread is provisioned for the team automatically after creation.

post/api/v1/teams

Request body

descriptionstring

Optional human-readable description of the team's purpose.

metadataobject

Arbitrary key-value pairs you can attach to the team for your own use. Values must be strings.

namestring required

Display name for the team.

orgstring

Organization ID (org_...) to associate the team with. Omit to create the team without an org affiliation.

Example request

{
  "acl": {
    "add": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "grants": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "remove": [
      {
        "principal": "string",
        "principal_type": "user"
      }
    ]
  },
  "description": "An example description.",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "org": "string"
}

Response

Successful response

appstring

ID of the developer application this team belongs to (dap_...). null if the team is not scoped to an app.

badgesobject

Aggregated badge counts for the team, keyed by category. null when badge data is not loaded.

created_atstring date-time

When this team was created (ISO 8601).

descriptionstring

Human-readable description of the team's purpose. null if not set.

idstring required

Team ID (tem_...).

membership_statusstring

The authenticated viewer's role on this team. One of "owner", "admin", or "member". null if the viewer is not a member.

metadataobject

Arbitrary key-value metadata attached to this team. Returns an empty object when no metadata has been set.

namestring

Display name of the team.

orgstring

ID of the organization this team belongs to (org_...). null if the team is not org-scoped.

sandboxstring

ID of the developer sandbox this team is scoped to (dsb_...). null outside sandbox contexts.

slugstring

URL-safe slug for the team, derived from the team name. null if not set.

updated_atstring date-time

When this team was last updated (ISO 8601).

Example response

{
  "acl": {
    "add": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "grants": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "remove": [
      {
        "principal": "string",
        "principal_type": "user"
      }
    ]
  },
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "badges": {},
  "created_at": "2024-01-01T00:00:00Z",
  "description": "An example description.",
  "id": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "membership_status": "member",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
  "slug": "example-slug",
  "updated_at": "2024-01-01T00:00:00Z"
}