Follow a team (bookmark it into your teams rail)

POST

/teams/{id}/follow

• Local development behind nginx (port 8088 by default)

Adds the caller to team_follows (#577). Requires teams.read — the same capability that lets you see the team at all.

A follow is a BOOKMARK, not a relationship

It grants nothing. It does not touch team_memberships, it is never read by any authorization rule, and following a studio does not widen one row of what you can see of its work — the visibility planes decide that and do not consult this table. All it does is put the team in your teams rail.

There is deliberately no unread model and no notification fanout behind it; a follow is a bookmark, not a subscription.

Idempotent

Following a team you already follow is a no-op 204, not a 409. The insert is ON CONFLICT DO NOTHING, so a double-tapped button and a retried request are the same request.

Refusals are indistinguishable

A nonexistent team and a soft-deleted team both answer 404 with the same body, because the FK cannot see teams.deleted_at and an explicit liveness probe therefore runs first. The two MUST stay indistinguishable: any difference between them turns this endpoint into a team-existence oracle over every studio on the instance, which is the discipline visibility.CanAssignToTeam carries for the same reason.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Responses

204

Followed (or already following)

401

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"
}

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed

500

Unexpected server error

object

error

required

Human-readable error summary

string

Example

the request could not be completed