Create a team
POST /teams
Creates a team, optionally under one or more parent teams.
You need to be signed in with teams.create, teams.admin or
system.admin granted globally; a grant within a team isn’t enough.
Creating a team doesn’t make you a member or give you any role in
it.
slug and name have surrounding spaces removed and then mustn’t
be empty, or the answer is 400; description is saved as sent. The
maximum lengths shown aren’t checked, and the slug isn’t held to any
format, so any slug that isn’t blank is accepted. A slug that’s
already taken gets 409, and deleted teams keep theirs, so a deleted
team’s slug counts as taken. If two requests try to create the same
slug at once, one succeeds and the other gets 409. The slug can’t be
changed later.
Each id in parent_ids must name an existing team, or the answer is
404 and nothing is created. A deleted team is accepted as a parent:
it isn’t shown among the new team’s parents, but listing the teams
under it, and grants given within it, include the new team.
A body that can’t be read as JSON, including a UUID string in
parent_ids that can’t be parsed, gets a plain-text 400 before
sign-in is checked. The team is saved before the response is put
together, so a plain-text 500 can arrive after it was created; check
before retrying. No audit entry is recorded.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
Surrounding spaces are removed, and it mustn’t then be empty. The maximum length shown isn’t checked, and no format is required. It must not be taken by another of this server’s teams, deleted ones included.
Surrounding spaces are removed, and it mustn’t then be empty. The maximum length shown isn’t checked.
Saved as sent, or empty when left out. The limit shown isn’t checked.
Teams to make the new team’s direct parents. Each must exist; a team listed twice is linked once.
Responses
Section titled “ Responses ”The new 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 completedConflict (slug taken, would create cycle, etc.)
object
Human-readable error summary
Example
the request could not be completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed