Description
Returns one page of the releases of a project, newest first.
Every entry carries the release's identity, its notes and the metadata document attached when it was created, so a pipeline polling for what has been built does not have to read each release individually to see them.
What is deliberately not here is the snapshot - the package versions, steps, variables and lifecycle phases a release locked in. That is what Get a release returns. The deployments of a release are not here either: a release can be deployed any number of times, so its deployments are a paged list of their own - List deployments.
Ordering is by creation date, newest first, with the release ID breaking ties between two releases created in the same microsecond. It is not version order: SemVer ordering cannot be expressed in SQL, and a page boundary has to mean the same thing to the server as it does to the caller. A release cut out of version sequence - a hotfix on an older line, say - therefore still appears at the top of the first page.
Deleted releases are never returned.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId |
query | string | yes | ID of the project whose releases to list, from List projects. |
max |
query | integer | no | Releases per page. Defaults to 100 and is clamped to the range 1-500 rather than rejected, so an out-of-range value still returns a page. |
cursor |
query | string | no | Continuation token from the previous response's nextCursor. Omit it to read the first page. See below. |
Paging
Paging is by cursor, not by row offset. Read the first page without cursor, then hand each response's nextCursor back as the cursor of the next request, and keep going until nextCursor comes back null.
That null is the only signal that you have read everything. Do not stop on a short page and do not compare the row count against the max you asked for - neither tells you whether more releases follow.
A cursor rather than a page number, because a build server keeps creating releases while you page and each new one arrives at the top of this list. A numbered window would shift underneath you on every arrival, handing you some releases twice and skipping others entirely. A cursor names the last row you actually read, so the next page continues from there whatever has appeared in front of it.
The token is opaque. Hand it back as you received it rather than building or reading one - it encodes a position, and the encoding is free to change. A token that does not decode is rejected with 400 rather than ignored, because serving page one to a caller that believes it asked for page nine is the worse failure.
Response
| Field | Type | Description |
|---|---|---|
projectId |
string | The project the page belongs to, echoing the one you asked for. |
releases |
object[] | One page of releases, newest first. Empty array when the project has no releases - not an error. |
releases[].releaseId |
string | The release's id. Pass it to Get a release or Deploy a release. |
releases[].projectId |
string | The project the release belongs to. |
releases[].version |
string | The release version, as it was stored. Note that this list is not ordered by it. |
releases[].notes |
string | The release notes, or null when none were given. |
releases[].metadata |
object | The free-form document attached at creation, exactly as it was stored, or null when none was attached. Jaws never reads into it - see Create a release. |
releases[].created |
string | When the release was created, ISO 8601 with offset. This is the field the list is ordered by. |
releases[].createdBy |
object | Who created the release: userId, name and email. The service account's own user for a release cut by a pipeline. null when the creator no longer resolves. |
releases[].channelId |
string | The channel the release is bound to, or null for a release created without one. |
releases[].channelName |
string | Name of that channel, or null. |
releases[].lifecycleName |
string | Name of the lifecycle the channel binds the release to, or null when the release is not phase-controlled. |
nextCursor |
string | Pass back as cursor to read the next page. null means this page was the last one. |
Errors
| Status | Meaning |
|---|---|
400 |
Missing or invalid projectId. A project in another organization is reported the same way as one that does not exist, so an id cannot be probed for existence. |
400 |
cursor is not a token this endpoint issued - the response reads invalid cursor. Nothing is returned; ask again from the page you last read. |
401 |
Missing or invalid Basic auth credentials, or the service account lacks permission to view releases of this project. |