PUT

Replace a group's members

/v1/groups/{group}/members in the Groups API.

curl -X PUT https://api.example.test/v1/groups/$GROUP_ID/members \  -H "Authorization: Bearer $TOKEN" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{"user_ids": ["2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80", "4b8e2f6a-1c3d-4e5f-9a7b-8c9d0e1f2a3b"]}'

This is a sync, not an add. The array replaces the membership entirely: anyone omitted is removed, and [] empties the group. That is deliberate and differs from the permission field above: clearing a group is a legitimate thing to ask for, whereas silently stripping every permission because a field was blank is not.

Every id must already belong to the group's team. A group grants permissions inside one tenant, so an outsider is refused naming the offending ids; the whole call fails rather than partly applying, so you never end up with a membership you did not ask for.

Answers 200 with the group, its permissions and its member_ids.

Requires ability

The token must hold this ability, or the call is refused with 403.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted in the app under Account Settings, then API Tokens, sent as Authorization: Bearer zg_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team, and optionally to one project, at mint time.

In: header

Path Parameters

group*string

The group, resolved by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Formatuuid

Request body

JSONWhat the request carriesRequiredapplication/json

The group's complete membership after the call. A sync, not an add: anyone omitted is removed, and [] empties the group.

Responses

200OKapplication/json

The group with its permissions and members as they now stand.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (a zg_test_ token on production).

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who registered a row answers FORBIDDEN with the same status, and says so in its own description.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

422Validation failedVALIDATION_FAILEDapplication/json

The payload broke a rule, and error.fields maps each offending key to its messages. A refusal from the domain, such as a role code already taken or a team the caller does not own, uses the same code with error.message saying why and no fields. On this endpoint: VALIDATION_FAILED: when any id is not a member of the group's team; error.message lists the outsiders.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X PUT "https://example.com/v1/groups/497f6eca-6276-4993-bfeb-53cbbbba6f08/members" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12" \  -H "Content-Type: application/json" \  -d '{    "user_ids": [      "2d98503d-4ab4-41bd-8fc6-78cc006fd2db"    ]  }'

{  "data": {    "id": "1f68d92a-04c5-4e83-97b1-3d6a05e2f847",    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",    "code": "incident-commanders",    "name": "Incident Commanders",    "permissions": [      "incident:command"    ],    "member_ids": [      "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80"    ]  }}

Type definitions

The shapes above as types, ready to paste into your client.

Request

export interface SyncGroupMembersRequest {  user_ids: string[];}

Response

export interface Response {  data: Data;}export interface Data {  id: string;  team_id: string;  code: string;  name: string;  permissions: string[];  member_ids: string[];}

How is this guide?

Last updated on October 29, 2026 at 13:13 UTC

Delete a group

/v1/groups/{group} in the Groups API.

Imports API

A brief import hands a client's brief to Heimdall and gets back suggestions: the epics, stories, requirements, business rules, use cases, glossary terms, personas, stakeholders, risks, assumptions and decisions a good analyst would draft from it, each with how sure Heimdall was, why, and the passage of the brief it drew on, plus improvements, the gaps and questions a project of this kind leaves open.