---
title: "Create team"
method: POST
path: "/teams"
tags: ["teams"]
---

# Create team

`POST /teams`

Creates a new team in your workspace.
You must provide the team `name` and a unique `handle` for @mentions.

## Required Fields

- `name`: The name of the team (1-255 characters, must be unique per workspace)
- `handle`: Unique handle for @mentions (lowercase alphanumeric only, 1-255 characters, must be unique per workspace)

## Response

Returns a reference to the created team with its ID and self link.
Use the GET endpoint to retrieve the full team details.

## Request body

- object
  - `data` object, required
    - `fields` TeamCreateOrUpdateFields, required — Fields for creating or updating a team. For creation, `name` and `handle` are required. For updates, the `fields` object is required but all individual field properties within it are optional. **Note:** `avatarUrl` is read-only and cannot be set via API. Avatar management is only available through the UI.
      - `name` string — The name of the team. # Validation - Required for creation - Must be between 1 and 255 characters - Must be unique per workspace # Filtering Supports exact match via `name` parameter and partial match via `query` parameter on GET /v2/teams.
      - `handle` string — Unique handle for @mentions. # Validation - Required for creation - Lowercase letters and numbers only (no uppercase, spaces, or special characters) - Must be unique per workspace
      - `description` string — Optional description of the team. # Validation - Optional field - Maximum length: 10000 characters

## Response `201`

Team created successfully

- TeamReferenceResponse — Response wrapper containing a team reference.
  - `data` TeamReference, required — Minimal reference to a team resource containing only identifying information.
    - `id` string, uuid, required — Unique identifier of the team
    - `type` 'team', required — Resource type identifier
    - `links` TeamLinks, required — Links for navigating team resources.
      - `self` string, uri, required — URL of the team resource.
      - `members` string, uri, required — URL of the paginated team members sub-resource.
      - `html` string, uri, required — URL of the team page in the Productboard UI.

## Other responses

- `400` — Bad Request - Invalid input format or malformed request
- `401` — Unauthorized - Missing or invalid authentication credentials
- `403` — Forbidden - Insufficient permissions
- `408` — Request Timeout - The server did not receive a complete request within the allowed time
- `409` — Conflict - Action cannot be performed due to current state or constraint violation
- `422` — Unprocessable Entity - Validation failed (e.g., missing required fields, unknown fields)
- `429` — Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time
- `500` — Internal Server Error - An unexpected error occurred on the server, please retry or contact support

---

[API](https://skmtc.dev/productboard/apis/notes.md) · [All operations](https://skmtc.dev/productboard/apis/notes/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/productboard/notes/revisions/b4004749b60f/schema)