Group APIs - Qoder

Use Group APIs to organize members for functional access management. A member can belong to multiple groups. Group membership does not change the member's role, seat, usage limit, billing group, or Credits attribution.

Applicable plans: Enterprise. The organization must have the Groups capability enabled.

Complete Get API Key and review OpenAPI Conventions before calling these endpoints.

Requirements

Send Authorization: Bearer <api_key>.
Send Content-Type: application/json for requests with a JSON body.
Use the organization bound to the API key as organization_id.
Use user IDs, not organization member IDs, in userIds request fields. Obtain them from the userId field returned by Member APIs.

Group types

Use source to determine whether a group is writable. Groups with source: "manual" are managed through Qoder and can be updated, deleted, and have their members changed through these APIs. Every other source is read-only through OpenAPI and returns isManaged: true; for example, a SCIM group returns source: "scim". Manage read-only groups in their source system.

Data models

Group

Field	Type	Description
`id`	string	Group ID
`organizationId`	string	Organization ID
`displayName`	string	Group name
`description`	string	Description; omitted when empty
`source`	string	Group source, such as `manual` or `scim`
`externalId`	string	ID in the source system; omitted when empty
`syncType`	string	Synchronization type, such as `scim`; omitted when empty
`isManaged`	boolean	Whether membership is managed by an external source
`creatorId`	string	Creator user ID; omitted when unavailable
`createdAt`	string	Creation time in ISO 8601 format; omitted when unavailable
`updatedAt`	string	Last update time in ISO 8601 format; omitted when unavailable
`memberCount`	integer	Current number of group members

Group member

Field	Type	Description
`id`	string	Organization member ID
`userId`	string	User ID; use this value when adding or removing group members
`name`	string	Member name
`email`	string	Member email; omitted when unavailable
`status`	string	Organization member status, such as `ENABLED` or `DISABLED`
`joinedAt`	string	Time the user joined the organization; omitted when unavailable
`usageLimit`	object	Current member usage limit; omitted when unavailable
`usageLimit.quotaKey`	string	Quota identifier
`usageLimit.limitValue`	number	Limit amount; `-1` means unlimited
`usageLimit.usedValue`	number	Amount used in the current period
`usageLimit.resetCycle`	string	Reset cycle; omitted when unavailable
`usageLimit.isActive`	boolean	Whether the limit is active
`usageLimit.lastResetAt`	string	Last reset time; omitted when unavailable
`usageLimit.nextResetAt`	string	Next reset time; omitted when unavailable

The group member object intentionally does not include the member role or billing group. Use Member APIs when those fields are needed.

API reference

List groups

GET /v1/organizations/{organization_id}/groups

Query parameter	Type	Required	Description
`source`	string	No	Exact source filter, such as `manual` or `scim`
`externalId`	string	No	Exact external group ID filter
`syncType`	string	No	Exact synchronization type filter
`userId`	string	No	Return only groups containing this user UUID
`keyword`	string	No	Case-insensitive match against group name or description
`maxResults`	integer	No	Page size; default 20, max 100
`nextToken`	string	No	Cursor returned by the previous response

Success response (200 OK)

