Updates

You no longer need to predefine custom fields before configuring an integration. The setup process now supports creating custom fields directly within the integration configuration flow.

This update reduces manual steps and makes it easier to define exactly what you need without leaving the context of your integration setup.

‍

To find out more about creating integrations, click here. To see our recent updates in the Developer Portal, click here.

In this update, we’ve made the following changes: 

‍

New Custom Field Group endpoints added

A Custom Field Group is a container that allows you to group related custom fields together. For more information about setting up Custom Fields (including Custom Field Groups) please see our help center article here. You will need to have edit access on the Custom Fields and you will need the Custom Fields Admin role to use the endpoint. 

‍

• List Custom Field Groups - ^{GET /core/custom_field_groups} 
• Get a Custom Field Group - ^{GET /core/custom_field_groups/{id}}
• Create a new Custom Field Group - ^{POST /core/custom_field_groups}
• Update a Custom Field Group - ^{PATCH /core/custom_field_groups/{id}}
• Archive a Custom Field Group - ^{PATCH /core/custom_field_groups/{id}/archive}

‍

Note: You will need to have at least Cutover Core version of 2025.1.0 to use these endpoints. 

‍

‘Relationships’ attribute added 

‍

We’ve also added a new ‘relationships’ attribute to introduce support for associating a Custom Field with a Custom Field Group - 

^{core.custom_field.relationships.custom_field_group}

‍

Custom Field fix

‍

We’ve improved the ^{GET /core/custom_fields/{id}} endpoint so it now correctly supports runbook-type filtering, ensuring reliable and consistent access to the right custom field data.

‍

Other minor changes

Create a new Custom Field - Improved documentation for ^{POST /core/custom_fields}, including clearer schema descriptions. 

‍

In this update, we’ve made the following changes: 

Major changes

‍

Improved Custom Field Search:

‍

We’ve added ^searchable and ^{multi_searchable} options to GET/custom_fields query parameters to help improve the filtering of your results. We’ve also updated ^{core.custom_field.field_type} schema to support these new search options. 

‍

We’ve added ^{core.custom_field.relationships.constraints} introducing the ability to define constraints for custom fields. 

‍

We’ve introduced ^{core.custom_field.relationships.dependent_custom_fields} to define field dependencies.

‍

We’ve added ^{core.custom_field_values.display_name} for more readable values. Note: You need to have at least Cutover Core version 2024.16.0 to see the above mentioned change.

‍

‍

RTO/RTA Management for runbooks

‍

We’ve added the ^{core.runbook.rto} attribute for setting/updating RTO values in runbook templates. 

‍

We’ve introduced ^{core.runbook.relationships.rto_start_task}, ^rto_end_task, and ^rto_source for managing the RTO lifecycle.

‍

GET/core/runbooks and GET/core/runbooks{id} now return ^{core.runbook.meta.rto_rta_meta} with RTO/RTA details.

‍

Note: You need to have at least Cutover Core version 2024.16.0 to see the above mentioned changes.

‍

‍

Other minor changes

‍

We’ve added a ^{create_activity} boolean to the ‘Comments’ resource. This helps to manage activity creation when adding comments to the Activity feed. The default setting is true. 

‍

Note: You need to have at least Cutover Core version 2025.1 and the activity feed functionality turned on to see the above mentioned change.

‍

We’ve added a new ^hooks attribute to the 'integration_actions' resource. This is to help determine the resource type the integration is linked to and is now a mandatory field for integration actions. Available triggers are task/started (default) and runbook/updated. 

‍

We’ve also added ^{core.tasks.relationships.recipients} allowing tasks to be associated with specific recipients. 

‍

Note: You need to have at least Cutover Core version 2024.16 to see this change. 

‍

GET/core/users/ now supports sorting via the ^sort query parameter. 

‍

Setting up failure values

You can now set failure values in the Custom Integration Polling tab to define when a polling integration should fail. This ensures that Polling integrations will stop when a specified condition is met. For more details on this update, please see the Polling tab in our Developer Portal. 

‍

‍Maximum retries option added for polling

You can now set a maximum retries amount for integrations that require polling. The default value for new and existing integrations are 120 retries and this can be increased or decreased as required. You should review any polling integrations (through Custom Integration) to ensure this number suits your needs. 

‍

Default polling interval value

The default polling interval value has been updated to 30 seconds for all new integrations. 

‍

‍

Please see our Polling section for more information about these changes. 

