Set or clear a team's picture
PUT /teams/{id}/hero
Chooses the picture a team shows, or removes it so the team shows its initials.
You need teams.admin for this team, granted globally, within this
team or within a team above it, or system.admin. Being a member
isn’t enough, and teams.read isn’t needed. The body is checked
next, then that the team exists: a deleted team, or an id with no
team, gets 404.
The asset must be public, filed under this team and not deleted. If
it’s rated mature, you also need to own it, or to have mature
content turned on where the instance allows it; system.admin is
exempt and teams.admin isn’t. Any asset that doesn’t qualify,
including an id with no asset, gets the same 400. The asset’s
status, and whether it has a file or preview yet, aren’t checked.
Every team response shows the picture only when it can be shown to
the person asking: the asset must still qualify for them and have a
col preview on record for its file. So a newly chosen picture may
not appear until that preview is recorded, and one that stops
qualifying is left out until it qualifies again; the choice itself
is kept. Deleting the asset permanently clears the choice.
Each request replaces the previous choice, with no check for changes
made in between, so the one saved last stands. Clearing a team with
no picture still succeeds and updates updated_at. 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 ”Send asset_id to choose a picture, or clear_hero: true to remove
it. A body with neither, or with both, gets 400; clear_hero: false
counts as neither.
object
The asset to use. It must be public, filed under this team and not deleted, with the mature rule in the description above. Any other id, including one with no asset, gets the same 400. Sending null is the same as leaving it out.
Set to true to remove the picture, so the team shows its initials.
It can’t be combined with asset_id.
Responses
Section titled “ Responses ”The team, with its picture as you can see it now.
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