{
  "groups": [
    {
      "id": "1c8f3ee2-b970-4b61-93f9-f8be080ae945",
      "organizationId": "org_xxx",
      "displayName": "Platform Team",
      "description": "Platform maintainers",
      "source": "manual",
      "isManaged": false,
      "creatorId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-08-01T08:00:00Z",
      "updatedAt": "2026-08-01T08:00:00Z",
      "memberCount": 2
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response"
}

nextToken is omitted on the last page.

Create a group

POST /v1/organizations/{organization_id}/groups Creates a manually managed group. displayName is trimmed and must not be empty. Group names must not conflict with an existing active manual group. Omit userIds or send an empty array to create a group without members. Duplicate user IDs are de-duplicated. If any ID is invalid or is not a current organization member, the request fails and the group is not created.

Request body

{
  "displayName": "Platform Team",
  "description": "Platform maintainers",
  "userIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

Field	Type	Required	Description
`displayName`	string	Yes	Group name
`description`	string	No	Group description
`userIds`	array of strings	No	User UUIDs to add when creating the group

Returns the created Group with 201 Created.

Get a group

GET /v1/organizations/{organization_id}/groups/{group_id} Returns the requested Group with 200 OK.

Update a group

PUT /v1/organizations/{organization_id}/groups/{group_id} Only manually managed groups can be updated. Omitted fields remain unchanged. Send an empty description to clear the description.

Request body

{
  "displayName": "Platform Engineering",
  "description": ""
}

Field	Type	Required	Description
`displayName`	string	No	New group name; must not be empty after trimming
`description`	string	No	New description; an empty string clears it

Returns the updated Group with 200 OK.

Delete a group

DELETE /v1/organizations/{organization_id}/groups/{group_id} Only manually managed groups can be deleted. Deleting a group removes its membership relationships and any access policies attached to the group. It does not delete organization members or change their billing groups, individual usage limits, or historical usage. Returns 200 OK:

{}

List group members

GET /v1/organizations/{organization_id}/groups/{group_id}/members

Query parameter	Type	Required	Description
`keyword`	string	No	Case-insensitive match against member name or email
`maxResults`	integer	No	Page size; default 20, max 100
`nextToken`	string	No	Cursor returned by the previous response

Success response (200 OK)

{
  "members": [
    {
      "id": "member_abc123",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Alice",
      "email": "alice@example.com",
      "status": "ENABLED",
      "joinedAt": "2026-06-01T08:00:00Z",
      "usageLimit": {
        "quotaKey": "big_model_credits",
        "limitValue": 5000,
        "usedValue": 1250,
        "resetCycle": "monthly",
        "isActive": true
      }
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response"
}

nextToken is omitted on the last page.

Add group members

POST /v1/organizations/{organization_id}/groups/{group_id}/members Adds one or more organization users to a manually managed group. Existing memberships are not duplicated.

Request body

{
  "userIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

userIds is required and must contain at least one non-empty user ID. Duplicate and already-added user IDs do not create duplicate memberships. All IDs are validated before membership changes; if any ID is malformed or is not a current organization member, the request fails with 400 BadRequest and no memberships are added. The 200 OK response contains up to the first 20 current group members and does not include pagination fields; use List group members to retrieve the complete list.

{
  "members": [
    {
      "id": "member_abc123",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Alice",
      "email": "alice@example.com",
      "status": "ENABLED",
      "joinedAt": "2026-06-01T08:00:00Z"
    }
  ]
}

Remove group members

DELETE /v1/organizations/{organization_id}/groups/{group_id}/members Removes one or more membership relationships from a manually managed group. It does not delete the users from the organization.

Request body

{
  "userIds": [
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

userIds is required and must contain at least one non-empty user ID. This endpoint uses a JSON body with DELETE; ensure that your HTTP client and proxy preserve the body. If any ID is malformed, the request fails with 400 BadRequest and no memberships are removed. A valid user ID that is not an organization member or is not in the group has no effect; other matching memberships in the same request are still removed. Returns 200 OK:

{}

Errors

Errors use the standard response shape described in OpenAPI Conventions.

HTTP status	Error code	Typical cause
400	`BadRequest`	Malformed request, invalid ID or cursor, or empty required field
400	`OrganizationGroupSCIMReadOnly`	Attempt to change a synchronized or externally managed group
401	`Unauthorized`	API key is missing or invalid
403	`Forbidden`	API key does not belong to the target organization
403	`OrganizationPlanCapabilityForbidden`	The organization does not have the Groups capability
404	`NotFound`	Group or member does not exist
409	`AlreadyExists`	An active manual group with the same name already exists

​Requirements

​Group types

​Data models

​Group

​Group member

​API reference

​List groups

​Success response (200 OK)

​Create a group

​Request body

​Get a group

​Update a group

​Request body

​Delete a group

​List group members

​Success response (200 OK)

​Add group members

​Request body

​Remove group members

​Request body

​Errors

Requirements

Group types

Data models

Group

Group member

API reference

List groups

Success response (200 OK)

Create a group

Request body

Get a group

Update a group

Request body

Delete a group

List group members

Success response (200 OK)

Add group members

Request body

Remove group members

Request body

Errors