Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

This page covers the /api/v1/images/ endpoints for browsing public computer images, reviewing imported and purchased images, retrieving image icons, importing free images, purchasing paid images, and rating images. Use these operations when selecting a base image, managing an image library, or recording an image rating.

Get a paginated list of public computer images with optional filtering and sorting.

NameInTypeRequiredDescription
osquerystringNoFilter by operating system, for example debian. The platform currently carries debian/13 only.
architecturequerystringNoFilter by CPU architecture, for example amd64, arm64, or armhf.
min_pricequerynumberNoMinimum price filter for paid images. A value of 0 includes free images.
max_pricequerynumberNoMaximum price filter for paid images.
min_ratingquerynumberNoMinimum average rating filter. Accepts a value from 0 to 5.
max_ratingquerynumberNoMaximum average rating filter. Accepts a value from 0 to 5.
searchquerystringNoSearch term matched as a substring against the image alias, image name, and description.
pagequeryintegerNoPage number for pagination. Starts from 1. Default: 1.
limitqueryintegerNoNumber of images to return per page. Maximum: 100. Default: 20.
sort_byquerystringNoSort field. Allowed values: alias, added_date, price, rating.
sort_orderquerystringNoSort direction. Allowed values: asc, desc.
Terminal window
curl --request GET \
--url 'https://api.hoody.com/api/v1/images/public?os=debian&architecture=amd64&page=1&limit=20&sort_by=alias&sort_order=asc' \
--header 'Accept: application/json'

Returns one page of public computer images and pagination details.

Media type: application/json

{
"statusCode": 200,
"message": "Public computer images retrieved successfully",
"data": {
"images": [
{
"id": "507f1f77bcf86cd799439021",
"alias": "debian/13",
"description": "Debian 13 (Trixie) - Default base image",
"image_name": "debian/13",
"architecture": "amd64",
"os": "debian",
"release": "13",
"variant": "default",
"size": 512000000,
"price": 0,
"added_date": "2025-01-10T08:00:00.000Z",
"average_rating": 4.5,
"rating_count": 142,
"icon_url": "/api/v1/images/507f1f77bcf86cd799439021/icon"
}
],
"pagination": {
"total": 87,
"page": 1,
"limit": 20,
"totalPages": 5
}
}
}
FieldTypeRequiredDescription
statusCodenumberNo-
messagestringNo-
dataobjectNo-
data.imagesarrayNo-
data.images[].idstringYes-
data.images[].aliasstringNo-
data.images[].descriptionstringNo-
data.images[].image_namestringNo-
data.images[].architecturestringNo-
data.images[].osstringNo-
data.images[].releasestringNo-
data.images[].variantstring or nullNo-
data.images[].sizenumberNo-
data.images[].pricenumberNo-
data.images[].added_datestringNo-
data.images[].average_ratingnumberNo-
data.images[].rating_countnumberNo-
data.images[].icon_urlstring or nullNo-
data.paginationobjectNo-
data.pagination.totalnumberNo-
data.pagination.pagenumberNo-
data.pagination.limitnumberNo-
data.pagination.totalPagesnumberNo-

Get details for a specific public computer image.

NameInTypeRequiredDescription
idpathstringYesUnique identifier of the public computer image to retrieve details for.
Terminal window
curl --request GET \
--url 'https://api.hoody.com/api/v1/images/public/67e89abc123def456789abcd' \
--header 'Accept: application/json'

Returns the public computer image details.

Media type: application/json

{
"statusCode": 200,
"message": "Computer image details retrieved successfully",
"data": {
"id": "507f1f77bcf86cd799439021",
"alias": "debian/13",
"description": "Debian 13 (Trixie) - Default base image",
"image_name": "debian/13",
"architecture": "amd64",
"os": "debian",
"release": "13",
"serial": "20250110",
"variant": "default",
"size": 512000000,
"price": 0,
"added_date": "2025-01-10T08:00:00.000Z",
"average_rating": 4.5,
"rating_count": 142,
"icon_url": "/api/v1/images/507f1f77bcf86cd799439021/icon"
}
}
FieldTypeRequiredDescription
statusCodenumberNo-
messagestringNo-
dataobjectNo-
data.idstringNo-
data.aliasstringNo-
data.descriptionstringNo-
data.image_namestringNo-
data.architecturestringNo-
data.osstringNo-
data.releasestringNo-
data.serialstringNo-
data.variantstring or nullNo-
data.sizenumberNo-
data.pricenumberNo-
data.added_datestringNo-
data.average_ratingnumberNo-
data.rating_countnumberNo-
data.icon_urlstring or nullNo-

Get the icon for a computer image. If the image has no icon, is not public, or does not exist, the endpoint returns a generic placeholder PNG.

NameInTypeRequiredDescription
idpathstringYesUnique identifier of the computer image to retrieve the icon for.
Terminal window
curl --request GET \
--url 'https://api.hoody.com/api/v1/images/67e89abc123def456789abcd/icon' \
--header 'Accept: image/png' \
--output 'image-icon.png'