‍

New Refresh data source option

You can now pull new fields and attributes from the data source by using the Refresh option which can be found in the three dots menu. Here you can also archive a data source too. Refreshing a datasource will require users to input a new search value before new attributes can be retrieved. 

‍

‍

Nested JSON now supported in Data sources

Previously data sources only supported non-nested JSON structures. You can now drill down into nested JSON for data sources, allowing you to be more granular when adding this information into the platform.  

‍

‍

In this update, we've made the following changes: 

‍

Major changes

‍

Enhancements to the `List Runbooks` endpoint for editing runbooks

‍

We’ve added an ^is_editable attribute to the `Runbook` resource. This means that the runbook can be marked as editable/uneditable during certain processes such as the Task CSV Import. 

‍

Note: You need to have at least Cutover Core version 2024.13.0 to see the above mentioned change.

‍

‍

New Runbook endpoint added 

‍

• Get roles for runbook - ^{GET /core/runbooks/{id}/roles}

This endpoint retrieves all of the roles for a specific runbook. You can use the available query parameters to filter the results. 

‍

Note: You need to have at least Cutover Core version 2024.14.0 to see the above mentioned change.

‍

‍

New Folder endpoints added

‍

• Replace roles for a folder - ^{POST /core/workspaces/{workspace_id}/folders/{id}/roles}

‍

This endpoint replaces all roles on the folder. Note: You will need to have at least Cutover Core version 2024.14.0 to use this endpoint. 

‍

‍

• Update a folder - ^{PATCH /core/workspaces/{workspace_id}/folders/{id}}

‍

This endpoint updates a specific folder in a specific workspace. Note: You will need to have at least Cutover Core version 2024.14.0 to use this endpoint. 

‍

Other minor changes

The List, Get, Create and Update Integration action endpoints now have updated schemas.

‍

To make it easier when searching we’ve set the default sort order for ‘^{List Users}’ to be core_users.email. 

‍

We’ve also fixed the List Tasks in a Runbook query parameter ^{runbook_team_id}. 

‍

Major changes

‍

New endpoints

‍

In this update, we’ve added five new `Integrations` endpoints:

‍

• List Integrations - ^{GET /core/integrations}
• Get an Integration - ^{GET /core/integrations/{id}}
• Create a new Integration - ^{POST /core/integrations}
• Update an Integration - ^{PATCH /core/integrations/{id}}
• Archive an Integration - ^{PATCH /core/integrations/{id}/archive}

Note: You need to have at least Cutover Core version 2024.12.0 to use these endpoints.

‍

These endpoints will allow you to manage your integrations by giving you the ability to create new, update, archive, retrieve and get a list of integration actions in your instance. 

‍

Other minor changes

‍

We’ve added an `archived` query parameter to the List Runbooks endpoint to help improve the filtering of your results. It can filter on ^true or ^false. 

‍

Major changes

‍

New endpoints

‍

In this update, we’ve added five new `Integrations` endpoints:

‍

• List Integrations Actions - ^{GET /core/integration_actions}
• Get an Integration Action - ^{GET /core/integration_actions/{id}}
• Create a new Integration Action - ^{POST /core/integration_actions}
• Update an Integration Action - ^{PATCH /core/integration_actions/{id}}
• Archive an Integration Action - ^{PATCH /core/integration_actions/{id}/archive}

‍

Note: You need to have at least Cutover Core version 2024.11.0 to use this endpoint.

‍

These endpoints will allow you to manage your integration actions by giving you the ability to create new, update, archive, retrieve and get a list of integration actions in your instance. 

‍

Other minor changes

We’ve also made some documentation improvements to our `Get a Runbook` query parameter ^{custom field values}. 

‍

Major changes

New 'Task' endpoints: 

‍

In this update, we’ve added three new `Task` endpoints:

‍

• ‍Update a Task integration status - _‍^{PATCH /core/runbooks/{runbook_id}/tasks/{id}/integration/status}

‍

Note: You need to have at least Cutover Core version 2024.10.0 to use this endpoint.

‍

‍

• Cancel a Task integration -  ^{PATCH /core/runbooks/{runbook_id}/tasks/{id}/integration/cancel}

• Trigger a Task integration - ^{PATCH /core/runbooks/{runbook_id}/tasks/{id}/integration/trigger}

‍Note: You need to have at least Cutover Core version 2024.9.0 to use the above two endpoints.These endpoints will allow you to manage your integrations by giving you the ability to trigger, pause and check the status. 

