---
title: delete-a-team
product: vercel
url: /docs/rest-api/teams/delete-a-team
canonical_url: "https://vercel.com/docs/rest-api/teams/delete-a-team"
last_updated: 2026-11-18
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about delete-a-team on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
search_with_vercel_cli: npx vercel@latest docs search "<query>"
---

# Delete a Team

```http
DELETE /v1/teams/{teamId}
```

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.

## Authentication

**bearerToken**: HTTP bearer

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `teamId` | string | Yes | The Team identifier to perform the request on behalf of. |


## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `newDefaultTeamId` | string | No | Id of the team to be set as the new default team |
| `slug` | string | No | The Team slug to perform the request on behalf of. |


## Request body

Required: Yes

Content-Type: `application/json`

```json
{
  "type": "object",
  "properties": {
    "reasons": {
      "type": "array",
      "description": "Optional array of objects that describe the reason why the team is being deleted.",
      "items": {
        "type": "object",
        "description": "An object describing the reason why the team is being deleted.",
        "required": [
          "slug",
          "description"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "description": "Idenitifier slug of the reason why the team is being deleted."
          },
          "description": {
            "type": "string",
            "description": "Description of the reason why the team is being deleted."
          }
        }
      }
    }
  }
}
```

## Example request

### TypeScript

```typescript
const response = await fetch('https://api.vercel.com/v1/teams/teamId?newDefaultTeamId=string&slug=string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);
```

### Next.js

```typescript
'use server';

export async function callEndpoint() {
  const response = await fetch('https://api.vercel.com/v1/teams/teamId?newDefaultTeamId=string&slug=string', {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${process.env.VERCEL_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    next: { revalidate: 3600 }
  });

  if (!response.ok) {
    throw new Error('Request failed');
  }

  return response.json();
}
```

### cURL

```bash
curl -X DELETE 'https://api.vercel.com/v1/teams/teamId?newDefaultTeamId=string&slug=string' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
```

## Example response

```json
{
  "id": "team_LLHUOMOoDlqOp8wPE4kFo9pE",
  "newDefaultTeamIdError": "true"
}
```

## Responses

### 200: The Team was successfully deleted

Content-Type: `application/json`

```json
{
  "type": "object",
  "description": "The Team was successfully deleted",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the deleted Team"
    },
    "newDefaultTeamIdError": {
      "type": "boolean",
      "description": "Signifies whether the default team update has failed, when newDefaultTeamId is provided in request query.",
      "enum": [
        false,
        true
      ]
    }
  }
}
```

### 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: No description

### 403: You do not have permission to access this resource.
The authenticated user can't access the team

### 404: No description

### 409: No description

### 410: No description

### 503: No description

---

## Related

- [teams endpoints](/docs/rest-api#teams)

- [REST API overview](/docs/rest-api)

- [OpenAPI spec](https://vercel.com/openapi.json) (machine-readable, all endpoints)

## Search the docs from your terminal

Search the Vercel docs and read pages as Markdown with the Vercel CLI. No login required.

```bash
# Find docs pages by keyword
npx vercel@latest docs search "environment variables"
npx vercel@latest docs search "function timeout"

# Print a docs page as Markdown, by path or URL
npx vercel@latest docs inspect <page>
```

---

[View full sitemap](/docs/sitemap)


If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.
