Releases API
- List releases
- Get a single release
- Create a release
- Update a release
- Archive a release
- Trash a release
- Restore a release
- Fields
List releases
List all releases for an account:
GET /releases
Response
Status: 200 OK
[
{
"completion_target_at": "2016-06-14T15:00:00-05:00",
"status": "implementation",
"created_at": "2016-04-27T05:24:00-05:00",
"updated_at": "2016-05-31T18:53:31-05:00",
"subject": "Automate exchange rate updates in Expense Reporting",
"id": 294,
"sourceID": null,
"completed_at": null,
"impact": "none"
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of releases.
Predefined Filters
The following predefined filters are available:
/releases/completed
: List all completed releases/releases/open
: List all open releases/releases/managed_by_me
: List all releases which manager is the API user
Collection Fields
By default the following fields will appear in collections of releases:
id
sourceID
subject
impact
status
completion_target_at
completed_at
created_at
updated_at
Obtain a different set of fields using the ?fields= parameter.
Filtering
Filtering is available for the following fields:
id
source
sourceID
subject
impact
status
completion_target_at
completed_at
created_at
updated_at
Sorting
By default a collection of releases is sorted descending by id
.
The following fields are accepted by the ?sort= parameter:
id
sourceID
subject
impact
status
completion_target_at
completed_at
created_at
updated_at
Response
The response is similar to the response in List releases
Get a single release
GET /releases/:id
Response
Status: 200 OK
{
"completion_target_at": "2016-06-14T15:00:00-05:00",
"status": "implementation",
"created_at": "2016-04-27T05:24:00-05:00",
"updated_at": "2016-05-31T18:53:31-05:00",
"subject": "Automate exchange rate updates in Expense Reporting",
"id": 294,
"sourceID": null,
"completed_at": null,
"impact": "none",
"completion_reason": null,
"manager": {
"id": 53,
"name": "Frank Watson",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"source": null
}
The response contains these fields.
Create a release
POST /releases
When creating a new release these fields are available.
Response
Status: 201 Created
{
"subject": "...",
"...": "..."
}
The response contains all fields of the created release and is similar to the response in Get a single release
Update a release
PATCH /releases/:id
When updating a release these fields are available.
Response
Status: 200 OK
{
"subject": "...",
"...": "..."
}
The response contains all fields of the updated release and is similar to the response in Get a single release
Archive a release
POST /releases/:id/archive
Moves a given release to the Archive. This action requires the Account Administrator or Directory Administrator role in the account of the release.
Response
Status: 200 OK
{
"archived": "true",
"subject": "...",
"...": "..."
}
The response contains all fields of the archived release and is similar to the response in Get a single release
Trash a release
POST /releases/:id/trash
Moves a given release to the Trash. This action requires the Account Administrator or Directory Administrator role in the account of the release.
Response
Status: 200 OK
{
"trashed": "true",
"subject": "...",
"...": "..."
}
The response contains all fields of the archived release and is similar to the response in Get a single release
Restore a release
POST /releases/:id/restore
Moves a given release from the Archive or the Trash back into the view of “Completed Releases”. This action requires the Account Administrator or Directory Administrator role in the account of the release.
Response
Status: 200 OK
{
"subject": "...",
"...": "..."
}
The response contains all fields of the archived release and is similar to the response in Get a single release
Fields
- attachments
- Readonly aggregated Attachments
- Use Releases - Notes API to get note attachments.
- completed_at
- Readonly datetime — The Completed at field is automatically set to the date and time at which the release is set to the status “Completed”.
- completion_reason
- Readonly enum — The Completion reason field is automatically set based on the completion reason of the release’s workflows. Possible values are:
-
withdrawn
: Withdrawn - Withdrawn by Requesterrejected
: Rejected - Rejected by Approverrolled_back
: Rolled Back - Original Environment Restoredfailed
: Failed - No Requirements Metpartial
: Partial - Not All Requirements Metdisruptive
: Disruptive - Caused Service Disruptioncomplete
: Complete - All Requirements Met
- completion_target_at
- Readonly datetime — The Completion target field shows the target date and time of the last task of the workflows that are related to the release.
- created_at
- Readonly datetime — The date and time at which the release was created.
- custom_fields
- Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the release.
- custom_fields_attachments
- Writeonly attachments The attachments used in Custom fields.
- id
- Readonly integer — The unique ID of the release.
- impact
- Readonly enum — The Impact field shows the maximum impact level that is selected in the tasks of the workflows that are related to the release. This indicates the maximum extent to which a “service instance”:/help/service_instance will be impacted by the implementation of the release. Possible values are:
-
none
: None - Service Not Degradedlow
: Low - Service Degraded for One Usermedium
: Medium - Service Down for One Userhigh
: High - Service Degraded for Several Userstop
: Top - Service Down for Several Users
- manager
- Required reference to Person, default: authenticated person — The Manager field is used to select the Person who is responsible for coordinating the implementation of the release. The person must have the release Manager role.
- note
- Optional text (max 64KB) — The Note field is used to provide a high-level description of the result that should be accomplished by the implementation of the release’s workflows. It is also used to add any information that could prove useful for anyone affected by the release.
-
The Note field cannot be specified in the ?fields= parameter.
- note_attachments
- Writeonly attachments The attachments used in the Note field.
- source
- Optional string (max 30) - See source
- sourceID
- Optional string (max 128) - See source
- status
- Readonly enum — The Status field is automatically set based on the status of the release’s workflows. Possible values are:
-
registered
: Registeredrisk_and_impact
: Risk & Impact — deprecated: replaced byin_progress
approval
: Approval — deprecated: replaced replaced byin_progress
implementation
: Implementation — deprecated: replaced byin_progress
in_progress
: In Progressprogress_halted
: Progress Haltedcompleted
: Completed
- subject
- Required string (max 255) — The Subject field is used to enter a short description of the objective of the release.
- ui_extension
- Readonly reference to UI Extension — The UI extension field indicates the UI extension that is applied to the release.
- updated_at
- Readonly datetime — The date and time of the last update of the release. If the release has no updates it contains the
created_at
value.