‍

Other minor changes

‍

We’ve added a featured attribute to the ^Comments resources. This gives the ability to Star comments.  

‍

We’ve also fixed an issue with filtering the ^{List Comments in a runbook} endpoint. 

‍

Note: You need to have at least Cutover Core version 2024.8.0 to see the above mentioned change.

‍

Major changes

In this update, we have made the following changes: 

‍

New `Runbook` endpoint

‍

We’ve added a new `Runbook` endpoint - Replace roles for a runbook - ^{POST /core/runbooks/{id}/roles}

‍

The endpoint replaces all roles on the runbook. When making updates to an existing runbook, use the "Get roles for a runbook" endpoint to retrieve the current role data.

‍

‍Note: You need to have at least Cutover Core version 2024.5.0 to use this endpoint.

‍

Other minor changes

‍

• We've fixed an issue with creating sub-streams.  

‍

In this update, we have made the following changes: 

‍

• New updated descriptions now provide further clarity on each endpoint.
  
  
• We have added a ^restricted attribute to the Runbook resource which means that the user must have a direct role to access the runbook. 

Note: You need to have at least Cutover Core version 2024.2.0 to see this attribute.

‍

• We have added a source_runbook attribute. The source runbook provides the ID from which the runbook was copied from. 

Note: This is only required on the ^{Get a Runbook} endpoint. 

‍

Major changes

New 'Runbook' endpoints

In this update, we’ve added three new endpoints:

‍

• Cancel a Runbook - ^{PATCH /core/runbooks/{runbook_id}/cancel}‍
• Pause a Runbook -  ^{PATCH /core/runbooks/{runbook_id}/pause}‍
• Resume a runbook - ^{PATCH /core/runbooks/{runbook_id}/resume}

These endpoints will allow you to manage your runbooks by giving you the ability to pause, resume and cancel. 

‍

Note: You need to have at least Cutover Core version 3.84 to use these endpoints.

‍

Enhancement to the 'List Runbook(s)' endpoint

‍

We’ve added the following attributes to the ^Runbook resource to help with sorting the List Runbooks response by when the runbooks were last ^touched_at.

‍

•  ^{GET /core/runbooks?sort= parameter. sort=touched_at}

Note: You need to at least have Cutover Core version 3.83 to use this attribute.

Major changes

New 'Stream' endpoints

In this update, we’ve added three new 'Stream' endpoints: 

‍

• Create a new Stream - ^{POST /core/runbooks/{runbook_id}/streams}
• Update a Stream - ^{PATCH /core/runbooks/{runbook_id}/streams/{id}}
• Delete a Stream - ^{DELETE /core/runbooks/{runbook_id}/streams/{id}}‍‍

Note: You need to have at least Cutover Core version 3.84 to use these endpoints.

Major changes

Enhancements to the 'Get Roles for a User' endpoint

‍

We’ve added a 'resource_type' query parameter to the Get Roles for a User endpoint to help improve the filtering of your results. It can filter on ^global, ^folder, ^workspace, ^runbook, ^stream or ^user.

‍

Note: You need to at least have Cutover Core version 3.82 to use this query parameter.

‍

Major changes

New options added to the 'Merge Runbook(s)' endpoint

‍

We’ve added a new 'Merge Runbook(s)' endpoint:

‍

• Insert after task id - ^{PATCH/core/runbooks/{id}/merge} . This allows you to specify where you want the incoming runbook to be inserted.
• Insert type - ^{PATCH/core/runbooks/{id}/merge}. When you are inserting multiple runbooks, the ‘insert type’ determines whether the tasks are inserted in parallel or sequence. 

‍

Added new Linked Runbooks functionality

‍

• We’ve added the following attributes to the ^Task resource to help with managing Snippets and Linked Runbooks. This new functionality allows you to create linked runbooks: ^{core.task.attributes.task_links}

‍Other minor changes

‍Enhancements to the Get a Runbook resource for Snippets functionality

‍

• We’ve enhanced the following attribute: template_type - Indicates whether the runbook isn’t a template at all (^off), is a normal template (^default), or is a snippet template (^snippet). 

New Get a User query parameter

‍

• We’ve added a new query parameter to the Get a User endpoint: ^id_key

‍Note: You will need to at least have Cutover Core version 3.82 to use all of these new features

‍

Major changes

