What's changed in the REST API

This topic includes a comprehensive list of updates to the REST API and SDKs by version.

Must read

The following upcoming REST API updates necessitate that you review your existing code and make modifications as necessary.  These updates will be implemented in a future release ofALM Octane, so please prepare now.

Back to top

Version 12.60.52

New entities

More REST API entities (and their fields) are now available: 

  • Program field for Work items and Planning info.

Version 12.60.41


You can now deactivate and reactivate list items, in addition to deprecating them, by updating a list item's activity level.

For details, see Remove an item from an existing list.

Time user last logged in

You can now query on a user's last_login time. For details, see GET: See users that logged in.

Back to top

Version 12.60.35

Data access (Enterprise Edition)

You can now use the REST API to list workspace users' data access.

For details, see GET: See users' data access levels (Enterprise Edition).


You can now filter entities' list values, phases, and metaphases using the values' names. You do not have to look up the logical names for these list values, even though this method is still supported.

This new functionality is available for English queries only. Results are returned in the localized language.

For details, see Cross-filter on lists.

Back to top

Version 12.60.31

New entities

More REST API entities (and their fields) are now available: 

Getting license usage using the REST API (technical preview)

Space admins can now use the REST API to view maximum concurrent license usage by date. For details, see Viewing ALM Octane license usage (technical preview).

Back to top

Version 12.60.16

Track security vulnerabilities (technical preview)

You can now track security vulnerabilities using static code analysis tools other than Fortify on Demand. 

This is done by pushing vulnerability issues that were detected in the code into ALM Octane using the ALM Octane REST API.

For details, see Add vulnerability issues into ALM Octane.

New entities

More REST API entities (and their fields) are now available: 

Back to top

Version 12.60.10


Attaching binary (octent-stream) files is now supported as a technical preview.

For details, see Example: POST request for octet-stream attachments (technical preview).

New entities

More REST API entities (and their fields) are now available: 

  • permissions

Back to top

Version 12.60.4

New public entities

More REST API entities (and their fields) are now publicly available: 

  • metaphases (GET only)

  • user_tags (GET and POST)

  • comments

New client type header

  • Use the new ALM_OCTANE_TECH_PREVIEW header with the value true when sending APIs. This gives you a sneak preview of new APIs that are not yet officially supported.

    For details, see Technical preview resources.

  • The HPE_REST_API_TECH_PREVIEW value for the HPECLIENTTYPE header will soon be deprecated. You can disable, or continue using, this header value by setting the ENABLE_LEGACY_TECH_PREVIEW_CLIENT_TYPE configuration parameter.


Logical names for lists

Lists and their items are assigned logical names, which facilitate easier filtering.

For details on naming lists and their items, see Set up lists.

For details on working with lists using the REST API, see Working with lists.

Back to top

Version 12.55.32

Shared entities (technical preview) 

Management of shared entities is supported using the REST API and OData.

The following table describes the REST API contexts for working with shared and space-level entities.

Understanding the table:

  • The Workspace context column is for isolated space context, or for entities that can also be customized on workspace-level.

  • Shared entities include releases, UDFs, forms, rules, lists, and so on.

  • Space entities include users, API access, and so on.

Entity Workspace context Shared space context
Shared entities





Space entities





Note: Unless indicated otherwise, the documentation and examples in this ALM Octane Developer Help assume the context of workspaces in an isolated space.

Back to top

Version 12.55.25

New public entities

More REST API entities (and their fields) are now publicly available: 

Back to top

Version 12.55.17

New public entities

More REST API entities (and their fields) are now publicly available: 

  • automated_runs

  • taxonomy_category_nodes. This entity represents environmental categories, such as DB, Browser, Distribution, AUT Env, and so on.Only GET operations are supported.

  • taxonomy_item_nodes. This entity represents environmental items that are grouped into categories. For example, the Browser categories has items corresponding to Firefox, Chrome, and so on.

  • taxonomy_nodes. This composite entity contains all taxonomy_category_nodes and taxonomy_item_nodes. Only GET operations are supported.

Back to top

Version 12.55.13

Shared customization and entities

The following table describes the current level of REST API support for shared customization and entities.

Type Isolated Space Shared Space
Customization, such as UDFs, forms, rules, lists, and so on
Entities, such as releases and teams

The documentation and examples in this ALM Octane Developer Help assume the context of an isolated space.

Back to top

Version 12.55.9

New public entities

More REST API entities (and their fields) are now publicly available: 

  • requirements

  • requirement_documents

  • requirement_folders

  • requirement_roots

  • teams

  • team_sprints

Set space configuration parameters

The space admin can set configuration parameters for spaces using the REST API. For an example, see Activating basic authentication by the space admin.

Back to top

Version 12.55.8

Aliases and deprecation

New names (aliases) for deprecated API resources are now supported. This means that you can choose to use the new names for APIs, or the existing names, without breaking your existing code.

While both names are currently supported, we suggest you plan your switch to the alias name in the near future.

You can also see a list of deprecated resources and their aliases under Changes in behavior.

Back to top

Changes in behavior

We have made some improvements to the REST API. These improvements may require updates to your existing REST API calls.

The table below lists the changes made by version.

Tip: For the most up-to-date information, see Retrieving metadata and use the Interactive API client.

Version Entity Field Item or attribute Old New
12.60.47 work items NA user_items Private Technical preview
actual_story_points Public
12.60.41 list_nodes NA activity_level NA 3 (inactive)
1 (inactive) 1 (deprecated)
12.60.16 NA NA vulnerabilities custom resource NA Technical preview
12.60.4 stories



NA Technical preview Public
request header NA ALM_OCTANE_TECH_PREVIEW NA True / false
request header NA HPECLIENTTYPE HPE_REST_API_TECH_PREVIEW Value being deprecated.
12.55.32 teams team_members NA Private Public
Shared customization NA shared_area Did not exist. shared_area
12.55.17 run testing_tool value change StormRunner StormRunner Load


NA NA Private Public
taxonomy_category_nodes NA NA Private Public
taxonomy_item_nodes NA NA Private Public
12.55.9 users site_admin <deprecated> site_admin Use roles instead.
12.55.8 product_area product_area <deprecated> product_area application_module
test product_area <deprecated> product_area application_module
workspace_user activity_level <deprecated> activity_level user_activation_status
test_suite_link_to_test subtype required Did not exist. subtype
workspace name unique false true
<All> attachments <PUT operation deprecated> Supported. Not supported.
<All> comments <POST and PUT operations deprecated> Supported, as technical preview. Not supported.
12.55.7 run runs_in_suite editable true


steps_num NA This field was public. This field is no longer available.
native_status NA This field was public. This field is no longer available.
run_suite runs_in_suite editable true


workspace_user password inBusinessRule true


required false true
uid unique false true
isFinal false true
activity_level sortable true


email unique false


ldap_dn inBusinessRule true


Note: Remember that ID values for all entities are strings, even if the values they contain are numeric. We recommend that you check your REST API calls to make sure your code does not process ID values as numbers.

12.55.4 User-defined fields are no longer returned by default when performing GET operations.
12.53.20 defect severity required false true

Back to top

See also: