Groups

Create a group

curl -X POST https://api.subscriby.net/v1/groups \
  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
        "code": "billing-team",
        "name": "Billing Team",
        "permissions": ["project-subscription:view-any"]
      }'

Choose the code deliberately. code is unique within the team and cannot be changed afterwards: permissions are addressed by it. Only name and the permission set are mutable.

A group starts empty. Add people with the members endpoint; membership is deliberately not a field here, because replacing who is in a group and naming it are different operations with different consequences.

Answers 201 with the group and its permissions. Emits group.created.

post/v1/groups

Request

  • Base URL: https://api.subscriby.net
  • URL: https://api.subscriby.net/v1/groups
  • Auth: HTTP bearer

Headers

Idempotency-Keystring uuid required

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.

Request body

team_idstring uuid required

The team to create the group in; the caller must belong to it, and a team outside their account answers 404. Prohibited on update: a group cannot be moved between teams.

codestring required

The machine name, up to 255 letters, numbers, dashes and underscores, unique within the team and immutable afterwards because permissions are addressed by it. Prohibited on update.

namestring required

The display name, up to 255 characters.

permissionsstring[]

The permission codes the group grants. Sending it sets the group's permissions to exactly this list; omit the key to leave the existing set untouched. Defaults to none on create.

Response

The group resource as a 201.

Example response

{
  "data": {
    "id": "1f68d92a-04c5-4e83-97b1-3d6a05e2f847",
    "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
    "code": "ops",
    "name": "Ops",
    "permissions": [
      "project:view-any"
    ],
    "member_ids": [
      "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80"
    ],
    "created_at": "2026-05-18T10:05:00Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.