Resource Group Endpoints
Endpoints are under /v1/resource-groups.
Base URL: https://api.gpcn.com/v1
Resource group IDs are UUIDs, not integers.
See the API Reference → for examples in TypeScript, Python, Go, and C#.
List Resource Groups
GET /resource-groups
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page |
integer | 1 |
Page number |
limit |
integer | 10 |
Items per page (max 100) |
sort |
string | createdAt:desc |
Sort field and direction (name, createdAt) |
search |
string | — | Search by name |
entityId |
UUID | — | Tenant to list from (for users with access to multiple tenants) |
Response meta includes unassignedUsers — users with no explicit membership, who still belong to the tenant's Default group — and unassignedVMs, which is always 0 now that every VM belongs to a group.
curl https://api.gpcn.com/v1/resource-groups \
-H "X-API-Key: gpcn_your_api_key_here"
Create Resource Group
POST /resource-groups
Request Body
{ "name": "Engineering", "description": "Engineering team resources" }
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | 1–64 characters after trimming; unique within the tenant |
description |
string | No | Up to 255 characters |
entityId |
UUID | No | Tenant to create in (defaults to yours) |
If your own standing could have granted it, you're added as a member of the new group holding the Tenant Operator role scoped to it, so you can deploy into it right away.
Response (201 Created)
{ "success": true, "message": "Resource created successfully", "data": { "resourceGroupId": "880e8400-e29b-41d4-a716-446655440001" } }
Error: 409 Conflict
A resource group with this name already exists in the tenant.
Get Resource Group Details
GET /resource-groups/{id}
Returns resource group info with a paginated member list. Supports page, limit, sort (firstName, lastName, email, createdAt), and search for members.
For the Default group, every live user of the tenant is a member implicitly, and members lists every one of them.
Update Resource Group
PUT /resource-groups/{id}
name is required on every call, even when you're only changing the description.
{ "name": "Platform Engineering", "description": "Updated description" }
Response (200 OK)
{ "success": true, "message": "", "data": { "updatedResourceGroupId": "880e8400-e29b-41d4-a716-446655440001" } }
Delete Resource Group
DELETE /resource-groups/{id}
Deletes an empty resource group. Deleting removes every explicit membership in the group and revokes every role assignment scoped to it.
Response (202 Accepted)
{ "success": true, "message": "Resource deleted successfully", "data": { "membershipsRemoved": 2, "roleAssignmentsRevoked": 1 } }
Error: 409 Conflict
Two different refusals share this status:
| Code | Meaning |
|---|---|
RESOURCE_GROUP_NOT_EMPTY |
The group still holds live resources. error.details counts them: virtualMachines, gpuVirtualMachines, volumes, vpcs, l2Segments (legacy L3 networks aren't counted). Move them to another group and retry. |
RESOURCE_GROUP_IS_DEFAULT |
The group is the tenant's Default, which can never be deleted. |
Add Member
POST /resource-groups/{id}/members
{ "userId": "user-uuid" }
Adding a user to the Default group succeeds and changes nothing — every live user is already an implicit member. Adding a user who's already an explicit member is also a no-op. Adding a user whose only membership was system-added (a migration or a creator twin) re-stamps it as this explicit grant.
Response (200 OK)
Remove Member
DELETE /resource-groups/{id}/members/{userId}
Any role assignment the user holds scoped to this group is revoked in the same call. Removing a user who isn't a member succeeds and changes nothing.
Response (202 Accepted)
Error: 409 Conflict
RESOURCE_GROUP_IS_DEFAULT — every live user is an implicit, unremovable member of the Default group.
Bulk Delete Resource Groups
POST /resource-groups/bulk/delete
{ "ids": ["880e8400-e29b-41d4-a716-446655440001", "880e8400-e29b-41d4-a716-446655440002"] }
1–50 IDs. Each deletion is attempted independently; partial success is possible.
Bulk Add Members
POST /resource-groups/bulk/add-members
{ "userIds": ["user-uuid-1", "user-uuid-2"], "resourceGroupIds": ["880e8400-e29b-41d4-a716-446655440001"] }
Creates every user–group combination. Each assignment is attempted independently; partial success is possible.
Next Steps
- Manage Resource Groups in the Portal → — create and manage resource groups from the dashboard
- User Endpoints → — manage users and role assignments via API
- Authentication → — API keys and permission scoping
.png)