Skip to content

Delete a team

DELETE
/teams/{id}

Deletes a team: it disappears from team lists and lookups, but nothing else about it is removed, and there’s no way to restore it.

You need to be signed in with teams.admin or system.admin granted globally; a grant within this team isn’t enough. A team that’s already deleted, or an id with no team, gets 404, so of two deletes at once one gets 204 and the other 404.

The team keeps its parent and child links, members, followers, role assignments and grants, and the assets and posts filed under it; its slug stays taken. Members can still open its team-only assets, and grants given within the team still apply, to it and to the teams below it, which stay where they are.

Nothing removes the team for good later. A copy of the team read just before the delete can, rarely, still be returned afterwards. An id that isn’t a UUID gets a plain-text 400 before sign-in is checked, and server errors get a plain-text 500. No audit entry is recorded.

id
required
string format: uuid

The team’s id.

The team was deleted.

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed