sharegroups

Creates, updates, deletes, gets or lists a sharegroups resource.

Overview

Name	sharegroups
Type	Resource
Id	linode.images.sharegroups

Fields

The following fields are returned by SELECT queries:

get_by_token

A single share group object.

Name	Datatype	Description
id	integer	Read-only The share group's numeric identifier, used primarily as path parameters in URLs.
created	string (date-time)	Read-only When this share group was created. (example: 2025-04-14T22:44:02)
description	string	A detailed description of this share group. (example: Group of base operating system images and engineers used for CI/CD pipelines and infrastructure automation)
is_suspended	boolean	Read-only If true, the share group is currently suspended.
label	string	The share group's descriptive name. (example: DevOps Base Images)
updated	string (date-time)	Read-only When this share group was last updated.
uuid	string (uuid)	Read-only The share group's unique identifier used for membership token management. (example: 1533863e-16a4-47b5-b829-ac0f35c13278)

get

A single share group object.

Name	Datatype	Description
id	integer	Read-only The share group's numeric identifier, used primarily as path parameters in URLs.
created	string (date-time)	Read-only When this share group was created. (example: 2025-04-14T22:44:02)
description	string	A detailed description of this share group. (example: Group of base operating system images and engineers used for CI/CD pipelines and infrastructure automation)
expiry	string (date-time)	Read-only When the share group expires.
images_count	integer	Read-only The total number of images currently belonging to the share group.
is_suspended	boolean	Read-only If true, the share group is currently suspended.
label	string	The share group's descriptive name. (example: DevOps Base Images)
members_count	integer	Read-only The number of users with access to the share group.
updated	string (date-time)	Read-only When this share group was last updated.
uuid	string (uuid)	Read-only The share group's unique identifier used for membership token management. (example: 1533863e-16a4-47b5-b829-ac0f35c13278)

list_by_image

Returns a paginated list of share groups.

Name	Datatype	Description
id	integer	The share group's numeric identifier, used primarily as path parameters in URLs.
created	string (date-time)	Read-only When this share group was created. (example: 2025-04-14T22:44:02)
description	string	The share group's detailed description. (example: Group of base operating system images and engineers used for CI/CD pipelines and infrastructure automation)
expiry	string (date-time)	Read-only When the share group expires.
images_count	integer	Read-only The total number of images currently belonging to the share group.
is_suspended	boolean	Read-only Indicates whether the share group is currently suspended.
label	string	Filterable The share group's descriptive name. (example: DevOps Base Images)
members_count	integer	Read-only The number of users with access to the share group.
updated	string (date-time)	Read-only When this share group was last updated.
uuid	string (uuid)	The share group's unique identifier used for membership token management. (example: 1533863e-16a4-47b5-b829-ac0f35c13278)

list

A paginated list of sharegroups.

Name	Datatype	Description
id	integer	The share group's numeric identifier, used primarily as path parameters in URLs.
created	string (date-time)	Read-only When this share group was created. (example: 2025-04-14T22:44:02)
description	string	The share group's detailed description. (example: Group of base operating system images and engineers used for CI/CD pipelines and infrastructure automation)
expiry	string (date-time)	Read-only When the share group expires.
images_count	integer	Read-only The total number of images currently belonging to the share group.
is_suspended	boolean	Read-only Indicates whether the share group is currently suspended.
label	string	Filterable The share group's descriptive name. (example: DevOps Base Images)
members_count	integer	Read-only The number of users with access to the share group.
updated	string (date-time)	Read-only When this share group was last updated.
uuid	string (uuid)	The share group's unique identifier used for membership token management. (example: 1533863e-16a4-47b5-b829-ac0f35c13278)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_by_token	select	tokenUuid		Gets details about a share group you're a member of. To get the token_uuid, run the Get a token or Create a token for the share group you want to join and share it with the group owner. You have to be accepted as a share group member before running this operation. Learn more... Learn more...
get	select	sharegroupId		Get information about an owned share group. Run the List share groups operation to get the id you should use as the (sharegroupId) path parameter that identifies an existing share group. - If the sharegroupId in the request body belongs to a group you don't own, calling this API will result in a 404 error. Learn more... Learn more...
list_by_image	select	imageId		Lists all owned share groups where a given private image is currently shared. Run the List images operation. Store the id for the target image as your {imageId}, for use in this operation's URL path. > 📘 > > This operation returns an empty list for shared and distribution image IDs. Learn more... Learn more...
list	select		page, page_size	Lists all owned groups with shared images. > 📘 > > This operation doesn't list groups you're a member of. Run Get a token's share group to find these share groups using your membership token. Learn more... Learn more...
create	insert	label		Creates a group to share images with other users. - Include existing images in the request or Add images to a share group later. Run the Get an image operation to see the existing images' id values. If needed, Create an image or Upload an image. - You can set a label and description for the group and each image, visible to all group members. - If omitted, the shared image keeps the original label and description. Note that when you Update the original image, it has no effect on shared image's details within any groups. - Run the Add members to a share group to include other users in the group. Use the group's uuid from the response to Create a token for user authentication. Learn more... Learn more...
update	replace	sharegroupId		Updates the details of a share group you own. Run this operation to edit the label or description of a particular sharegroup. - Run the List share groups operation to get the id you should use as the (sharegroupId) path parameter that identifies an existing share group. - You can update either of the fields, but when you provide a new label, make sure that it's not an empty string. Learn more... Learn more...
delete	delete	sharegroupId		Deletes an owned share group. All shared group members lose access to the images within the group upon deletion. - Run the List share groups operation to get the id you should use as the (sharegroupId) path parameter that identifies an existing share group. Learn more... Learn more...

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
imageId	string	Slug identifier assigned to the private image upon creation. This identifier includes a slash (/), which must be URL-encoded in requests to prevent breaking the URL structure.
sharegroupId	string	The share group's unique identifier assigned after creating it. Not to be confused with the group's uuid.
tokenUuid	string (uuid)	A unique identifier for the token, used to reference it after creation.
page	integer	The page of a collection to return.
page_size	integer	The number of items to return per page.