Enhancements to the 'List Tasks in a Runbook' response

‍

We’ve made two enhancements to the List Tasks in a Runbook response:

• Forecast mode now also returns ^predecessors and ^successors array of tasks as part of the ^{relationships} object.
• When the ^{source_runbook} field is included in the fields list, custom field values belonging to that source runbook are now included. These values are marked ^read_only in the response because they are a historical snapshot of the source runbook, and are not updatable when updating custom fields on a task.

Note: You need to at least have Cutover Core version 3.81 to benefit from both of these improvements.

‍

‍Enhancements to the 'Runbook' resource

‍

We’ve made two enhancements to the source:

‍

• We’ve added an ^author object to the relationships object of the ^Runbook resource. It can be read to see which user created a runbook but can also be written to (to state which user authored a new runbook) when using Create a new Runbook. This is important for any user looking to make API calls from ServiceNow using Business Rules. The author object can be used to pass through the user that has made the call request and will make them the Runbook Admin in Cutover. The user must have the 'Workspace runbook creator' role assigned to them to be made Runbook Admin in this scenario.
• We’ve added an ^external_id attribute to the ^Runbook resource. This ID pertains to an external system, such as an IT service management ticket associated with the runbook. It must be unique to Cutover - two runbooks can’t share the same ^external_id.

Note:  You need to at least have Cutover Core version 3.81 to benefit from both of these improvements.

‍

New 'Get a Runbook' query parameter

‍

In light of the addition of the ^external_id attribute to the ^Runbook resource, a new query parameter has been added to the Get a Runbook endpoint:

• ^id_key

It can filter on either a normal runbook ^id or on the ^external_id.

Note: You need to at least have Cutover Core version 3.81 to use this query parameter.

Major changes

New 'ActionLog' query parameters

‍

We've added two new query parameters to the List Action Logs endpoint:

• ^{created_after}
• ^{created before}

These new query parameters allow you to filter by actions performed after and before a given date and time.

‍Note: You need to at least have Cutover Core version 3.79 to use these query parameters.

‍

Other minor changes

• We've improved our generic remote error response by now providing specific error information with it.
• The List Tasks in a Runbook response now provides ^{relationships} data about ^{runbook_teams}.

Major changes

New  'RunbookTeam' endpoints

‍

We've added three new 'RunbookTeam' endpoints:

• Create a new Runbook Team - ^{POST /core/runbooks/{runbook_id}/runbook_teams}
• Delete a Runbook Team - ^{DELETE /core/runbooks/{runbook_id}/runbook_teams/{id}}‍
• Unlink a Runbook Team - ^{PATCH /core/runbooks/{runbook_id}/runbook_teams/{id}/unlink}

These endpoints give you greater control and more efficient management over your runbook teams. You can create new runbook teams in a specified runbook, as well as delete them from a specified runbook. You can also unlink a runbook team from its centralized team, which copies its list of users over to a specified runbook which can then be customized.

‍

Enhancement to the  resource for template workflows

‍

We’ve added the following attributes to the ^Runbook resource to help with managing and tracking template workflows. They can be used to retrieve the status of templates, as well as provide other key information, all of which can be important for reporting purposes.

• ^{attributes.template_status} - Indicates whether the template’s status is currently ^draft, ^pending or ^approved. This attribute is read only.
• ^{attributes.template_type} - Indicates whether the runbook isn’t a template at all (^off), is a normal template (^default), or is a snippet template (^snippet). This attribute can be read and written.
• ^{meta.approval_status} - Indicates whether the template’s approval status is currently ^pending, ^open, ^approved, ^rejected, ^expiring or ^expired. This attribute is read only.
• ^{meta.template_version} - Indicates the current version of the template. This attribute is read only.
• ^{relationships.reviews} - Provides an array of template reviews with their respective IDs. This attribute is read only. The details of each review is in the ^included section at the bottom of the response. This relationship is only included in the Get a Runbook response.
  

Major changes

Enhancements to  'Task' resource

We’ve added the following in relation to the ^auto_finish attribute. Note: You need to at least have Cutover Core version 3.76 to benefit from these improvements:

• New error codes for scenarios in which it isn't possible to set ^auto_finish:

- ^{task.auto_finish_on_auto_finish_task_type:} It can't be set on an Auto Finish task type.

- ^{task.auto_finish_on_branching_task_type:} It can't be set on a Branching task type.

- ^{task.auto_finish_on_integration:} It can't be set on an Integration task type.

