update_team_member_role

Purpose

Moves an existing collaborator onto a different role. This is the only way to re-role someone without removing and re-inviting them — the dashboard's team settings page offers invite, remove and cancel-invitation only, so there is no UI equivalent.

The team owner cannot be re-roled: ownership is not a membership row and carries everything unconditionally.

Growth-tier capability. On a lower tier this returns TEAM_TIER_REQUIRED and changes nothing.

Required ability

team-member:update-role

Input schema

{
  "type": "object",
  "properties": {
    "team_id": { "type": "string", "description": "UUID of the team." },
    "user_id": {
      "type": "string",
      "description": "UUID of the collaborator whose role is changing."
    },
    "role": {
      "type": "string",
      "description": "Role code to move them onto. Must already exist on the team."
    }
  },
  "required": ["team_id", "user_id", "role"]
}

Output shape

{
  "data": {
    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
    "user_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "role": "manager"
  }
}

Emits team.member.role_changed.

This is what makes that event reachable

Nothing in Subscriby called the underlying re-role path before this shipped, so team.member.role_changed sat in the webhook catalog — and was offered as a Zapier and n8n trigger — while being impossible to fire.

Example prompts

"Promote Priya to manager on the Research team."

"Move everyone currently on the admin role down to manager except me."

Failure modes

AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks team-member:update-role.
TEAM_TIER_REQUIRED — the caller's platform tier does not include Teams.
RESOURCE_NOT_FOUND — no such team, or user_id is not a member of it. The owner also returns 404 here, because the owner has no membership row to change.
VALIDATION_FAILED — unknown role code.

invite_team_member
remove_team_member
list_roles — the codes you can move someone onto.
Team Members API