v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Update a team member's role

Changes the role of an existing user member on the specified team. Returns the updated membership on success.

Only user memberships are supported by this endpoint. Attempting to update an agent membership returns 404. To change an agent's role, remove the existing membership and re-add the agent with the desired role.

The caller must have permission to modify the team. You cannot change a member's role across organization boundaries. Demoting the last owner of a team returns 409. An invalid role value returns 422. When app is provided, the request is scoped to that app and requires a valid app-scoped token.

patch/api/v1/teams/{team}/members/{user}

Path parameters

teamstring required

Team ID (team_...). The team whose member role you want to update.

userstring required

User ID (usr_...) of the existing member whose role should be changed.

Request body

rolestring required

New role to assign. One of "owner", "admin", or "member".

Example request

{
  "role": "string"
}

Response

Successful response

created_atstring date-time

When this membership record was created (ISO 8601).

idstring required

Team membership ID (tmb_...).

joined_atstring date-time

When the principal joined the team (ISO 8601).

metadataobject

Arbitrary key-value metadata attached to this membership record. null if no metadata has been set.

namestring

Display name of the member, derived from the associated user or agent. null if the principal is unknown.

rolestring

The member's role within the team. One of "owner", "admin", or "member".

teamobject

The team this membership belongs to, as an expanded team object. null when the team association is not preloaded.

typestring

Resolved principal type. One of "user", "agent", or "unknown" when the principal cannot be determined.

updated_atstring date-time

When this membership record was last updated (ISO 8601).

Example response

{
  "agent": {
    "acl": {
      "add": [
        {
          "actions": [
            "read",
            "write"
          ],
          "principal": "string",
          "principal_type": "user"
        }
      ],
      "grants": [
        {
          "actions": [
            "read",
            "write"
          ],
          "principal": "string",
          "principal_type": "user"
        }
      ],
      "remove": [
        {
          "principal": "string",
          "principal_type": "user"
        }
      ]
    },
    "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
    "created_at": "2024-01-01T00:00:00Z",
    "default_model": "claude-3-7-sonnet-latest",
    "email": "user@example.com",
    "id": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "identity": "You are a helpful assistant that answers questions about ArchAstro products.",
    "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
    "lookup_key": "string",
    "metadata": {
      "key": "value"
    },
    "name": "Example Name",
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "org_name": "Example Name",
    "originator": "deploy-pipeline",
    "phone_number": "+15555550123",
    "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
    "source_solution": {
      "solution": {
        "category_keys": [
          "string"
        ],
        "created_at": "2024-01-01T00:00:00Z",
        "description": "An example description.",
        "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
        "kind": "Solution",
        "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu",
        "latest_version": "1.0.0",
        "lookup_key": "string",
        "metadata": {
          "key": "value"
        },
        "name": "Example Name",
        "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
        "org_logo": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "org_name": "Example Name",
        "org_slug": "example-slug",
        "owners": [
          "string"
        ],
        "readme_url": "https://example.com",
        "solution_id": "01234567-89ab-cdef-0123-456789abcdef",
        "solution_version": "1.2.0",
        "tag_keys": [
          "string"
        ],
        "template_kind": "AgentTemplate",
        "templates": [
          {
            "description": "An example description.",
            "display_name": "Example Name",
            "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
            "kind": "AgentTemplate",
            "lookup_key": "string",
            "name": "Example Name",
            "readme_url": "https://example.com",
            "virtual_path": "string"
          }
        ],
        "updated_at": "2024-01-01T00:00:00Z",
        "upgrade_available": true,
        "virtual_path": "string"
      },
      "template": {
        "created_at": "2024-01-01T00:00:00Z",
        "description": "An example description.",
        "display_name": "Example Name",
        "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
        "kind": "agent_tool_template",
        "lookup_key": "string",
        "name": "Example Name",
        "updated_at": "2024-01-01T00:00:00Z",
        "virtual_path": "string"
      }
    },
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "updated_at": "2024-01-01T00:00:00Z",
    "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
  },
  "created_at": "2024-01-01T00:00:00Z",
  "id": "tmb_0aBcDeFgHiJkLmNoPqRsTu",
  "joined_at": "2024-01-01T00:00:00Z",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "profile_picture": {
    "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
    "height": 600,
    "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
    "mime_type": "application/json",
    "refresh_url": "https://example.com",
    "url": "https://example.com",
    "width": 800
  },
  "role": "member",
  "team": {},
  "type": "user",
  "updated_at": "2024-01-01T00:00:00Z",
  "user": {
    "alias": "jdoe",
    "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
    "app_name": "Example Name",
    "email": "user@example.com",
    "id": "usr_0aBcDeFgHiJkLmNoPqRsTu",
    "is_system_user": true,
    "metadata": {
      "key": "value"
    },
    "name": "Example Name",
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "org_name": "Example Name",
    "org_role": "member",
    "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
    "sandbox_name": "Example Name"
  }
}