- ^{task.auto_finish_on_linked_task_type:} It can't be set on a Linked to Runbook task type.

- ^{task.auto_finish_on_required_custom_fields:} It can't be set on tasks with required custom fields that display on the task's end.

- ^{end.task.auto_finish_on_snippet_task_type:} It can't be set on a Snippet task type.

- ^{task.auto_finish_requires_end_fixed:} It can't be set on tasks that have a fixed due date and time.

• The ^auto_finish attribute can be set to ^null, which will mean the task will fall back to the associated task type's ^auto_finish value.

Major changes

Enhancement to 'Task' resource

‍

We’ve added an ^auto_finish attribute to the  resource. This means you can read whether a task is set to automatically finish, as well as use the endpoints Create a New Task and Update a Task to apply automatic finishes to tasks. To clarify the working of the auto finish feature, a task will automatically finish once its specified duration has expired, provided all validation has passed beforehand. Note: You need to at least have Cutover Core version 3.76 to benefit from this improvement.

‍

Enhancement to the 'List Folders' endpoint

‍

We’ve added ^{meta.permissions} data to the ^Folder resource in the List Folders response, enabling you to read which folders you have the permission to create runbooks in. Note: You need to at least have Cutover Core version 3.76 to benefit from this improvement.

‍‍

Enhancement to the 'Stream' resource

‍

We’ve added ^parent data to the ^{stream.relationships}  object so you can see which sub-streams belong to which parent stream.

Major changes

Enhancement to 'Folder' resource

We’ve added ^parent data to the ^{folder.relationships} object so you can see which subfolders belong to which parent folder, create new subfolders, and update subfolders so they belong to different parent folders. Note: You need to at least have Cutover Core version 3.73 to benefit from this improvement.

Firstly, a notice: A fix has been implemented in Cutover Core version 3.73 meaning that Update a Runbook works as expected. If you have an earlier Cutover Core version, the call incorrectly results in creating a new or empty runbook version. To avoid this, upgrade to 3.73.

Major changes

New  'RunbookTeam' endpoint

We've added a new 'RunbookTeam' endpoint:

‍

• List Runbook Teams in a Runbook - ^{GET /core/runbooks/{id}/runbook_teams}

This endpoint lets you retrieve all runbook teams from the current version of a specified runbook.

‍Note: You need to at least have Cutover Core version 3.73 to use this endpoint.

‍

Enhancement to  endpoints

For  endpoints, we've added the ability to read and update runbook teams who are assigned to, and are recipients of communications from, a task. Note: You need to at least have Cutover Core version 3.73 to benefit from this improvement.

Other minor changes

• We’ve implemented a fix to ensure that ^Runbook endpoint responses include the ^{relationships} object’s ^runbook_type object.

Major changes

New  'Teams' endpoint

We've added a new 'Teams' endpoint:

‍

• Delete a Centralized Team - ^{DELETE /core/teams/{id}}

This endpoint lets you delete a centralized team that you no longer require. It will temporarily mark the team as archived before copying all deleted roles to linked runbook teams, and then fully deleting the team.

‍

New  'Roles' endpoint

We've added a new 'Roles' endpoint:

‍

• Get roles for a runbook - ^{GET /core/runbooks/{id}/roles}
  

This endpoint lets you retrieve the roles (for example Runbook Admin, Stream Editor and Runbook Member) connected to a specified runbook.

Note: You need to at least have Cutover Core version 3.65 for this endpoint to work.

Other minor changes

• We’ve added the ability to read and update users who are assigned to, and are recipients of communications from, a task. This applies to List Tasks in a Runbook, Get a Task, Create a new Task and Update a Task endpoints. Note: You need to at least have Cutover Core version 3.68 for this endpoint to work.

• We’ve added query parameters to the List Users endpoint so you can filter returned results. Note: You need to at least have Cutover Core version 3.69 for these to be available:
  ‍
  - ^page[number](pagination)
  - ^query (approximate string matching by team name (also known as a ‘fuzzy’ search))
  - ^role_type_id
  - ^workspace_id

• We’ve added ^event and ^{resource_type} query parameters to the List Action Logs endpoint to help improve the filtering of your results. Note: You need to at least have Cutover Core version 3.68 for these to be available.
• When no bearer token is passed for authentication, we’ve corrected the error that gets returned; it is now ^{401 Unauthorized} instead of^{500 Internal Server Error}.
• We’ve now removed support for Cutover Core version 3.63.0.

