User Groups

User groups bundle organization members so resources can be shared with a group instead of user-by-user. These endpoints manage groups and their membership; resources are then shared with a group via the shared_groups field on the share endpoint.

Group names are unique per organization.

Permission

Reads are available to any org member. Writes require an org admin — or a platform API key, whose service account is treated as an admin for group management. DELETE calls additionally require a key with the full_access permission level (read_write keys cannot issue DELETE).

---

Groups

Create, list, update, and delete user groups.

GET/api/v1/unstract/{org_id}/groups/

List all user groups in the organization.▾

POST/api/v1/unstract/{org_id}/groups/

Create a user group. Returns 201 on success. The response echoes only name and description — re-list the groups to obtain the new group's id (names are unique per org, so a name match is unambiguous).▾

PATCH/api/v1/unstract/{org_id}/groups/{id}/

Partially update a group's name or description.▾

DELETE/api/v1/unstract/{org_id}/groups/{id}/

Delete a group. Removes the group and every resource share that references it. Members are only detached — their user accounts are not deleted. Returns 204 No Content on success.▾

---

Group Membership

List, add, and remove members of a group.

GET/api/v1/unstract/{org_id}/groups/{id}/members/

List the members of a group.▾

POST/api/v1/unstract/{org_id}/groups/{id}/members/

Add organization members to a group in bulk. Users who are already members are filtered out server-side, so re-sending the same list is idempotent.▾

DELETE/api/v1/unstract/{org_id}/groups/{id}/members/{user_id}

Remove a member from a group. Returns 204 No Content on success.▾

---

Resources Shared with a Group

Inspect which resources a group currently has access to.

GET/api/v1/unstract/{org_id}/groups/{id}/resources/

List the resources currently shared with the group, across all shareable resource types.▾

---

Resolving user IDs

Membership requests take numeric user IDs. Resolve a user's email to their ID via GET /users/:

{
  "message": "success",
  "members": [
    { "id": "2", "email": "alice@example.com", "role": "unstract_admin", "is_admin": true, "is_service_account": false }
  ]
}

The id is a numeric value returned as a string — cast it to an integer before sending it in user_ids. Internal service accounts are excluded from this listing.

Sharing resources with groups

Every shareable resource — adapters, connectors, workflows, pipelines, API deployments, and Prompt Studio projects — exposes a share endpoint:

POST /api/v1/unstract/{org_id}/{resource}/{id}/share/

The body may contain any subset of the three share axes:

{
  "shared_users": [2, 5],
  "shared_groups": [1],
  "shared_to_org": false
}

Each provided axis is applied replace-style (the new list fully replaces the old one for that axis); omitted axes are left untouched. shared_groups takes the group IDs returned by GET /groups/.

Typical post-clone automation

After cloning an organization, groups exist on the target but (by default) have no members. A typical follow-up script: list the target's groups via GET /groups/, map each intended member's email to a target user ID via GET /users/, then POST /groups/{id}/members/ with the resolved user_ids.