Operation details
GET /v1/admin/package-groups
List package catalog groups
- operationId
listPackageGroups- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. Unknown or repeated query parameters are rejected.
Responses
listPackageGroups Responses| Status | Description |
|---|
200 | All active groups ordered by sort order and then name. Fields：items: array<PackageGroup> total: integer(int64) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/admin/package-groups
Create a package catalog group
- operationId
createPackageGroup- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. The same idempotency key and normalized input replay the original response; a changed input returns idempotency_conflict, and a duplicate active name returns package_name_conflict.
Parameters
createPackageGroup Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createPackageGroup Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
visible | boolean | Yes | Whether the group is shown in package selection surfaces. |
|---|
sort_order | integer | Yes | — |
|---|
Responses
createPackageGroup Responses| Status | Description |
|---|
201 | Group created, or an identical idempotent request replayed. Fields：id: string(uuid) owner_scope_id: string(uuid) name: string visible: boolean sort_order: integer revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
PATCH /v1/admin/package-groups/{id}
Replace package group fields using optimistic concurrency
- operationId
updatePackageGroup- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. expected_revision is checked atomically; stale input returns version_conflict. An identical idempotent request replays the original response.
Parameters
updatePackageGroup Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | Package group or package product UUID. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
updatePackageGroup Request body| Name | Type | Required | Description |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
name | string | Yes | — |
|---|
visible | boolean | Yes | Whether the group is shown in package selection surfaces. |
|---|
sort_order | integer | Yes | — |
|---|
Responses
updatePackageGroup Responses| Status | Description |
|---|
200 | Group fields replaced and revision incremented, or an identical request replayed. Fields：id: string(uuid) owner_scope_id: string(uuid) name: string visible: boolean sort_order: integer revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
DELETE /v1/admin/package-groups/{id}
Soft-delete an unused package group
- operationId
deletePackageGroup- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. If-Match supplies the expected revision. A group referenced by an active package returns package_group_in_use; a stale revision returns version_conflict.
Parameters
deletePackageGroup Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | Package group or package product UUID. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Responses
deletePackageGroup Responses| Status | Description |
|---|
204 | Group soft-deleted, or an identical idempotent request replayed. |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list