‍

Major changes

Enhancement to 'List Tasks in a Runbook' endpoint

‍

When you request a ^{source_runbook} in the  List Tasks in a Runbook endpoint via the ^{source_runbook_id} query parameter, the response now includes the full runbook object in the ^included array.  

‍Note: You need at least Cutover Core version 3.67 to benefit from this enhancement.

‍

Enhancement to 'Get roles for a user' endpoint

We’ve enhanced the ^included object in the Get roles for a user  endpoint’s response to include all possible resources that the ^{relationships} object references within it.

Other minor changes

• We've improved our ^User endpoint's path parameters documentation to make it clear when a user's email can be used instead of their ID. Note: You need to at least have Cutover Core version 3.67 to benefit from this improvement.

‍

Major changes

New 'Roles' endpoint

We've added a new  endpoint:

‍

• Get roles for a team - ^{GET /core/teams/{id}/roles}

This endpoint lets you retrieve the roles for a team member by their ID or email.

Note: You need to at least have Cutover Core version 3.65 for this endpoint to work.

Other minor changes 

• We’ve renamed ^Team/s to ^{Centralized Team/s} where relevant in our endpoint documentation.
• ‍We’ve improved our JSON examples in our endpoint documentation for Create a new Centralized Team and Update a Centralized Team.
• We’ve removed support for Cutover Core version 3.61.

‍

‍

Major changes

New  'Runbook' endpoint

We have added a new 'Runbook' endpoint:

‍

• Merge Runbook(s) - ^{PATCH /core/runbooks/{id}/merge}

This endpoint lets you merge single or multiple runbooks into the runbook that you specify in the path parameter. 

Note: You need to at least have Cutover Core version 3.65 for this endpoint to work.

Other minor changes 

• We have added three query parameters to List Teams to improve the ability to filter returned results. Note: You need to at least have Cutover Core version 3.65 for these parameters to work:
  ‍‍
  - ^page[number] (pagination)
  - ^query (approximate string matching by team name (also known as a ‘fuzzy’ search))
  - ^workspace_id

• We have made general fixes and improvements to the ^Role resource. We have also added request examples to endpoint documentation that uses the resource. Note: You need to at least have Cutover Core version 3.65 to benefit from these fixes and improvements.
• We have added the ^key attribute to the ^RoleType resource. For example, this means you can read and pass the key string workspace-stakeholder as opposed to having to look up the ^RoleType's id.
• We have implemented a fix for missing ^{custom_field_values} for returned ^Task resources.
• We have implemented a fix to hide a returned ^Runbook resource’s relationships attribute ^{source_runbook} when the attribute has not previously been set.
• We have improved the detail given in the ^{400 Bad Request} error, which now makes it clearer when path parameters have not been specified. The lack of details previously given was liable to lead to the incorrect assumption that the error was in the JSON payload.

‍

Major changes

New  attributes

We have added some new attributes to the 'User' resource to increase its comprehensiveness.

• You can now create, update and read a user’s email and SMS acceptance settings with ^accept_email and ^accept_sms.
• You can now read login-related activity and metrics via these ^meta attributes:
  ‍
  - ^{last_activity_at}
  - ^{last_sign_in_at}
  - ^{invitation_accepted_at}
  - ^{invitation_sent_at}
  - ^{sign_in_count}

‍

Major changes

New 'Folder' endpoints

We have added two new  endpoints:

‍

• Create a new Folder - ^{POST /core/workspaces/{workspace_id}/folders}
• Update a Folder - ^{PATCH /core/workspaces/{workspace_id}/folders/{id}}

These endpoints give you greater control and management over your folders in a specified workspace. You can create new folders and you can update the name and description of existing ones.

Other minor changes

• We have added a runbook’s description to the List Runbooks response. Even if a runbook has not been given a description, a blank string is now returned.
• We have added ^{source_runbook_id} as a query parameter to List Tasks in a Runbook, letting you filter your task results by it.
• We have added the ability to pass ^{users/{email}} as well as ^users/{id} on all endpoints using the user path. For example, you can now call ^{GET /core/users/user%40example%2Ecom} (note that periods must be escaped).

‍

Major changes

New  'ListActionLogs' endpoint

We have added a new  endpoint:

‍

• List Action Logs - ^{GET /core/action_logs}

