List teams
GET /teams
Returns teams in name order, a page at a time. With ancestor, it
returns that team and every team below it instead.
You need to be signed in with teams.read granted globally, which
the standard Base role includes; others get 403. Without a session
cookie or bearer token that identifies you, the answer is 401,
whether or not public mode is on. Membership doesn’t matter:
everyone who can use this sees every team that isn’t deleted.
A page holds 100 teams unless you set limit; values below 1 count
as 1 and values above 500 as 500. When more teams follow,
next_cursor is set; pass it back as cursor. Names are compared
the way the database sorts text, with ties broken by id. The list
isn’t a snapshot, so teams created, renamed or deleted while you
page can be skipped or appear twice, and there’s no total.
A cursor that can’t be read gets a 500 with invalid cursor. That
includes the cursor handed out when a page ends with a team whose
name contains |, so paging can’t get past that team.
With ancestor, you get that team (unless it’s deleted) and the
teams below it at any depth, up to limit, in name order. cursor
is ignored, next_cursor is never set, and teams past the limit are
left out. Teams below a deleted team are still found through it, and
an id that names no team gives an empty list.
Each team carries member_count and content_count but not
parents. A limit that isn’t a whole number, or an ancestor
that isn’t a UUID, gets a plain-text 400 before sign-in is checked;
other server errors get a plain-text 500.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”A team’s id. Returns that team and every team below it, and cursor is ignored.
How many teams to return. Values outside 1 to 500 are brought into that range.
The next_cursor from the previous page. Ignored with ancestor.
Responses
Section titled “ Responses ”A page of teams.
object
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.
Pass this back as cursor to get the next page. Left out on the last page and with ancestor.
Authentication 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 completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed