---
title: "Delete a Team"
method: DELETE
path: "/v1/teams/{teamId}"
tags: ["teams"]
---

# Delete a Team

`DELETE /v1/teams/{teamId}`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/v1/teams/{teamId}`
- Auth: HTTP bearer

Delete a team under your account. You need to send a `DELETE` request with the desired team `id`. An optional array of reasons for deletion may also be sent. Enterprise teams can only be deleted in test billing mode and when not linked to an organization. Enterprise children of an organization cannot be deleted.

## Path parameters

- `teamId` string, required

## Query parameters

- `newDefaultTeamId` string: Id of the team to be set as the new default team
- `slug` string

## Request body

- object
  - `reasons` object[]: Optional array of objects that describe the reason why the team is being deleted.
    - `slug` string, required: Idenitifier slug of the reason why the team is being deleted.
    - `description` string, required: Description of the reason why the team is being deleted.

## Response `200`

The Team was successfully deleted

- object: The Team was successfully deleted
  - `id` string, required: The ID of the deleted Team
  - `newDefaultTeamIdError` false | true: Signifies whether the default team update has failed, when newDefaultTeamId is provided in request query.

## Other responses

- `400`: One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
- `401`: The request is not authorized.
- `402`
- `403`: You do not have permission to access this resource. The authenticated user can't access the team
- `404`
- `409`
- `410`
- `503`

## Changes

- **2026-09-30** `099fbe1f521c`: 1 info
  - added the non-success response with the status `404`
- **2026-09-02** `284e10c18f4d`: 1 info
  - added the non-success response with the status `503`
- **2026-07-21** `2ae10ee9d21c`: 1 info
  - added the non-success response with the status `410`
- **2026-01-22** `c12186034433`: 1 breaking, 2 warning
  - request body became required
  - added the new `false` enum value to the `newDefaultTeamIdError` response property for the response status `200`
  - added the new `true` enum value to the `newDefaultTeamIdError` response property for the response status `200`
- **2025-10-09** `50caddad4ae7`: 1 info
  - removed the non-success response with the status `404`

[Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v1/teams/:teamId/delete.md)

---

[API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)