Skip to content

Add a parent to a team

POST
/teams/{id}/parents

Makes parent_id a direct parent of the team in the path. A team can have several parents.

You need to be signed in with teams.admin or system.admin granted globally; a grant within a team isn’t enough, and neither is being a member. A body that can’t be read as JSON, including a parent_id string that can’t be parsed, or an id that isn’t a UUID, gets a plain-text 400 before sign-in is checked.

Both teams must exist, but deleted ones are accepted; an id with no team gets 404 and nothing changes. A link that would make a team its own ancestor gets 409, and so does a team named as its own parent, even when no team has that id. Adding a link that already exists succeeds and changes nothing.

Grants given within the parent, or within any team above it, now also apply to this team and the teams below it. Membership doesn’t carry over: members of the parent don’t become members of this team. An account that’s already signed in may keep its earlier reach until the server reloads its permissions, which this request doesn’t do.

Parent changes are applied one at a time, so two requests that would together make a loop can’t both succeed. The team’s cached copy is cleared. Nobody is notified, and no audit entry is recorded. Server errors get a plain-text 500.

id
required
string format: uuid

The team’s id.

object
parent_id
required

The team to add as a parent.

string format: uuid

The link exists now, whether it was added or was already there.

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