--- title: "Update a team member's role" method: PATCH path: "/api/v1/teams/{team}/members/{user}" --- # Update a team member's role `PATCH /api/v1/teams/{team}/members/{user}` 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. ## Path parameters - `team` string, required - `user` string, required ## Request body - object - `role` string, required — New role to assign. One of `"owner"`, `"admin"`, or `"member"`. ## Response `200` Successful response - TeamMembership — A record representing a user's or agent's membership in a team, including their resolved identity details and role. - `agent` Agent — An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or tasks. - `acl` Acl — An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants. - `add` AclGrant[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`. - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry. - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `grants` AclGrant[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`. - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry. - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `remove` AclRemoveTarget[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`. - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`. - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`. - `app` string — ID of the application that owns this agent (`dap_...`). - `created_at` string, date-time — When the agent was created (ISO 8601). - `default_model` string — Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`). - `email` string — Email address provisioned for this agent. `null` if email delivery is not configured. - `id` string, required — Agent ID (`agi_...`). - `identity` string — System-level identity prompt that shapes the agent's persona and behavior. - `last_applied_template_config` string — ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents. - `lookup_key` string — Stable, user-defined identifier for this agent within the application. Unique per app. - `metadata` object — Arbitrary key-value metadata attached to the agent. Not interpreted by the platform. - `name` string — Human-readable display name for the agent. `null` if not set. - `org` string — ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped. - `org_name` string — Display name of the organization this agent belongs to. `null` when the agent is not org-scoped or when the org association was not preloaded. - `originator` string — Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name). - `phone_number` string — Phone number provisioned for this agent. `null` if SMS is not configured. - `sandbox` string — ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments. - `source_solution` AgentSourceSolution — Summary of the Solution and AgentTemplate that an agent was last provisioned from. Returned on single-agent responses; `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. - `solution` SolutionSummary, required — A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information. - `category_keys` string[] — Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none. - `created_at` string, date-time — When the Solution config was first imported (ISO 8601). - `description` string — Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one. - `id` string, required — Solution config ID (`cfg_...`). - `kind` string, required — Resource type. Always `"Solution"`. - `latest_solution` string — When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise. - `latest_version` string — When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise. - `lookup_key` string — The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set. - `metadata` object — Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none. - `name` string — Human-facing display name declared in the Solution body. `null` when the Solution body does not set one. - `org` string — Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions. - `org_logo` ImageSource — Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record. - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file. - `height` integer — Height of the image in pixels. `null` if not known. - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity. - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known. - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing. - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires. - `width` integer — Width of the image in pixels. `null` if not known. - `org_name` string — Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`. - `org_slug` string — Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key — clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve. - `owners` string[], required — Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer's org scope). - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`. - `solution_id` string — Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it. - `solution_version` string — Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version. - `tag_keys` string[] — Freeform tag keys declared in the Solution body. An empty array when the body declares none. - `template_kind` string — Wrapped template kind — `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles. - `templates` SolutionTemplateSummary[], required — Template configs bundled by this Solution, in declaration order — the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references. - `description` string — Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel. - `display_name` string — Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`. - `id` string — Template config ID (`cfg_...`). `null` for inline-only templates. - `kind` string, required — Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved. - `lookup_key` string — Lookup key stamped on the template config at import time. `null` when no lookup key was assigned. - `name` string — Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`. - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`. - `virtual_path` string — Stable virtual path assigned to the template config. `null` when no virtual path was set. - `updated_at` string, date-time — When the Solution config was last modified (ISO 8601). - `upgrade_available` boolean, required — `true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows. - `virtual_path` string — The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset. - `template` UpgradeTemplateSummary, required — Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response. - `created_at` string, date-time — When this template config was created (ISO 8601). - `description` string — Description of the template from the config body. `null` if the current version has no `description` field. - `display_name` string — Human-readable display name from the config body. `null` if the current version has no `display_name` field. - `id` string, required — Template config ID (`cfg_...`). - `kind` string, required — Config kind identifier for this template (e.g. `"agent_tool_template"`). - `lookup_key` string — Stable lookup key assigned to this template config. `null` if no lookup key is set. - `name` string — Template name as stored in the config body. `null` if the current version has no `name` field. - `updated_at` string, date-time — When this template config was last modified (ISO 8601). - `virtual_path` string — Virtual filesystem path for this template config. `null` if not set. - `team` string — ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped. - `updated_at` string, date-time — When the agent was last modified (ISO 8601). - `user` string — ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped. - `created_at` string, date-time — When this membership record was created (ISO 8601). - `id` string, required — Team membership ID (`tmb_...`). - `joined_at` string, date-time — When the principal joined the team (ISO 8601). - `metadata` object — Arbitrary key-value metadata attached to this membership record. `null` if no metadata has been set. - `name` string — Display name of the member, derived from the associated user or agent. `null` if the principal is unknown. - `profile_picture` ImageSource — Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record. - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file. - `height` integer — Height of the image in pixels. `null` if not known. - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity. - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known. - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing. - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires. - `width` integer — Width of the image in pixels. `null` if not known. - `role` string — The member's role within the team. One of `"owner"`, `"admin"`, or `"member"`. - `team` object — The team this membership belongs to, as an expanded team object. `null` when the team association is not preloaded. - `type` string — Resolved principal type. One of `"user"`, `"agent"`, or `"unknown"` when the principal cannot be determined. - `updated_at` string, date-time — When this membership record was last updated (ISO 8601). - `user` User — A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API. - `alias` string — Short handle or alias for the user. `null` if not set. - `app` string — ID of the app this user (and their access token) is scoped to (`dap_...`). `null` if the user is not scoped to an app. - `app_name` string — Display name of the user's app. `null` when the app association was not preloaded by the caller. - `email` string — Email address of the user. - `id` string, required — User ID (`usr_...`). - `is_system_user` boolean — `true` if this account is an internal system user rather than a human. System users are created automatically by the platform. - `metadata` object — Arbitrary key-value metadata attached to the user. Defaults to an empty object. - `name` string — Full display name of the user. `null` if the user has not set a name. - `org` string — ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization. - `org_name` string — Display name of the user's organization. `null` when the user is not in an org, or when the org association was not preloaded by the caller. - `org_role` string — Role of the user within their organization. One of `"admin"`, `"member"`, or `"viewer"`. `null` when the user is not a member of any organization. - `sandbox` string — ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users. - `sandbox_name` string — Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller. ## Other responses - `401` — Unauthorized - `403` — Forbidden — caller lacks permission to modify this team - `404` — Team or member not found - `409` — Conflict — cannot demote the last owner - `422` — Validation failed (e.g. invalid role) --- [API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)