Skip to content

api/resources: Move the OS & Supervisor Release examples under the Release resource #3414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
thgreasi wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

api/resources: Move the OS & Supervisor Release examples under the Release resource #3414

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c2cf56
api/resources: Add the missing query param on the
thgreasi Apr 16, 2026
d056efa
api/resources: Move the OS & Supervisor Release examples under the Re…
thgreasi Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 43 additions & 58 deletions config/dictionaries/resource.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1013,46 +1013,25 @@
"method": "GET",
"endpoint": "/v7/release",
"filters": "?\\$filter=belongs_to__application%20eq%20<FLEET ID>%20and%20commit%20eq%20'<COMMIT HASH>'&\\$select=id"
}
]
},
{
"id": "release_tag",
"name": "Release tag",
"fields": [
"id",
"release",
"tag_key",
"value"
],
"examples": [
},

{
"id": "get-release-tags",
"summary": "Get all tags by release commit",
"description": "",
"id": "list-balenaos-versions-for-device-type",
"summary": "List the supported balenaOS versions for a device type",
"description": "To request a list of the supported balenaOS versions for a particular device type, the `DEVICE TYPE SLUG` parameter is required. Even though this query only selects the `raw_version` field, you can additionally specify any of the fields found in the release resource. The Authorization header is optional.",
"method": "GET",
"endpoint": "/v7/release_tag",
"filters": "?\\$filter=release/commit%20eq%20'<COMMIT>'"
"endpoint": "/v7/release",
"filters": "?\\$select=raw_version&\\$filter=(is_final%20eq%20true)%20and%20(is_invalidated%20eq%20false)%20and%20(status%20eq%20'success')%20and%20(semver_major%20gt%200)%20and%20(belongs_to__application/any(bta:(bta/is_host%20eq%20true)%20and%20(bta/is_for__device_type/any(dt:dt/slug%20eq%20'<DEVICE TYPE SLUG>'))))&\\$orderby=semver_major%20desc,semver_minor%20desc,semver_patch%20desc,revision%20desc"
},
{
"id": "create-release-tag",
"summary": "Create a new release tag",
"description": "",
"method": "POST",
"endpoint": "/v7/release_tag",
"filters": "",
"data": "{\n \"release\": \"<RELEASE ID>\",\n \"tag_key\": \"<KEY>\",\n \"value\": \"<VALUE>\"\n}"
}
]
},
{
"id": "supervisor_release",
"name": "List Supervisor releases",
"fields": [
"id",
"raw_version"
],
"examples": [
"id": "list-balenaos-versions-for-private-device-type",
"summary": "List the supported balenaOS versions for a private device type",
"description": "Same as above, but in order to access private device types, you must provide an authentication token.",
"method": "GET",
"endpoint": "/v7/release",
"filters": "?\\$select=raw_version&\\$filter=(is_final%20eq%20true)%20and%20(is_invalidated%20eq%20false)%20and%20(status%20eq%20'success')%20and%20(semver_major%20gt%200)%20and%20(belongs_to__application/any(bta:(bta/is_host%20eq%20true)%20and%20(bta/is_for__device_type/any(dt:dt/slug%20eq%20'<DEVICE TYPE SLUG>'))))&\\$orderby=semver_major%20desc,semver_minor%20desc,semver_patch%20desc,revision%20desc"
},

{
"id": "get-supervisor-releases-by-cpu-architecture-slug",
"summary": "Get all supervisor releases for a specific cpu architecture by slug (eg amd64/rpi/armv7hf/aarch64)",
Expand Down Expand Up @@ -1080,25 +1059,31 @@
]
},
{
"id": "balenaos_versions",
"name": "List balenaOS releases",
"fields": [],
"id": "release_tag",
"name": "Release tag",
"fields": [
"id",
"release",
"tag_key",
"value"
],
"examples": [
{
"id": "list-balenaos-versions-for-device-type",
"summary": "List the supported balenaOS versions for a device type",
"description": "To request a list of the supported balenaOS versions for a particular device type, the `DEVICE TYPE SLUG` parameter is required. Even though this query only selects the `raw_version` field, you can additionally specify any of the fields found in the release resource. The Authorization header is optional.",
"id": "get-release-tags",
"summary": "Get all tags by release commit",
"description": "",
"method": "GET",
"endpoint": "/v7/release",
"filters": "?\\$select=raw_version&\\$filter=(is_final%20eq%20true)%20and%20(is_invalidated%20eq%20false)%20and%20(status%20eq%20'success')%20and%20(semver_major%20gt%200)%20and%20(belongs_to__application/any(bta:(bta/is_host%20eq%20true)%20and%20(bta/is_for__device_type/any(dt:dt/slug%20eq%20'<DEVICE TYPE SLUG>'))))&\\$orderby=semver_major%20desc,semver_minor%20desc,semver_patch%20desc,revision%20desc"
"endpoint": "/v7/release_tag",
"filters": "?\\$filter=release/commit%20eq%20'<COMMIT>'"
},
{
"id": "list-balenaos-versions-for-private-device-type",
"summary": "List the supported balenaOS versions for a private device type",
"description": "Same as above, but in order to access private device types, you must provide an authentication token.",
"method": "GET",
"endpoint": "/v7/release",
"filters": "?\\$select=raw_version&\\$filter=(is_final%20eq%20true)%20and%20(is_invalidated%20eq%20false)%20and%20(status%20eq%20'success')%20and%20(semver_major%20gt%200)%20and%20(belongs_to__application/any(bta:(bta/is_host%20eq%20true)%20and%20(bta/is_for__device_type/any(dt:dt/slug%20eq%20'<DEVICE TYPE SLUG>'))))&\\$orderby=semver_major%20desc,semver_minor%20desc,semver_patch%20desc,revision%20desc"
"id": "create-release-tag",
"summary": "Create a new release tag",
"description": "",
"method": "POST",
"endpoint": "/v7/release_tag",
"filters": "",
"data": "{\n \"release\": \"<RELEASE ID>\",\n \"tag_key\": \"<KEY>\",\n \"value\": \"<VALUE>\"\n}"
}
]
},
Expand All @@ -1108,22 +1093,22 @@
"fields": [],
"examples": [
{
"id": "download-private-balenaos",
"summary": "Download private or ESR balenaOS images",
"description": "In order to download an ESR or private balenaOS image, you need to provide your bearer token. The `deviceType` and `version` parameters are required. Add an `--output` flag to provide a path for the image to be downloaded.",
"id": "download-balenaos",
"summary": "Download public balenaOS images",
"description": "Same as above but the auth header is optional to use. The `deviceType` and `version` parameters are required. You can find the available balenaOS version by using the [Release resource example for listing the supported balenaOS versions for a device type](release#list-balenaos-versions-for-device-type) .These releases also available for download on balena.io/os and the dashboard.",
"method": "GET",
"endpoint": "/download",
"content-type": "application/octet-stream",
"filters": "?deviceType=<DEVICE NAME>&version=<BALENAOS VERSION>&fileType=.zip'"
"filters": "?deviceType=<DEVICE NAME>&version=<BALENAOS VERSION>&fileType=.gz'"
},
{
"id": "download-balenaos",
"summary": "Download public balenaOS images",
"description": "Same as above but the auth header is optional to use. The `deviceType` and `version` parameters are required. These releases also available for download on balena.io/os and the dashboard.",
"id": "download-private-balenaos",
"summary": "Download private or ESR balenaOS images",
"description": "In order to download an ESR or private balenaOS image, you need to provide your bearer token. The `deviceType` and `version` parameters are required. Add an `--output` flag to provide a path for the image to be downloaded.",
"method": "GET",
"endpoint": "/download",
"content-type": "application/octet-stream",
"filters": "?deviceType=<DEVICE NAME>&version=<BALENAOS VERSION>&fileType=.gz'"
"filters": "?deviceType=<DEVICE NAME>&version=<BALENAOS VERSION>&fileType=.zip'"
}
]
},
Expand Down
Loading
Loading