SELECT examples

get_by_token

Gets details about a share group you're a member of.

To get the token_uuid, run the Get a token or Create a token for the share group you want to join and share it with the group owner. You have to be accepted as a share group member before running this operation.

Learn more...

Learn more...

SELECT
id,
created,
description,
is_suspended,
label,
updated,
uuid
FROM linode.images.sharegroups
WHERE tokenUuid = '{{ tokenUuid }}' -- required
;

get

Get information about an owned share group. Run the List share groups operation to get the id you should use as the (sharegroupId) path parameter that identifies an existing share group.

- If the sharegroupId in the request body belongs to a group you don't own, calling this API will result in a 404 error.

Learn more...

Learn more...

SELECT
id,
created,
description,
expiry,
images_count,
is_suspended,
label,
members_count,
updated,
uuid
FROM linode.images.sharegroups
WHERE sharegroupId = '{{ sharegroupId }}' -- required
;

list_by_image

Lists all owned share groups where a given private image is currently shared. Run the List images operation. Store the id for the target image as your {imageId}, for use in this operation's URL path.

> 📘
>
> This operation returns an empty list for shared and distribution image IDs.

Learn more...

Learn more...

SELECT
id,
created,
description,
expiry,
images_count,
is_suspended,
label,
members_count,
updated,
uuid
FROM linode.images.sharegroups
WHERE imageId = '{{ imageId }}' -- required
;

list

Lists all owned groups with shared images.

> 📘
>
> This operation doesn't list groups you're a member of. Run Get a token's share group to find these share groups using your membership token.

Learn more...

Learn more...

SELECT
id,
created,
description,
expiry,
images_count,
is_suspended,
label,
members_count,
updated,
uuid
FROM linode.images.sharegroups
WHERE page = '{{ page }}'
AND page_size = '{{ page_size }}'
;

INSERT examples

create

Creates a group to share images with other users.

- Include existing images in the request or Add images to a share group later. Run the Get an image operation to see the existing images' id values. If needed, Create an image or Upload an image.

- You can set a label and description for the group and each image, visible to all group members.

- If omitted, the shared image keeps the original label and description. Note that when you Update the original image, it has no effect on shared image's details within any groups.

- Run the Add members to a share group to include other users in the group. Use the group's uuid from the response to Create a token for user authentication.

Learn more...

Learn more...

INSERT INTO linode.images.sharegroups (
description,
images,
label
)
SELECT 
'{{ description }}',
'{{ images }}',
'{{ label }}' /* required */
RETURNING
id,
created,
description,
expiry,
images_count,
is_suspended,
label,
members_count,
updated,
uuid
;

Manifest

# Description fields are for documentation purposes
- name: sharegroups
props:
  - name: description
    value: "{{ description }}"
    description: |
      A detailed description of this share group.
  - name: images
    description: |
      A list of image's details, including the ID, label, and description.
    value:
      - description: "{{ description }}"
        id: "{{ id }}"
        label: "{{ label }}"
  - name: label
    value: "{{ label }}"
    description: |
      The share group's descriptive name.

REPLACE examples

update

Updates the details of a share group you own. Run this operation to edit the label or description of a particular sharegroup.

- Run the List share groups operation to get the id you should use as the (sharegroupId) path parameter that identifies an existing share group.

- You can update either of the fields, but when you provide a new label, make sure that it's not an empty string.

Learn more...

Learn more...

REPLACE linode.images.sharegroups
SET 
description = '{{ description }}',
label = '{{ label }}'
WHERE 
sharegroupId = '{{ sharegroupId }}' --required
RETURNING
id,
created,
description,
expiry,
images_count,
is_suspended,
label,
members_count,
updated,
uuid;

DELETE examples

delete

Deletes an owned share group. All shared group members lose access to the images within the group upon deletion.

- Run the List share groups operation to get the id you should use as the (sharegroupId) path parameter that identifies an existing share group.

Learn more...

Learn more...

DELETE FROM linode.images.sharegroups
WHERE sharegroupId = '{{ sharegroupId }}' --required
;