Returns PNG image bytes. The response uses a generic placeholder PNG when the image has no icon, is not public, or does not exist.

Media type: image/png

Get a paginated list of computer images in the authenticated user’s imported or purchased library.

NameInTypeRequiredDescription
pagequeryintegerNoPage number for pagination. Starts from 1. Default: 1.
limitqueryintegerNoNumber of images to return per page. Maximum: 100. Default: 20.
sort_byquerystringNoSort user images by creation date. Allowed value: created_at.
sort_orderquerystringNoSort direction. Allowed values: asc, desc.
Terminal window
curl --request GET \
--url 'https://api.hoody.com/api/v1/images/user?page=1&limit=20&sort_by=created_at&sort_order=desc' \
--header "Authorization: Bearer $HOODY_TOKEN" \
--header 'Accept: application/json'

Returns one page of user computer images and pagination details.

Media type: application/json

{
"statusCode": 200,
"message": "User images retrieved successfully",
"data": {
"images": [
{
"id": "507f1f77bcf86cd799439021",
"alias": "debian/13",
"description": "Debian 13 (Trixie) - Default base image",
"image_name": "debian/13",
"architecture": "amd64",
"os": "debian",
"release": "13",
"variant": "default",
"size": 512000000,
"price": 0,
"user_rating": 5,
"has_rated": true,
"average_rating": 4.5,
"rating_count": 142,
"icon_url": "/api/v1/images/507f1f77bcf86cd799439021/icon"
}
],
"pagination": {
"total": 12,
"page": 1,
"limit": 20,
"totalPages": 1
}
}
}
FieldTypeRequiredDescription
statusCodenumberNo-
messagestringNo-
dataobjectNo-
data.imagesarrayNo-
data.images[].idstringYes-
data.images[].aliasstringNo-
data.images[].descriptionstringNo-
data.images[].image_namestringNo-
data.images[].architecturestringNo-
data.images[].osstringNo-
data.images[].releasestringNo-
data.images[].variantstring or nullNo-
data.images[].sizenumberNo-
data.images[].pricenumberNo-
data.images[].user_ratingnumber or nullNo-
data.images[].has_ratedbooleanNo-
data.images[].average_ratingnumberNo-
data.images[].rating_countnumberNo-
data.images[].icon_urlstring or nullNo-
data.paginationobjectNo-
data.pagination.totalnumberNo-
data.pagination.pagenumberNo-
data.pagination.limitnumberNo-
data.pagination.totalPagesnumberNo-

Import a free public computer image into the authenticated user’s library.

NameInTypeRequiredDescription
idpathstringYesUnique identifier of the public computer image to import.
Terminal window
curl --request POST \
--url 'https://api.hoody.com/api/v1/images/import/67e89abc123def456789abcd' \
--header "Authorization: Bearer $HOODY_TOKEN" \
--header 'Accept: application/json'

The free computer image was imported successfully.

Media type: application/json

{
"statusCode": 200,
"message": "Free computer image imported successfully",
"data": {}
}
FieldTypeRequiredDescription
statusCodenumberNo-
messagestringNo-
dataobjectNo-

Purchase a paid computer image for the authenticated user’s account.

NameInTypeRequiredDescription
idpathstringYesUnique identifier of the paid computer image to purchase.
Terminal window
curl --request POST \
--url 'https://api.hoody.com/api/v1/images/purchase/67e89abc123def456789abcd' \
--header "Authorization: Bearer $HOODY_TOKEN" \
--header 'Accept: application/json'

The paid computer image was purchased successfully.

Media type: application/json

{
"statusCode": 200,
"message": "Computer image purchased successfully",
"data": {
"price_paid": 5.99,
"remaining_balance": 44.01
}
}
FieldTypeRequiredDescription
statusCodenumberNo-
messagestringNo-
dataobjectNo-
data.price_paidnumberNo-
data.remaining_balancenumberNoWallet balance after the purchase. Omitted when the caller is an auth token without financial.wallet.read or one limited to realms.

Rate a computer image in the authenticated user’s library from 0 to 5 stars.

NameInTypeRequiredDescription
idpathstringYesUnique identifier of the computer image to rate.
FieldTypeRequiredDescription
ratingintegerYesRating for the image, a whole number of stars from 0 to 5.
{
"rating": 5
}
Terminal window
curl --request POST \
--url 'https://api.hoody.com/api/v1/images/rate/67e89abc123def456789abcd' \
--header "Authorization: Bearer $HOODY_TOKEN" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{"rating":5}'

The computer image was rated successfully.

Media type: application/json

{
"statusCode": 200,
"message": "Computer image rated successfully",
"data": {
"new_rating": 5,
"average_rating": 4.6,
"rating_count": 143
}
}
FieldTypeRequiredDescription
statusCodenumberNo-
messagestringNo-
dataobjectNo-
data.new_ratingnumberNo-
data.average_ratingnumberNo-
data.rating_countnumberNo-