Update a team's name or description
PATCH /teams/{id}
Changes a team’s name, its description or both. The slug can’t be changed, and parents are managed with the parent endpoints.
You need to be signed in with teams.admin or system.admin
granted globally; a grant within this team isn’t enough. A deleted
team, or an id with no team, gets 404.
Send only what you want to change; a field you leave out or send as
null stays as it is. name is saved exactly as sent, so it isn’t
trimmed and can be empty, and an empty description clears the
description. The lengths shown aren’t checked. Every successful
request, even {}, updates updated_at.
Nothing checks for edits made in between: when two requests change
the same field, the one saved last stands. Teams that list this one
as a parent can keep showing its old name until the server next
reads them fresh. The change is saved before the response is put
together, so a plain-text 500 can arrive after it was saved. A body
that can’t be read as JSON, or an id that isn’t a UUID, gets a
plain-text 400 before sign-in is checked. No audit entry is
recorded.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The team’s id.
Request Body required
Section titled “Request Body required ”object
The new name, saved exactly as sent, so it can be empty. Leave it out or send null to keep the current one. The limits shown aren’t checked.
The new description; an empty string clears it. Leave it out or send null to keep the current one. The limit shown isn’t checked.
Responses
Section titled “ Responses ”The updated team, with its parents.
object
The team’s short name, unique among this server’s teams. A deleted team keeps its slug.
Example
aurora-rndExample
Aurora R&DThe server a copied team came from. Left out for this server’s own teams; nothing in the API creates copies.
The team’s picture: fetch it from
/assets/{hero_asset_id}/variants/col. Left out when the team has
no picture you can see, and then clients show the team’s initials.
This is checked on every read, for the person asking. The chosen
asset must still be public, filed under the team and not deleted,
with a col preview on record for its file; if it’s rated mature,
the viewer must own it, have mature content turned on where the
instance allows it, or have system.admin. The choice is kept when
the picture stops qualifying, so it comes back when it qualifies
again. It isn’t shared with other servers.
The team’s direct parents. Sent when one team is returned (an empty list if it has none) and left out of lists. Deleted parents aren’t included, though a parent renamed or deleted since the team last changed can still show as it was.
object
How many direct memberships the team has; members of teams below it
aren’t counted. Only listTeams sends it.
How many assets filed under the team haven’t been deleted. Every one
counts, including drafts and assets you can’t open or that are
hidden from you as mature, so it can be higher than what the team’s
asset list shows you. Posts and collections aren’t counted. Only
listTeams sends it.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completed