Provided you are either a Global User Admin or a Global Stakeholder, this lets you retrieve all of the action logs for your instance. Action logs provide you with a description of the action, any related changes because of the action, the author of the action, and the resource involved in the action. This information can be used for auditing purposes.

‍

New  'CustomFields' endpoints

We have added five new  endpoints:

‍

• List Custom Fields - ^{GET /core/custom_fields}
• Get a Custom Field - ^{GET /core/custom_fields/{id}}
• Create a new Custom Field - ^{POST /core/custom_fields}
• Update a Custom Field - ^{PATCH /core/custom_fields/{id}}
• Delete a Custom Field - ^{PATCH /core/custom_fields/{id}/archive}

These endpoints give you the ability to manage your custom fields. ^{List Custom Fields} lets you retrieve all of the custom fields in your instance, whereas ^{Get a Custom Field} lets you retrieve a specific custom field by its ID. ^{Delete a Custom Field} will in fact archive (as opposed to hard deleting) a custom field you no longer wish to make use of, meaning it is still possible to read it at a later date.

‍

New 'Runbook' endpoint

We have added a new 'Runbook' endpoint:

• Archive a Runbook - ^{POST /core/runbooks/{id}/archive}

This endpoint lets you archive a runbook, removing its visibility and access from your instance once it is no longer required or has served its purpose.

‍

New 'Task' endpoints

We have added two new  endpoints:

‍

• Skip a Task - ^{GET /core/runbooks/{runbook_id}/tasks/{id}/skip}
• Delete a Task - ^{DELETE /core/runbooks/{runbook_id}/tasks/{id}}

These endpoints add to the existing task endpoints, furthering your ability to control and manage tasks by being able to skip or delete a specific one in a runbook.

Other minor changes

• We have added the ^forecast query parameter to the List Streams in a Runbook endpoint. This means the endpoint now has two modes - a conventional mode which only returns attributes related to the streams, and a ‘forecast’ mode which returns additional start and end time information that has been calculated from the stream’s tasks.

‍

Major changes

New  'RoleType' endpoint

We have added a new 'Role Type' endpoint:

‍

• List Role Types - ^{GET /core/role_types}
  

This lets you retrieve all of the role types that are currently enabled in your instance, providing an ID and a description of the role type. You can then use role type IDs when creating, updating or simply just reading roles.

‍

New 'UserApp' endpoints

We have added three new 'UserApp' endpoints:

‍

• List User App Tokens - ^{GET /core/users/{user_id}/user_app_tokens}
• Create a New User App Token - ^{POST /core/users/{user_id}/user_app_tokens}
• Delete a User App Token - ^{DELETE /core/users/{user_id}/user_app_tokens/{id}}‍

These endpoints provide you with the ability to control and manage API access to your Cutover instance. List User App Tokens lets you retrieve all of the user app tokens belonging to a specific user. Create a New User App Token lets you create new tokens per user, and Delete a User App Token lets you delete tokens per user (effectively meaning you can revoke a user’s API access).

‍

New 'Workspace' endpoints

We have added four new 'Workspace' endpoints:

‍

• Create a New Workspace - ^{POST /core/workspaces}
• Update a Workspace - ^{PATCH /core/workspaces/{id}}
• Archive a Workspace - ^{PATCH /core/workspaces/{id}/archive}
• Unarchive a Workspace - ^{PATCH /core/workspaces/{id}/unarchive}
  

These endpoints provide you with the ability to manage your workspaces. Update a Workspace lets you update the name and description of a specified workspace, Archive a Workspace lets you remove visibility and access to a specified workspace once it is no longer required or has served its purpose, while Unarchive a Workspace lets you restore it if it is needed again.

‍

'Changelog' added to your API Portal

‍

We have added a 'Changelog' section to your instance’s API Portal, providing you with a list of all the changes for every API version that we release.

The section is accessed by clicking on My Profile in the bottom-left corner of the app and, under where it says 'View API endpoint documentation with credentials:' in the My Details panel, click either On the Developer Portal or On your API instance. 

This takes you to the ‘Overview’ page, at the top of which sits the ‘Changelog’.

Other minor changes

• We have added the ability to pass ^{custom_field_values} to the Start a Task and Finish a Task endpoints.
• We have added example JSON requests to the documentation for Create a New Task and Create a New User. Previously these areas were blank.
• We’ve ensured the ^last page link is always shown in pagination. Previously it wasn’t showing when you were on the last page itself.

‍