---
title: "Delete an organisation"
description: "Delete the organisation; admins only."
canonical: "https://grid82.com/docs/builder-api/orgs/delete"
updated: "2026-11-13"
---

# Delete an organisation

`DELETE https://studio.grid82.app/v1/organizations/{organizationId}`

Delete the organisation; admins only.

Send its name as `confirm`. This deletes every suite, app, and directory, and makes every address stop answering. App data remains through the grace period so deletion can be undone, but addresses are released immediately. Deletion is refused while a paid subscription is attached; cancel it with `billing.cancel` and wait for the period to end first, because deleting the organisation does not stop charges.

Requires the `account:write` scope. Operation `orgs.delete`. MCP tool `orgs_delete`. CLI: `grid82 orgs delete` (`npx grid82`).

## Path parameters

| Name             | Type   | Required | Description |
| ---------------- | ------ | -------- | ----------- |
| `organizationId` | string | yes      |             |

## Query parameters

| Name      | Type   | Required | Description           |
| --------- | ------ | -------- | --------------------- |
| `confirm` | string | no       | Up to 200 characters. |

## Headers

| Name              | Type   | Required | Description                                                                                                                                                                                                                                                        |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Idempotency-Key` | string | no       | Any unique string. Sending the same key with the same request again returns the first response (marked `Idempotency-Replayed: true`) instead of running it twice. Reusing it for a different request is refused with 409. Kept for 24 hours. Up to 255 characters. |

**Authorizations**

- `Authorization` (bearer, in header, required)

## Response

**200**: Success

- `data` (`object`, required)
- `data.id` (`string`, required)

```json
{
  "data": {
    "id": "<string>"
  }
}
```

**4XX**: Refused

- `error` (`object`, required)
- `error.code` (`enum<string>`, required, one of: `not_found, forbidden, unauthenticated, validation_failed, conflict, rate_limited, payment_required, not_implemented, internal`)
- `error.message` (`string`, required)
- `error.details` (`Record<string, unknown>`)

```json
{
  "error": {
    "code": "not_found",
    "message": "<string>",
    "details": {}
  }
}
```

**Example request**

```bash
curl --request DELETE \
  --url 'https://studio.grid82.app/v1/organizations/<organizationId>' \
  --header 'Authorization: Bearer <token>'
```