---
title: "Update a team"
method: PATCH
path: "/api/v1/teams/{team}"
---

# Update a team

`PATCH /api/v1/teams/{team}`

Updates one or more attributes of the team identified by `team`. Only the
fields you provide are changed; omitted fields are left as-is.

To replace the team's profile picture, supply the `profile_picture` object
with base64-encoded image data. The previous picture is deleted after the
new one is successfully uploaded. When `app` is present, the caller must hold
the corresponding app scope. The caller must be a team owner or org admin.

## Path parameters

- `team` string, required

## Request body

- object
  - `acl` object — New access control configuration for the team. Replaces the existing ACL.
    - `add` object[] — 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` object[] — 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` object[] — 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"`.
  - `description` string — New human-readable description of the team's purpose.
  - `metadata` object — Arbitrary key-value pairs to set on the team. Replaces the existing metadata map entirely.
  - `name` string — New display name for the team.
  - `profile_picture` object — New profile picture for the team. Provide this object to upload and replace the current picture.
    - `data` string — Base64-encoded binary image data.
    - `filename` string — Original filename of the image, used for storage metadata.
    - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.

## Response `200`

Successful response

- Team — A team within an organization, used to group users and agents and scope resources like configs, agents, and 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 developer application this team belongs to (`dap_...`). `null` if the team is not scoped to an app.
  - `badges` object — Aggregated badge counts for the team, keyed by category. `null` when badge data is not loaded.
  - `created_at` string, date-time — When this team was created (ISO 8601).
  - `description` string — Human-readable description of the team's purpose. `null` if not set.
  - `id` string, required — Team ID (`tem_...`).
  - `membership_status` string — The authenticated viewer's role on this team. One of `"owner"`, `"admin"`, or `"member"`. `null` if the viewer is not a member.
  - `metadata` object — Arbitrary key-value metadata attached to this team. Returns an empty object when no metadata has been set.
  - `name` string — Display name of the team.
  - `org` string — ID of the organization this team belongs to (`org_...`). `null` if the team is not org-scoped.
  - `sandbox` string — ID of the developer sandbox this team is scoped to (`dsb_...`). `null` outside sandbox contexts.
  - `slug` string — URL-safe slug for the team, derived from the team name. `null` if not set.
  - `updated_at` string, date-time — When this team was last updated (ISO 8601).

## Other responses

- `401` — Unauthorized
- `403` — Forbidden - app scope required
- `404` — Team not found
- `422` — Validation failed

---

[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)