Skip to content

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.

object
slug
required

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.

string
>= 1 characters <= 80 characters
name
required

Surrounding spaces are removed, and it mustn’t then be empty. The maximum length shown isn’t checked.

string
>= 1 characters <= 200 characters
description

Saved as sent, or empty when left out. The limit shown isn’t checked.

string
<= 500 characters
parent_ids

Teams to make the new team’s direct parents. Each must exist; a team listed twice is linked once.

Array<string>

The new team, with its parents.

object
id
required
string format: uuid
slug
required

The team’s short name, unique among this server’s teams. A deleted team keeps its slug.

string
<= 80 characters
Example
aurora-rnd
name
required
string
<= 200 characters
Example
Aurora R&D
description
required
string
<= 500 characters
origin_server_id

The server a copied team came from. Left out for this server’s own teams; nothing in the API creates copies.

string format: uuid
nullable
hero_asset_id

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.

string format: uuid
nullable
parents

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.

Array<object>
object
parent_id
required
string format: uuid
parent_slug
string
parent_name
string
member_count

How many direct memberships the team has; members of teams below it aren’t counted. Only listTeams sends it.

integer format: int64
content_count

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.

integer format: int64
created_at
required
string format: date-time
updated_at
required
string format: date-time

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

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

Conflict (slug taken, would create cycle, etc.)

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed