Archive the asset container

POST /v2/asset_containers/archive

Archive the assets database of the asset container.<br/><br/>Archiving the assets database of not used asset containers helps saving storage and computing resources of the database, therefore reduce the footprint of CAMS.The information stored in the archived asset containers will not be accessible until the asset containers are restored.

Request

Request Body

CatalogArchiveCatalogRequest

Archive request

comment

string

Path Parameters

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

202 - Accepted

The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.

failure

CatalogErrorContainerModel

The details of the error.

400 - Bad Request

401 - Unauthorized

403 - Forbidden

The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.

failure

CatalogErrorContainerModel

The details of the error.

400 - Bad Request

401 - Unauthorized

403 - Forbidden

duplicate_action

string

Action to take if duplicate assets are found for a given asset

default_duplicate_strategy

string

Default duplicate detection strategy for assets of types that do not have duplicate detection strategy defined

duplicate_strategies

array

Duplicate detection strategies of assets with specified asset types in this catalog/project/space

reporting_authorized

boolean

Authorize reporting in this catalog

default_purge_on_delete

boolean

Whether assets has to be purged on delete

default_purge_after_days

integer

Days after which assets has to be purged after soft delete

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

Replace or create configurations

PUT /v2/asset_containers/configurations

Replace the configurations of a catalog/project/space or create the configurations if they do not exist.

Request

Request Body

CatalogAssetContainerConfiguration

Configurations

duplicate_action

string

Action to take if duplicate assets are found for a given asset

default_duplicate_strategy

string

Default duplicate detection strategy for assets of types that do not have duplicate detection strategy defined

duplicate_strategies

array

boolean

Authorize reporting in this catalog

default_purge_on_delete

boolean

Whether assets has to be purged on delete

default_purge_after_days

integer

Days after which assets has to be purged after soft delete

400 - Bad Request

401 - Unauthorized

403 - Forbidden

The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.

failure

CatalogErrorContainerModel

The details of the error.

202 - Accepted

The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.

failure

CatalogErrorContainerModel

The details of the error.

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

List all asset lists defined for an account

GET /v2/asset_lists

Retrieve a paginated list of asset lists defined for an account.

Request

Path Parameters

Query Parameters

query

string

Query to retrieve a paginated list of asset list metadatas for which the request user has permission to view.<br/><br/>Search query in Common Expression Language, with special characters encoded. For example, & is %26.<br/><br/>Examples of query parameters:<br/>* id<br/>* type<br/>* state<br/>* access_control.owner<br/>* created_at<br/>* last_updated_at

start

string

Start token for pagination

limit

integer

Search result limit

sort

This parameter can be repeated to add additional sort fields. <br><br>Default: null

Examples of sort fields (these are case insensitive):

created_at
-created_at
last_updated_at
-last_updated_at

Response

200 - OK

limit

integer

The limit on the number of results returned.

total_count

integer

The total count on the number of results returned, accounting for filtering but not pagination.

first

CatalogBaseCollectionPage

type

string

The type (primary attribute) of the asset

container

object

The container for the asset ('catalog', 'project' or 'space').

items

array

The items in the asset list.

Response

Errors thrown during the operation

Delete asset lists

DELETE /v2/asset_lists

Deletes asset lists based on a query in Common Expression Language format.

Request

Path Parameters

Query Parameters

query

string

Query to delete asset lists for which the request user has permission.<br/><br/>Search query in Common Expression Language, with special characters encoded. For example, & is %26.<br/><br/>Examples of query parameters:<br/>* id<br/>* type<br/>* state<br/>* access_control.owner<br/>* created_at<br/>* last_updated_at

Response

Errors thrown during the operation

Retrieve an asset list identified by ID

GET /v2/asset_lists/{asset_list_id}

Retrieves the metadata of an asset list of a given identified by ID.

Request

Response

Errors thrown during the operation

Delete an asset list identified by ID

DELETE /v2/asset_lists/{asset_list_id}

Deletes an asset list identified by ID. The user must have permission to perform this action.

Request

Response

Errors thrown during the operation

Update the metadata of an asset list

PATCH /v2/asset_lists/{asset_list_id}

Use this API to update the asset list metadata. Specify patch operations using http://jsonpatch.com/ syntax.

Fields that can be patched:

/name
/description
/type
/state (Approvers and Functional users only)
/message (Approvers and Functional users only)

Note: The ownership cannot be modified after creation.

Request

Request Body

JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.

Response

Errors thrown during the operation

Start token for pagination

limit

integer

Search result limit

sort

This parameter can be repeated to add additional sort fields. <br><br>Default: null

Examples of sort fields (these are case insensitive):

created_at
-created_at
last_update_time
-last_update_time

Response

200 - OK

limit

integer

The limit on the number of results returned.

total_count

integer

The total count on the number of results returned, accounting for filtering but not pagination.

first

CatalogBaseCollectionPage

GET /v2/asset_lists/{asset_list_id}/items/{asset_list_item_id}

Retrieves an item identified by ID of an asset list identified by ID.

Request

Response

Errors thrown during the operation

Update an asset list item

PATCH /v2/asset_lists/{asset_list_id}/items/{asset_list_item_id}

Use this API to update an asset list item. Specify patch operations using http://jsonpatch.com/ syntax.

Fields that can be patched:

/properties

Request

Request Body

JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.

Response

Errors thrown during the operation

Searches for relationship types

GET /v2/asset_relationship_types

Searches for relationship types using various criteria. The query parameters here provide filters for the relationship types that are returned in the result. If no query parameters are provided, the result will include all relationship types that are visible to your bss account. If an asset container is specified, the results are limited to relationship types where at least one end can be used with the specified asset container. This is the case if the relationship end either has no declared asset container (for example because the end references a global asset type or is untyped) or if the end has an asset container that is the same as the asset container specified. If a `relname` filter is specified, the results are limited to relationship types where at least one end has a relationship name in the list. In order to see relationship types where at least one end is in the container asset type(s), you must either belong to the container's BSS account or have at least editor permission on the container. All users have permission to see global relationship types.

Limit the relationship types based on the item types:

If the `asset_type` is specified, the results are limited to relationship types where at least one end is either untyped or is in the specified asset type list.
If both `asset_type` and `related_asset_type` are specified, the results are limited to relationship types where both ends are untyped, or where one end is in the specified asset type list and the other end has the specified asset type list.
If the `artifact_type` is specified, the results are limited to relationship types where at least one end is either untyped or is in the specified artifact type list.
If both `artifact_type` and `related_asset_type` are specified, the results are limited to relationship types where both ends are untyped, or where one end is in the specified artifact type list and the other end has the specified asset type list.
If the `asset_type` or `related_asset_type` is set to `*#_column`, the results are limited to relationship types where one end can be used with any supported column type (currently limited to `data_asset` columns)
If the item type is set to `*`, the results are limited to relationship types where one end can be used with any asset type or any artifact type.

Note: In CP4D environments there is just one global bss account, so all relationship types are always visible to all users.

Request

Path Parameters

Related Asset Type Name(s). This parameter can only be set when either asset_type or artifact_type is also set.

When asset_type is set, this limits the results to only relationship types that have an endpoint with the specified asset type and the other endpoint with this specified asset type.

When artifact_type is set, this limits the results to only relationship types that have an endpoint with the specified artifact type and the other endpoint with this specified asset type.

limit

integer

limit to use when finding relationship types

bookmark

string

Optional bookmark to use when finding relationship types.

relname

array

Relationship name(s). This limits the results to relationship types that have an endpoint with the specified name. The parameter should be repeated for each allowed relationship name.

default_display_name

array

Default display name(s). This limits the results to relationship types that have an endpoint with the specified name. The parameter should be repeated for each allowed relationship name.

scope

string

Specifies the scope of the relationship types which can be (GLOBAL/BSS_ACCOUNT). If GLOBAL - it returns all types scoped to Global.If BSS_ACCOUNT - it returns all types scoped to BSS_ACCOUNT.If query parameter is omitted, it returns all.

bss_account_id

string

If specified, the results are limited to relationship types that can be accessed by the specified BSS account. If `container_id` is also specified, the catalog's BSS account must be the same as the BSS account specified here.

If `bss_account_id` is not specified and the API is called with an accredited service ID access token, then there is no filtering of the results based on BSS account.

If `bss_account_id` is not specified, and the API is called with a regular user (i.e. non-service ID) access token, then the result depends on whether `container_id` is specified. If `container_id` is specified, then the result includes global relationship types and account-scoped relationship types for the container's BSS account. If `container_id` is not specified, then the result includes global relationship types, and account-scoped relationship types for all of the user's BSS accounts.

Response

200 - Success

resources

array

relationship types that match the search criteria

total_rows

integer

total number of rows in the search result

object

URL to fetch the next page of search results

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

429 - Too Many Requests

Specifying the Type

The combination of `container_type`, `container_id`, and `containing_asset_type(s)` control what asset types can be used at each end of the relationship. The asset type can be a global asset type, an account-level asset type, a container-scoped asset type, or any asset type.

Global Asset Type

To define a relationship end for a global asset type, the `containing_asset_type(s)` field must be set to the name of the asset type and the `container_id` must be omitted. In this case, the relationship end can only be used with the specified global asset type. If the `container_type` field is set when using a global asset type, it is ignored.

Account Level Asset Type

To define a relationship end for an account-level asset type, the `containing_asset_type(s)` field must be set to the name of the asset type and the `container_id` must be omitted. In addition, the `bss_account_id` query parameter must be set to the bss account that owns the account-level asset type. In this case, the relationship end can only be used with the specified account-level asset type. If the `container_type` field is set when using an account-level asset type, it is ignored.

Container-Scoped Asset Type

The relationship mechanism allows relationship ends to be restricted to an asset type defined in a specific catalog, project, or space. To do this, the `containing_asset_type(s)`, `container_type`, and `container_id` fields must all be set.

Artifact Type

To define a relationship end for an governance artifact type, the `containing_artifact_type(s)` field must be set to the name of the artifact type and the `container_id` must be omitted. The on_delete field can only set to IGNORE on both ends

Column Type

To define a relationship end for a column type, the `containing_asset_type(s)` field must be set in the format of `<asset_type>#_column`. When `*#_column` is specified, the relationship end can be used with any supported column type. Currently, only `data_asset` columns are supported. The `on_delete` field can only set to `IGNORE` on both ends

Any Type

To allow a relationship end to be used with any asset type, the `containing_artifact_type(s)`, `containing_asset_type(s)` and `container_id` fields for the relationship end must be omitted. In this case, the relationship end can be used with any asset type, any artifact type, and any supported column type in any container. If the `container_type` field is set, it will be ignored.

Note: Cannot have `containing_artifact_type(s)` specified in both ends

Specifying the Relationship Type Scope

A relationship type can either be global or be scoped to a BSS account.

A relationship type can be explicitly scoped to a specific bss account using the `bss_account_id` query parameter. When a relationship type is scoped to a bss account, all specified asset containers and account-level asset types must belong to that bss account. If either endpoint for the relationship type has a specific asset container, the relationship type is automatically scoped to the bss account for the asset container. Account scoped relationship types can only be created if the user either belongs to the same bss account or is an administrator of all asset containers in the relationship type definition.

By default, if neither end of the relationship type specifies an asset container, the relationship type is created in the global scope and is accessible to all users. Only service ids with permission to create global asset types are allowed to create globally scoped relationship types. It is possible to scope a relationship type where neither end has an asset container to a specific BSS account. To do this, you must set the `bss_account_id` query parameter when creating the relationship type. The bss account must be set to a bss account that you have access to. In that case, the relationship type will be created, but its use will be restricted to asset containers associated with that bss account.

By default, on_delete is set to `IGNORE` if it is not specified

Note that in CP4D environments, there is only one bss account (`999`). As a result, in that context relationship types scoped to a specific BSS account are effectively global.

Cascading clone/publish/promote to Referenced Assets

The following flags control how related assets are processed when an asset is copied using the `deepcopy` endpoint

Option	Allowed Value	Default	Description
on_clone	CASCADE/IGNORE	IGNORE	If `CASCADE`, `deepcopy` from a catalog to a project causes the referenced assets to be copied as well
on_publish	CASCADE/IGNORE	IGNORE	If `CASCADE`, `deepcopy` from project to a catalog causes the referenced assets to be copied as well
on_promote	CASCADE/IGNORE	IGNORE	If `CASCADE`, `deepcopy` from a project to a space causes the referenced assets to be coped as well

Creates an asset relationship type

POST /v2/asset_relationship_types

Use this API to create an asset relationship type. The type definition consists of two endpoints which specify the two ends of a bidirectional relationship. The endpoints define the name of the relationship at each end, and the qualified asset type or the qualified artifact type that contains the relationship endpoint. The names of the relationships that can be used with any given asset type or artifact type are required to be unique. If the qualified asset type and the qualified artifact type are omitted, that end can be used with any asset type and any artifact type in any container.

Specifying the Type

Global Asset Type

Account Level Asset Type

Container-Scoped Asset Type

Artifact Type

Column Type

Any Type

Note: Cannot have `containing_artifact_type(s)` specified in both ends

Specifying the Relationship Type Scope

A relationship type can either be global or be scoped to a BSS account.

By default, on_delete is set to `IGNORE` if it is not specified

Note that in CP4D environments, there is only one bss account (`999`). As a result, in that context relationship types scoped to a specific BSS account are effectively global.

Cascading clone/publish/promote to Referenced Assets

The following flags control how related assets are processed when an asset is copied using the `deepcopy` endpoint

Option	Allowed Value	Default	Description
on_clone	CASCADE/IGNORE	IGNORE	If `CASCADE`, `deepcopy` from a catalog to a project causes the referenced assets to be copied as well
on_publish	CASCADE/IGNORE	IGNORE	If `CASCADE`, `deepcopy` from project to a catalog causes the referenced assets to be copied as well
on_promote	CASCADE/IGNORE	IGNORE	If `CASCADE`, `deepcopy` from a project to a space causes the referenced assets to be coped as well

Request

Request Body

CatalogRelationshipTypeEntity

Relationship Type request body

end1

Required *

object

First relationship type endpoint (order is not important)

default_display_name

Required *

string

Default display name for this end of the relationship. This is what will be shown in the UI.

localized_display_name

object

Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")

relationship_name

Required *

Second relationship type endpoint (order is not important)

default_display_name

Required *

string

Default display name for this end of the relationship. This is what will be shown in the UI.

localized_display_name

object

Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")

relationship_name

Required *

string

Internal, non-translated, name for this end of the relationship. This becomes part of the path in the APIs for manipulating and querying relationship types.

containing_artifact_type

string

Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.

containing_artifact_types

array

on_delete

string

on_clone

string

containing_asset_type

string

Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.

flags

object

Set of flags. These flags determine the relationship type's behavior

description

string

Description of the relationship type

Path Parameters

Query Parameters

bss_account_id

string

This parameter forces the relationship type to be scoped to the specified bss account. It allows the creation of an account-scoped relationship type where both ends are either untyped, or are global asset types. It is required if the relationship type entity references any account-level asset types. An account-scoped relationship type is only visible to users in the BSS account for the relationship type. If the query parameter is unset, such relationships will be global in scope and can only be created if the user has permission to create a global asset type. Note: the BSS account can also be set via an impersonation header. If it is set in both places, the `bss_account_id` query parameter has precedence. This parameter is not required if either end of the relationship type has a catalog asset type. If it is set for a relationship type that has a catalog asset type, it must be the same as the BSS account for the catalog.

Response

201 - Created

metadata

object

relationship type metadata

entity

object

relationship type entity

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

429 - Too Many Request

For a column type:

set `asset_type` as `<asset_type>#_column`
if `asset_type` is specific to a container (catalog, space, or project), then set a container ID parameter as appropriate (`catalog_id`, `space_id`, `project_id`).

For a governance artifact type:

set `artifact_type`. This parameter should be repeated for each allowed artifact type

Searches for relationship type ends

POST /v2/asset_relationship_types/search_ends

Find relationship type ends that can be used with an asset type or artifact type. This API supports finding relationship type ends that use global or catalog asset types.

For an asset type:

set `asset_type`. This parameter should be repeated for each allowed asset type
All asset types in the list must either be global/account level asset types or be scoped to the asset container specified by the `catalog_id`, `project_id`, or `space_id`.

For a column type:

set `asset_type` as `<asset_type>#_column`
if `asset_type` is specific to a container (catalog, space, or project), then set a container ID parameter as appropriate (`catalog_id`, `space_id`, `project_id`).

For a governance artifact type:

set `artifact_type`. This parameter should be repeated for each allowed artifact type

Request

Path Parameters

Optional bookmark to use when finding relationship type ends.

orderby

array

orderby. This parameter can be repeated to add additional sort fields. <br><br>Default: relationship_display_name_asc

Supported sort fields (these are case insensitive):

relationship_name_asc
relationship_name_desc
relationship_display_name_asc
relationship_display_name_desc
create_time_asc
create_time_desc

relationship_names

array

Limits results to only include the specified relationships. By default, all relationship type ends which match the other search criteria are included. Repeat the query parameter to specify multiple relationship names.

Response

200 - Success

object

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

429 - Too Many Requests

Finds relationship types that are used by an asset, column or governance artifact

POST /v2/asset_relationship_types/search_used_ends

Finds relationship types that are used by an asset, column or a governance artifact. This API only returns the first page of results. It does not accept a bookmark. Any additional pages of results must be fetched using the next page url included in the response.<br/></br>You can refer to the options in the response to get the full list of relationship names.

Request

Path Parameters

Includes a list of the related asset types and artifact types in the result. This option adds overhead, so enable it only if the related type information is needed.

orderby

array

orderby. This parameter can be repeated to add additional sort fields. <br><br>Default: relationship_display_name_asc

Supported sort fields (these are case insensitive):

relationship_name_asc
relationship_name_desc
relationship_display_name_asc
relationship_display_name_desc
create_time_asc
create_time_desc

Response

200 - Success

object

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

429 - Too Many Requests

DELETE /v2/asset_relationship_types/{relationship_type_id}

Deletes a relationship type.

Request

Path Parameters

relationship_type_id

Required *

string

Query Parameters

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

429 - Too Many Request

Add a display name to an endpoint without an existing `localized_display_name` element:

``` [ { "op": "add", "path": "/end2/localized_display_name", "value": {" "en-us": "English Display Name" } } ] ```

Add a display name to an endpoint with an existing `localized_display_name` element:

``` [ { "op": "add", "path": "/end2/localized_display_name/en-gb", "value": "British Display Name", } ] ```

Change localized display name for en-gb in end2:"

``` [ { "op": "replace", "path": "/end2/localized_display_name/en-gb", "value": "New British Display Name" } ] ```

Remove localized display name for en-gb rom end1:

``` [ { "op": "remove", "path": "/end1/localized_display_name/en-gb" } ] ```

Add a relationship option override, replace an existing relationship option override, delete an existing relationship option override:

``` [ { "op": "add", "path": "/end1/option_overrides/-", "value": { "this_asset_type": "ibm_bi_report", "other_asset_type": "ibm_bi_report_query", "on_delete": "CASCADE", "on_publish": "IGNORE", "on_promote": "CASCADE", "on_clone": "IGNORE" } }, { "op": "replace", "path": "/end1/option_overrides/1/on_delete", "value": "CASCADE" }, { "op": "add", "path": "/end1/option_overrides/1/on_promote", "value": "IGNORE" }, { "op": "remove", "path": "/end1/option_overrides/1/on_promote" } [ ``` ">

Patches a relationship type

PATCH /v2/asset_relationship_types/{relationship_type_id}

Updates an existing relationship type. The patch body must be an array of json patch operations as defined in RFC 6902.

The following fields can be patched in each relationship type endpoint:

`default_display_name` (value can be changed but not removed)
`localized_display_name` (values can be added, changed, and removed)
`on_delete` (value can be added, removed, or deleted)

Relationship types where at least one endpoint is a catalog asset type can be patched either by an admin member of the catalog, or by a user in the catalog's BSS account. Global relationship types can only be patched by a user with permission to create global asset types.

It is important to note that the patch specifies updates to apply the current json representation of the relationship types. When specifying an add/replace/remove patch operation, all of parent elements in the path must already exist. In particular, if the relationship type endpoint was originally created without a `localized_display_name` element, that element needs to be created by the patch operations.

Here are some examples of patches that can be applied:

Add a display name to an endpoint without an existing `localized_display_name` element:

``` [ { "op": "add", "path": "/end2/localized_display_name", "value": {" "en-us": "English Display Name" } } ] ```

Add a display name to an endpoint with an existing `localized_display_name` element:

``` [ { "op": "add", "path": "/end2/localized_display_name/en-gb", "value": "British Display Name", } ] ```

Change localized display name for en-gb in end2:"

``` [ { "op": "replace", "path": "/end2/localized_display_name/en-gb", "value": "New British Display Name" } ] ```

Remove localized display name for en-gb rom end1:

``` [ { "op": "remove", "path": "/end1/localized_display_name/en-gb" } ] ```

Add a relationship option override, replace an existing relationship option override, delete an existing relationship option override:

Request

Request Body

 JSON array of patch operations as defined in RFC 6902.
 Note: Any ‘~’ characters need to be escaped as ~0 in the path field.
 Any ‘/’ characters need to be escaped as ~1 in the path field.
 For example, in &#x60;{&quot;foo/&quot; : {&quot;~bar&quot; : &quot;value&quot;}}&#x60;, the path for &#x60;&quot;~bar&quot;&#x60; is &#x60;&quot;/foo~1/~0bar&quot;&#x60;.

Path Parameters

relationship_type_id

Required *

string

relationship_type_id

Query Parameters

Response

200 - Relationship type was successfully patched

metadata

object

relationship type metadata

entity

object

relationship type entity

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

429 - Too Many Requests

List all asset types defined for an account, catalog, project or space.

GET /v2/asset_types

Get all asset types in an account, catalog, project or space. Custom properties added/updated at the account level asset types can only be fetched if bss_account_id parameter is passed

Request

Path Parameters

This parameter allows to retrieve asset types which can be used only as attributes and are user defined. You can provide either a true or a false. At a time, either permits_decorators or custom_attributes can be true.

locale

string

Language code, such as default, en, etc.

Response

200 - OK

resources

array

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Creates an asset type in an account, catalog, project or space.

POST /v2/asset_types

Creates an asset type in account, catalog, project or space.

Request

Request Body

CatalogCreationType

Asset Type request body

description

string

Asset type description

fields

Required *

array

Fields that are indexed if present in the asset.

external_asset_preview

object

External Asset Preview. Clients can make use of this to render content appropriately for this asset type.

base_client_url

Asset type name

allow_decorators

boolean

Path Parameters

Query Parameters

catalog_id

string

This parameter allows the creation of a catalog-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.

project_id

string

This parameter allows the creation of a project-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.

space_id

string

This parameter allows the creation of a space-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.

bss_account_id

string

This parameter allows the creation of an account-scoped asset type. May be different than account of user specified in Bearer token. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.

Response

Define the behavior only if this asset type is used as an attribute.

attribute_only

401 - Unauthorized

403 - Forbidden

409 - Conflict

429 - Too Many Request

Retrieves an asset type of a given name.

GET /v2/asset_types/{type_name}

Retrieves an asset type of a given name. Custom properties added/updated at the account level asset types can only be fetched if bss_account_id parameter is passed

Request

Path Parameters

type_name

Required *

string

array

This parameter can have one or more values as below:

GLOBAL - return asset type in global scope
BSS_ACCOUNT - return asset type in account scope
CONTAINER - return asset type in catalog/ project/ space scope

If no value is provided, the default value is taken as null, and the asset type with the highest search scope is returned. A combination of more than one search scope is also valid. In this case, an asset type with the highest search scope from the given scopes will be returned.

Response

Define the behavior only if this asset type is used as an attribute.

boolean

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

Replace an asset type

PUT /v2/asset_types/{type_name}

Replace asset attributes for the given asset type or create a new asset type if the given asset type does not exist.

Request

Request Body

CatalogUpdateType

Asset Type request body

description

string

Asset type description

fields

Required *

array

Fields that are indexed if present in the asset.

external_asset_preview

object

External Asset Preview. Clients can make use of this to render content appropriately for this asset type.

base_client_url

remove_on_copy

boolean

Remove the attribute when cloning, publishing or promoting the asset

attribute_only

boolean

data_protection

object

Asset type properties and attachments that should be filtered out for users without data access

all_fields

boolean

Indicates if all fields of the asset type are protected. If 'all_fields' is true, then 'fields' is ignored.

all_attachments

boolean

Indicates if all attachments of the asset type are protected. If 'all_attachments' is true, then 'attachment_types' is ignored.

field_search_paths

string

Asset Type name (eg: data_asset)

Query Parameters

catalog_id

string

This parameter allows creating or updating a catalog-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.

project_id

string

This parameter allows creating or updating a project-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.

space_id

string

This parameter allows creating or updating a space-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.

bss_account_id

string

This parameter allows creating or updating an account-scoped asset type. May be different than account of user specified in Bearer token. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.

Response

Define the behavior only if this asset type is used as an attribute.

attribute_only

401 - Unauthorized

403 - Forbidden

404 - Not Found

409 - Conflict

429 - Too Many Request

500 - Internal Server Error

Deletes an asset type

DELETE /v2/asset_types/{type_name}

Deletes an asset type in given account or container. Note that, deletion of an account scope asset type or a container scope asset type triggers background clean up of assets:<br/><ul><li>Assets of this type are deleted.</li><li>And in case of other assets, attributes of this type are removed.</li></ul>

Request

Path Parameters

type_name

Required *

string

Asset Type name (eg: data_asset)

Query Parameters

catalog_id

string

This parameter allows creating or updating a catalog-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.

project_id

string

This parameter allows creating or updating a project-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.

space_id

string

This parameter allows creating or updating a space-scoped asset type. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.

bss_account_id

string

Response

200 - OK

202 - Accepted

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

409 - Conflict

429 - Too Many Request

500 - Internal Server Error

Finds relationship types for an asset type

GET /v2/asset_types/{type_name}/relationships

Finds relationship types that originate from a given asset type. This API supports limiting the results to a specific set of relationship types as well as providing pagination and sorting options. It also supports finding relationship types that use both global and catalog asset types.<br>This API is deprecated - use `POST /v2/asset_relationship_types/search_ends` instead

Request

Path Parameters

type_name

Required *

string

array

orderby. This parameter can be repeated to add additional sort fields. <br><br>Default: relationship_display_name_asc

Supported sort fields (these are case insensitive):

relationship_name_asc
relationship_name_desc
relationship_display_name_asc
relationship_display_name_desc
create_time_asc
create_time_desc

relname

array

Limits results to only include the specified relationships. By default, all relationship types for the asset type are included. Repeat the query parameter to specify multiple relationship names.

Response

200 - Success

object

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

429 - Too Many Requests

Search for asset metadata within assets of the specified type

POST /v2/asset_types/{type_name}/search

Use this API to search for assets of the generic asset type (asset) or any specific asset type in a Catalog, Space, or Project.

The request body must contain a `query` field, which specifies a Lucene query to search for assets on indexed fields.<br/> See <b>Searchable Asset and Attachment Fields</b> below for the list of fields that can be searched in the query.<br/>

If `query` contains no selection criteria (`":"`), then the result includes all assets that are instances of the type specified in the `type_name` path parameter, including assets whose primary asset type (i.e. its `metadata.asset_type` value) is that type, and assets that have an attribute of that type.<br/> To filter out assets whose primary type does not match the `type_name` parameter, the query must include an `asset.asset_type:{type_name}` predicate.

The query results can be sorted by specifying a `sort` field in the request with format `field<sort_type>`. The `sort_type` can be either `number` or `string` (e.g. `"sort" : "asset.name<string>"`).

<b> Search With Pagination </b>

The `limit` request body field can be specified to limit the number of assets in the search results.<br/> The default `limit` is 200. The maximum `limit` value is 200, and any greater value is ignored.<br/>

Sample Request Body: ``` { "query" : "asset.name:Asset*", "limit" : 2, "sort" : "asset.name<string>" } ```

Response: ``` { "next": { "bookmark": "g1AAAXXXXXXXX", "query" : "asset.name:Asset*", "limit" : 2, "sort" : "asset.name<string>" }, "results": [ { ..asset 1... }, { ..asset 2... } ], "total_rows": 3 } ```

When more search results are available, then the response will contain a `next` JSON object - `next` contains `bookmark` along with original query which needs to be returned to retrieve the next page of results. To paginate through the entire result set, the request should be re-executed with the `bookmark` from the `next.bookmark` value of the previous response until there is no `next` object in the response (note that this response may contain an empty `results` array).

Sample request body to get the next page of results: ``` { "bookmark": "g1AAAXXXXXXXX", "query" : "asset.name:Asset*", "limit" : 2, "sort" : "asset.name<string>" } ```

<b>Searchable Asset and Attachment Fields</b>

The following asset and attachment fields can be searched in the query - note that type `<string>` or `<number>` only needs to be added for use in the `sort` request field:<br/> `asset.asset_attributes<string>`<br/> `asset.asset_category<string>`<br/> `asset.asset_state<string>`<br/> `asset.asset_type<string>`<br/> `asset.catalog_id<string>`<br/> `asset.created_at<string>`<br/> `asset.delete_timestamp<string>`<br/> `asset.description<string>`<br/> `asset.memberIds<string>`<br/> `asset.editor_id<string>`<br/> `asset.viewer_id<string>`<br/> `asset.member_or_owner_id<string>`<br/> `asset.memberGroupIds<string>`<br/> `asset.editor_group_id<string>`<br/> `asset.viewer_group_id<string>`<br/> `asset.member_or_owner_group_id<string>`<br/> `asset.mode<number>`<br/> `asset.name<string>`<br/> `asset.owner_id<string>`<br/> `asset.owner_group_id<string>`<br/> `asset.project_id<string>`<br/> `asset.rating<number>`<br/> `asset.resource_key<string>`<br/> `asset.identity_key<string>`<br/> `asset.source_asset_id<string>`<br/> `asset.source_catalog_id<string>`<br/> `asset.source_project_id<string>`<br/> `asset.source_space_id<string>`<br/> `asset.source_system<string>`<br/> `asset.source_system_asset_id<string>`<br/> `asset.source_system_created_at<string>`<br/> `asset.source_system_id<string>`<br/> `asset.source_history_asset_id<string>`<br/> `asset.source_history_system_id<string>`<br/> `asset.space_id<string>`<br/> `asset.tags<string>`<br/> `attachment.connection_id<string>`<br/> `attachment.connection_path<string>`<br/> `attachment.name<string>`<br/> `attachment.object_key<string>`<br/>

Request

Request Body

CatalogCatalogSearch

Search Criteria. The "include" field in the request body is a list of asset sections to include in the search results, values are comma-separated and the supported values are "entity" or "entity,attachments".

query

Required *

string

Lucene query

type_name

Required *

string

string

Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.

Response

200 - OK

CatalogCatalogSearch

Catalog Search Model

total_rows

integer

results

array

400 - Bad Request

401 - Unauthorized

403 - Forbidden

Get the status of an account scope or global scope asset type.

GET /v2/asset_types/{type_name}/status

Retrieves an account scope or global scope status, If bss_account_id is not provided, api will try to retreive status of an asset type at global level if present.

Request

Path Parameters

type_name

Required *

string

Asset Type name (eg: account_type)

Query Parameters

bss_account_id

string

This parameter allows retrieving status of an account-scoped asset type. May be different than account of user specified in Bearer token.

Response

200 - OK

name

string

status

string

303 - See Other

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

Create an asset

POST /v2/assets

Use this API to create an asset in catalog or project. Assets contain information about the contents of your data and how to access the data. You store asset metadata in a catalog and add collaborators from your organization to analyze data. Your data can reside in a variety of sources. For example, you can keep your data in your existing on-premises data sources, cloud data services, or streaming data feeds. By adding connection information to these remote sources in the catalog, you can allow other catalog users to access the data with the stored credentials. Alternatively, you can copy a snapshot of the remote data into the catalog's encrypted cloud storage.<br/>All asset types have a common set of properties. Some asset types have additional properties.<br/>When you add an asset to a catalog, you specify these common properties:

The asset name and an optional description. The name can only contain letters, numbers, underscore, dash, space, and period. The name can't be only blank spaces.
Privacy. You can choose to restrict access to the asset with the privacy level and asset membership.
- Public = Default. No restrictions on finding or using the asset.
- Private = Only asset members can find or use the asset.
Members. The catalog collaborators can be added as members of the asset. Members are important if you restrict access to the asset. When you create an asset, you are the owner (and implicitly a member) of it. Members can be set in metadata/rov/collaborator_ids or metadata/rov/member_roles, but not both. Members set in metadata/rov/member_roles are given an explicit set of roles. Members can have up to two roles: OWNER and either EDITOR or VIEWER. Only service ids can assign the OWNER role. The request to add the OWNER role is ignored for other callers. Asset members with the EDITOR or VIEWER role must also be members of the catalog. Members set in metadata/rov/collaborator_ids are automatically assigned a role based on their role in the catalog.
Tags. Metadata that makes searching for the asset easier. Tags can contain only letters, numbers, underscores, dashes, and the symbols # and @.

Request

Request Body

CatalogAsset

Asset metadata

metadata

CatalogAssetMetadata

AssetMetadata Model

name

Required *

string

Choose Any Name for your Asset

description

string

Required *

string

source_system

object

Source System Info

child_source_systems

array

source_system_history

array

History of external repository assets that were the source of an imported/synced/rehomed asset.

entity

Required *

object

attachments

array

Path Parameters

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

duplicate_action

string

Action to take if the call would result in a duplicate asset. `IGNORE` means the call will ignore the duplicate and create a new asset. `REJECT` means the call will fail and no asset will be created. `UPDATE` means the best matched duplicate will be updated with the incoming changes according to the predefined rules. `REPLACE` means the best matched duplicate will be overwritten with the input values according to the predefined rules. No value means the duplicate_action specified in catalogs/projects/spaces will be used.

hide_deprecated_response_fields

boolean

Response

201 - Created

metadata

CatalogResponseAssetMetadata

entity

object

href

string

attachments

CatalogAttachment

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get one or more assets.

GET /v2/assets/bulk

Use this API to retrieve one or more assets located in catalog or project or space. Access to an asset is controlled by a combination of the privacy level and the members of the asset. For a governed catalog, data assets are protected from unauthorized access by the governance policies that are defined in Data Governance. Data assets in ungoverned catalogs are not subject to governance policies.<br/><br/>Response includes, for each asset, asset ID, status, HTTP status and, if no errors, asset details & relationship count or list of errors. For example:

``` { "resources":[ { "asset_id":"cf38d92c-eb55-462e-89bf-cdb9fe67f0b7", "status":"success", "http_status":200, "asset":{...}, "relationship_count":2 }, { "asset_id":"c6650020-3176-4d67-8fbe-5a19ba1c2c7e", "status":"failed", "http_status":404, "errors":[ ... ] }, ... ] } ```

Request

Path Parameters

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

asset_ids

Required *

string

Comma separated list of asset IDs; maximum of 20. For assets with revisions, an optional revision number can be specified using colon character in the form of '<asset id>:<revision>,<asset id>,...'. Revision numbers are non-zero positive numbers likes 1, 2, 3 etc.

allow_metadata_on_dpr_deny

boolean

Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.

include

string

The parameter `include` is deprecated, please use `exclude` instead

exclude

string

Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.

hide_deprecated_response_fields

boolean

include_relationship_count

boolean

Whether to include per-asset relationship count. Note: The default will be changed to 'false' in a later release.

include_source_columns

boolean

Whether to include relationships where source end is a column of the source asset in the asset's relationship counter.

Response

200 - OK

trace

string

resources

array

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Marks existing assets for delete

DELETE /v2/assets/bulk

Use this API to delete assets. You can delete an asset if you are the owner of the asset or a member of the asset with Admin or Editor permissions on the catalog or project or space.

Purge Options to Delete Assets

purge_on_delete = true and purge_after_days is not specified: the asset is purged immediately. purge_on_delete = true and purge_after_days = n: the asset is moved to trash and purged after n days. purge_on_delete = false and purge_after_days is not specified: the asset is moved to trash and never purged. purge_on_delete is not specified and purge_after_days is not specified: the asset will be deleted/purged based on the catalog setting. purge_on_delete = false or is not specified and purge_after_days = n: invalid combination - the call will fail with a 400 Bad Request error.

Request

Path Parameters

string

Comma separated list of asset IDs; maximum of 20.

Response

207 - Check response body for status of each asset being deleted

status

array

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get assets membership for a specific user

GET /v2/assets/bulk/members/{member_id}

Returns any memberships this user has on assets, including direct membership and any access group memberships.

Request

Path Parameters

member_id

Required *

string

member_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

asset_ids

Required *

string

Comma separated list of asset IDs; maximum of 25.

resolve_member_roles

boolean

Should resolve member roles from usergroup(s) and collaborator roles

member_type

string

Type of the member specified by the member_id. If not specified, the service will determine if the member is a user or an access group based on the member_id, which is not always possible or accurate. Always supplying the member type is recommended.

profile_id

string

IAM Profile ID for Trusted Profile users: If the getMemberForAssetV2 API is called to fetch details for a Trusted Profile, the member_id is the IAM ID of the actual user, and the profile_id will be the IAM ID of the trusted user. For IBM users and App ID users, this value should be null.

Response

200 - OK

members

array

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

POST /v2/assets/bulk_copy

Use this API to publish one or more assets from a project to a catalog or promote from a project to a space. This API can also be used to clone one or more assets from a catalog to a project. The default maximum number of assets in a request is 50. <br/><br/>Copy sends the same Rabbit MQ messages as publish, promote or clone. Messages are sent for all assets that are copied.<br/><br/>This API supports using a refresh token in place of an access token. This can be helpful if the copy is expected to be a long running operation. The copy operation uses the access token to authenticate with other services, so it is important that it not expire while the operation is in progress. When a refresh token is specified, it is used to generate an initial access token as well as additional access tokens if the initial access token expires

Request

Request Body

CatalogBulkAssetsCopyRequest

Request body should include target container ID and list of assets with metadata overrides, and may include asset permissions override. Target container ID should be either that of a catalog (publish) or of a space (promote) if source conatiner is a project, or that of a project (clone) if source is a catalog. Example:

``` { "catalog_id": "string", "rov_mode": "integer", "member_roles": { "Member's IAM ID": { "user_iam_id": "Member's IAM ID", "roles": ["EDITOR"] }, "Access Group ID": { "access_group_id": "Access Group ID", "roles": ["VIEWER"] }, "Another IAM ID": { ... } }, "copy_configurations":[ { "asset_id": "string", "revision_id": "string", "metadata_overrides": { "name":"string", "description":"string", "tags":["string","string"] } }, ... ] } ``` Fields 'rov_mode' and 'member_roles' are optional.

If specified, they apply to all newly copied (target) assets.
If not supplied, newly copied asset gets mode and 'member_roles' from its corresponding source asset.
Valid values for 'rov_mode' are 0 (public), 8 (private) and 16 (hidden).
If caller doesn't have permissions to set any of the roles then 'member_roles' is completely ignored.
If supplied, 'member_roles' should include at least one OWNER role.

The 'metadata_overrides' field is optional and may contain attributes to overwrite the values in original asset. Currently only name, description and tags can be overriden. If specified 'metadata_overrides' cannot be empty and only applies to respective root asset.

Any cross-referenced asset is copied only once.

catalog_id

string

project_id

string

space_id

string

rov_mode

integer

member_roles

object

To assign owners and other collaborators on newly copied target assets.

copy_configurations

Required *

array

Path Parameters

Query Parameters

catalog_id

string

Source catalog ID. Only one of either catalog ID or project ID must be provided.

project_id

string

Source project ID. Only one of either catalog ID or project ID must be provided.

deepcopy

boolean

Determines if the copy operation should be cascaded to referenced assets. Referenced assets are determined using bidirectional external relationships and as well as in-line relationships. In-line relationship types are defined as part of asset type definitions. Cascading happens only if `CASCADE` is set for the following relationship type property:

`on_clone`, in case of copying from catalog to project,
`on_publish`, in case of copying from project to catalog and
`on_promote`, in case of copying from project to space.

auto_copy_connections_in_remote_attachments

boolean

Whether to automatically copy connections in remote attachments

duplicate_action

string

hide_deprecated_response_fields

boolean

Response

string

copy_status_href

string

Errors thrown during the operation

Create one or more assets.

POST /v2/assets/bulk_create

Use this API to create one or more assets in a catalog or a project or a space. The default maximum number of assets in a request is 20. Example of request (POST) data:<br/><br/> ``` { "assets":[ { "name":"<Name of the first asset>", "description":"<Description of the first asset>", "tags":["<Tag 1>", "<Tag 2>", ...], "asset_type":"<Asset type such as "connection", "data_asset", etc.>", "entity":{ ... } "attachments":{ ... } }, { "name":"<Name of the second asset>", ... }, ... ] } ``` Response includes, for each asset in the request and in the same order, details of newly created asset or details of updated asset if a duplicate/match is found or errors if any:

``` { "trace":"<Trace ID, if failed to create or update one or more assets>", "responses":[ { "http_status":201, "asset":{...} }, { "http_status":400, "errors":[ ... ] }, ... ] } ```

Request

Request Body

CatalogBulkAssetsCreateRequest

JSON containing list of assets to be created.

assets

Required *

array

Path Parameters

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

duplicate_action

string

hide_deprecated_response_fields

boolean

Response

200 - OK

trace

string

responses

array

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

RFC 6902 specification.

Example of request (POST) data:

``` { "resources": [ { "asset_id": "cf38d92c-eb55-462e-89bf-cdb9fe67f0b7", "operations": [ { "op": "add", "path": "/metadata/description", "value": "Four score and seven years ago..." }, { "op": "add", "path": "/entity/data_asset/mime_type", "value": "text/csv" }, { "op": "replace", "path": "/attachments/1/name", "value": "New name for the 2nd attachment." }, { "op": "remove", "path": "/attachments/0" } { "op":"add", "path":"/attachments/-", "value":{...} }, { "op":"replace", "path":"/attachments/1/name", "value":"New name for the 2nd attachment." }, { "op":"add", "path":"/attachments/2", "value":{...} }, ] }, { "asset_id":"c6650020-3176-4d67-8fbe-5a19ba1c2c7e", "operations": [ ... ] }, ... ] } ``` Response includes, for each asset, asset ID, status and updated version or errors, if any: ``` { "resources": [ { "asset_id": "cf38d92c-eb55-462e-89bf-cdb9fe67f0b7", "status": 200, "http_status": 200, "asset": { ... } }, { "asset_id": "c6650020-3176-4d67-8fbe-5a19ba1c2c7e", "status": 404, "http_status": 404, "errors": [ ... ] }, ... ] } ```

Currently the API allows to patch up to twenty (20) assets. There is no limit on number of patch instructions. Any number of (allowed) metadata properties and/or attributes can be:

modified,
new ones added,
existing ones be replaced or
deleted

JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.

> Note: Any `~` characters need to be escaped as `~0` in the path field

Any `/` characters need to be escaped as `~1` in the path field

For example, in `{"foo/: {"~bar: "value"}}`, the path for `~bar` is `/foo~1/~0bar` ">

Patch one or more assets.

POST /v2/assets/bulk_patch

Use this API to patch one or more assets in catalog or project or space. The default maximum number of assets in a request is 20.

The API supports the following operations:

Patching of allowed metadata properties. See `PATCH /v2/assets/{asset_id}` API for list of allowed metadata properties that can be patched."
Add, update and delete of attributes such as `asset_terms`, `data_profile`, etc."
Create, update and delete of attachments:
- The (asset) `attachments` field is an array and the index of the first attachment is 0, the index of the second one is 1 and so on. Adding or deleting an attachment shifts indexes of any attachments that follow it.
- A newly created attachment is added at the specified location. If the `path` is `/attachments/-` then it will be added at the end.
- Newly added attachment cannot be updated or deleted (in the same API call). And, newly updated attachment cannot be deleted.
- Some of the new attachment fields like `attachment_id`, `url1`, `url2`, etc. are only included in the response the first time when the attachments are created.
- Only the following attachment fields can be updated: `name`, `description`, `mime`, `size`, `partitions` and `transfer_complete`.

The API does not support patching of whole metadata, entity and attachments.

i.e. The `path` cannot be the following values: `/metadata`, `/entity` or `/attachments`.

Access to an asset is controlled by a combination of the privacy level and the members of the asset. For a governed catalog, data assets are protected from unauthorized access by the governance policies that are defined in Data Governance. Data assets in ungoverned catalogs are not subject to governance policies.

> Note: Patch 'operations' should conform to RFC 6902 specification.

Example of request (POST) data:

Currently the API allows to patch up to twenty (20) assets. There is no limit on number of patch instructions. Any number of (allowed) metadata properties and/or attributes can be:

modified,
new ones added,
existing ones be replaced or
deleted

JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.

> Note: Any `~` characters need to be escaped as `~0` in the path field

Any `/` characters need to be escaped as `~1` in the path field

For example, in `{"foo/: {"~bar: "value"}}`, the path for `~bar` is `/foo~1/~0bar`

Request

Request Body

CatalogBulkAssetsUpdateRequest

JSON containing per-asset updates/patches.

resources

Required *

array

Path Parameters

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Gets the status of asset copy operation

GET /v2/assets/copy_status/{copy_task_id}

For large deep copies, portions of the copy operation are performed in the background. This API provides a way to get the status of the background processing. It also provides additional details about deep copy operations that have already been completed.

Similar to /v2/assets/deepcopy/{deep_copy_task_id} API but response can support completion details of multiple source assets.

Note: The status of completed copy operations is only available for 24 hours.

Request

Path Parameters

copy_task_id

Required *

string

Query Parameters

state

string

error

CatalogErrorContainerModel

Errors thrown during the operation

Create a PUT signed url for an object or a file

POST /v2/assets/create_object_url

Use this API to create a PUT signed url to an object or a file in the catalog/project/space bucket/storage. <br/>You must specify both name and asset_type (to create a new object or a file) OR the asset_id (to overwrite an existing object or a file) in the request.<br/>You must specify one of these -- catalog_id, project_id or the space_id as a query parameter.<br/>Details:

No new meta-data (asset_id) is created or updated for this request.
Only the PUT signed url is returned for the object or the file.
If the asset_id is given in the request, a PUT signed url is returned for that asset's attachment's object/file, if the object/file is stored in the catalog/project/space bucket/storage. If the asset_type is given, the object/file from the first attachment with that asset_type is the one for which the PUT signed url will be returned. If the asset_type is not given, then, the asset's asset_type, then the "data_asset", will be used to find the attachment with the object/file.
If the asset_id is not given in the request, and asset_type and name are specified, a PUT signed url is returned for an object_key where the object_key value is created using the combination of asset_type, sanitized name, and a random string.
The name in the request can only contain letters, numbers, underscore, dash, space, and period -- same requirements as the attachment name.
The value of expires_in is in seconds. The default value of expires_in is 604800 (7 days). Given a value of 0, the default value will be applied. The max value is the same as the default value; if a value larger than the max value is input, the max value will be used.

Request

Request Body

CatalogObjectURLReqResp

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

201 - Created

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Gets the status of a deep copy operation

GET /v2/assets/deepcopy/{deep_copy_task_id}

Note: The status of completed deep copy operations is only available for 24 hours.

Request

Path Parameters

deep_copy_task_id

Required *

string

Query Parameters

Response

200 - OK

source

CatalogAssetContainer

target

Errors thrown during the operation

Bulk search duplicate assets

POST /v2/assets/duplicates/bulk_search

Use this API to search for duplicate assets of an array of assets in the target catalog, project, or space. The maximum number of assets in a request is 20.

Each asset in the request can either be an existing asset, or an asset object that is the same as the user would provide for creating a new asset. E.g., ``` { "resources":[ { "asset": { "metadata": {}, "entity": {} } }, { "project_id": "6f79ff7d-9227-4cba-81e7-726db8984d16", "asset_id": "faad7530-4a30-41da-ac27-d3a0f07b2070" }, { "asset": { "metadata": {}, "entity": {} } } ] } ``` The response contains an array of duplicate search results. The index of the results in the array is the same as the index of the corresponding asset in the request array. Each result can be a success or failure depending on the corresponding request asset. E.g., ``` { "trace":"32s0wywr3wdqpsn86b4cfzb4i", "resources":[ { "http_status": 200, "total_count": 1, "best_updatable_duplicate_asset_id": "b81c84f5-a551-43bb-9a6e-c8e7820995f9", "results": [ { "asset_id": "b81c84f5-a551-43bb-9a6e-c8e7820995f9", "highest_match_score": {}, "asset": { "metadata": {}, "entity": {} } } ] }, { "http_status": 404, "errors": [ { "code": "does_not_exist", "message": "ATTSV3024E: There is no asset with an ID of 'faad7530-4a30-41da-ac27-d3a0f07b2070' in a project with an ID of '6f79ff7d-9227-4cba-81e7-726db8984d16' ." } ] }, { "http_status": 200, "total_count": 0, "results": [ ] } ] } ``` The response of each requested item contains a `http_status` field that can be used to determine if the specific request was successful or not. If a request failed, the corresponding response will contain a field `errors` indicating the cause of the failure. For detail explaination of other fields in the request and response of each item, please refer to the `POST /v2/assets/duplicates/search` endpoint.

Request

Request Body

CatalogBulkSearchDuplicateRequest

The assets to search for duplicate assets.

resources

Required *

array

the assets to search duplicates for

Path Parameters

Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.

limit

integer

The maximum number of items to return for each requested asset

Response

200 - OK

trace

string

trace id of the transaction. only avaialbe if any of the request item failed.

resources

array

the responses

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Search duplicate assets

POST /v2/assets/duplicates/search

Use this API to search for duplicate assets of an asset in the target catalog, project, or space.

Users can provide an existing asset like below to search for duplicate assets of the given asset in the target asset container. The authenticated user needs to have the read access to the specified asset. ``` { "project_id": "6f79ff7d-9227-4cba-81e7-726db8984d16", "asset_id": "faad7530-4a30-41da-ac27-d3a0f07b2070" } ```

Or provide an asset object to search for duplicate assets of the given asset payload in the target asset container. The asset payload is the same as the user would provide for creating a new asset. ``` { "asset": { "metadata": {}, "entity": {} } } ```

The query parameter `limit` can be used to limit the number of duplicates in the response. If not supplied, the maximum allowed value `100` is used. Note that the API does not support paignation as users usually only care about top `x` number of duplicates instead of all duplicates. If they do, they can always use a large limit to retrieve all duplicates. There number of the duplicates of any given asset should be far less than the maximum allowed value of the parameter `limit`. The system would become unusable long before the number of duplicates reaches that value.

The duplicate assets in the response are ordered by the matching score from high to low. The higher the matching score, the more certain that the asset is a duplicate of the incoming asset.

The `total_count` indicates the total number of duplicates of the given asset. This is useful in case the total number of duplicates is greater than the specified limit.

array

Path Parameters

Response

200 - OK

results

array

List of matching duplicate assets

best_updatable_duplicate_asset_id

string

The id of the best updatable duplicate asset that would be chosen for updating/overwriting in a real persistence transaction. It is possible that there are matching duplicate assets but this field is null, which indicates the caller does not have permission to update/replace any of the matching duplicate assets

total_count

integer

Total number of duplicates

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Finds related assets

POST /v2/assets/get_relationships

Finds assets related to a given asset or a given governance artifact. This API supports limiting the results to a specific set of relationships as well as providing pagination and sorting options.

One of the {`catalog_id`, `project_id`, `space_id`} must be specified.
asset_id must be specified.
artifact_id and artifact_type cannot be specified.

artifact_id and artifact_type must be specified.
asset_id and container id cannot be specified.

One of the {`catalog_id`, `project_id`, `space_id`} must be specified.
asset_id must be specified. asset_id should be in the format of `<asset_id>#COLUMN#<column_identifier>`
artifact_id and artifact_type cannot be specified.

<br/><br/>Note:When self references are present (i.e. when the source and target asset in the relationship are the same), more rows than specified by the limit may be returned. When this happens, the total rows reported is accurate and the bookmark points to next page of results.

Request

Path Parameters

limit. Defaults to 25

orderby

array

orderby. This parameter can be repeated to add additional sort fields. <br><br>Default: update_time_asc

Supported sort fields (these are case insensitive):

create_time_asc
create_time_desc
update_time_asc
update_time_desc
creator_id_asc
creator_id_desc
updater_id_asc
updater_id_desc

include_source_columns

boolean

Whether to return relationships where source end is either the given asset or a column of the given asset. When this parameter set to 'true', 'include_target_columns' must also be set to 'true'. By this, all relationships of asset-asset, asset-column, asset-artifact, column-asset, column-column, column-artifact will be returned.Use this parameter when 'asset_id' refers to an asset which has columns.

Response

200 - Success

options

object

resources

array

total_rows

integer

object

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Get an ibm_data_source asset

GET /v2/assets/ibm_data_source

Use this API to get an ibm_data_source asset with provided endpoint or physical_collection. There is only one ibm_data_source asset that meets the specified parameters. Currently we only support the following three query methods:

host + port, the host is either ipV4 or ipV6 or a DNS name
host + port + physical_collection
physical_collection

Request

Path Parameters

Query Parameters

catalog_id

string

Catalog GUID or UID

bss_account_id

string

the bss_account_id

host

string

port

string

physical_collection

string

It can be database, project_id or bucket

hide_deprecated_response_fields

boolean

Response

200 - OK

metadata

CatalogResponseAssetMetadata

entity

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Publish an asset from a project which is only referenced in that project

POST /v2/assets/publish

Use this API to publish an asset whose only metadata are only in project as reference to a target catalog. Assets contain information about the contents of your data and how to access the data. You store asset metadata in a catalog and add collaborators from your organization to analyze data. Your data can reside in a variety of sources. For example, you can keep your data in your existing on-premises data sources, cloud data services, or streaming data feeds. By adding connection information to these remote sources in the catalog, you can allow other catalog users to access the data with the stored credentials. Alternatively, you can copy a snapshot of the remote data into the catalog's encrypted cloud storage.<br/>All asset types have a common set of properties. Some asset types have additional properties.<br/>When you add an asset to a catalog, you specify these common properties:

The asset name and an optional description. The name can only contain letters, numbers, underscore, dash, space, and period. The name can't be only blank spaces.
Privacy. You can choose to restrict access to the asset with the privacy level and asset membership.
- Public = Default. No restrictions on finding or using the asset.
- Private = Only asset members can find or use the asset.
Members. The catalog collaborators can be added as members of the asset. Members are important if you restrict access to the asset. When you create an asset, you are the owner (and a member) of it.
Tags. Metadata that makes searching for the asset easier. Tags can contain only letters, numbers, underscores, dashes, and the symbols # and @.

Request

Request Body

CatalogPublishAsset

Asset metadata

metadata

CatalogPublishAssetMetadata

Publish Asset Metadata

name

Required *

string

Choose Any Name for your Asset

description

string

Required *

string

source_system

object

Source System Info

child_source_systems

array

source_system_history

array

History of external repository assets that were the source of an imported/synced/rehomed asset.

published_from

object

Asset metadata where its published from

published_to

object

Asset metadata where it published to

entity

object

Path Parameters

Query Parameters

hide_deprecated_response_fields

boolean

Response

201 - Created

metadata

CatalogResponseAssetMetadata

entity

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Specifying conditions that at least one end of the relationship must match

There are three different conditions of this type that can be specified:

* relationship name  - limits results to relationships with the specified name(s)

* Required object criteria:
* required artifact — must specify artifact_type and artifact_id
* required asset - must specify asset_id and one of: catalog_id, project_id, space_id
* required asset container - must specify one of: catalog_id, project_id, space_id
* Only one type of required object criteria can be used

* Opposite end criteria:
* related_asset_types - specifies that opposite end must have one of the specified asset types
* related_artifact_types - specifies that opposite end must have one of the specified artifact types	
* related_asset_types and related_artifact_types can be used together to specify that the opposite end must have either the specified asset or artifact types

Specifying global conditions that the overall relationship much match:

There are 2 global conditions that can be specified: * modified_after - Restricts results to relationships created/updated after a specific date and time * modified_before - Restricts results to relationships created/updated before a specific date and time * modified_after and modified_before can be used together to filter for relationships created/updated within a specific time window.">

Searches for relationships

POST /v2/assets/search_relationships

Finds relationships that match the specified criteria. There are two general kinds of criteria that can be used: criteria that at least one relationship end must match and criteria that the overall relationship must match.

Specifying conditions that at least one end of the relationship must match

There are three different conditions of this type that can be specified:

* relationship name  - limits results to relationships with the specified name(s)

* Required object criteria:
* required artifact — must specify artifact_type and artifact_id
* required asset - must specify asset_id and one of: catalog_id, project_id, space_id
* required asset container - must specify one of: catalog_id, project_id, space_id
* Only one type of required object criteria can be used

* Opposite end criteria:
* related_asset_types - specifies that opposite end must have one of the specified asset types
* related_artifact_types - specifies that opposite end must have one of the specified artifact types	
* related_asset_types and related_artifact_types can be used together to specify that the opposite end must have either the specified asset or artifact types

Specifying global conditions that the overall relationship much match:

Request

Path Parameters

limit. Defaults to 25

orderby

array

orderby. This parameter can be repeated to add additional sort fields. <br><br>Default: update_time_asc

Supported sort fields (these are case insensitive):

create_time_asc
create_time_desc
update_time_asc
update_time_desc
creator_id_asc
creator_id_desc
updater_id_asc
updater_id_desc

include_source_columns

boolean

Response

200 - Success

options

object

resources

array

total_rows

integer

object

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

For Asset

The `asset_id` and one of the {`catalog_id`, `project_id`, `space_id`} must be set

For Column

The `asset_id` and one of the {`catalog_id`, `project_id`, `space_id`} must be set
The `asset_id` of a column must be in the format of `<asset_id>#COLUMN#<column_identifier>`

For Artifact

The `artifact_id` and `artifact_type` must be set. Use the global id of the artifact for `artifact_id` ">

Create asset relationships

POST /v2/assets/set_relationships

Use this API to create up to 20 asset relationships.

The relationship name must correspond to a relationship type defined on the source type.
The source must be an asset, column or governance artifact of the type specified in the relationship type definition.<br> Relationships created with a governance artifact as the source cannot be retrieved, modified, or deleted in the IKC UI.<br> These relationships can only be accessed through API calls such as `POST /v2/assets/search_relationships`, `POST /v2/assets/get_relationships`, and `POST /v2/assets/unset_relationships`.
The target must be an asset, column or governance artifact of the type specified in the relationship type definition.
If the specified relationship does not exist between a source and target, a new relationship is created.
If either end of the relationship is defined as multiplicity-one, any existing value of a multiplicity-one end is replaced.

For Asset

The `asset_id` and one of the {`catalog_id`, `project_id`, `space_id`} must be set

For Column

The `asset_id` and one of the {`catalog_id`, `project_id`, `space_id`} must be set
The `asset_id` of a column must be in the format of `<asset_id>#COLUMN#<column_identifier>`

For Artifact

The `artifact_id` and `artifact_type` must be set. Use the global id of the artifact for `artifact_id`

Request

Request Body

CatalogBulkAssetRelationshipsRequest

relationships

Required *

array

Response

207 - Check response body for results of processing each target artifact

results

array

Result(s) of relationship creation operation(s)

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

For Column

The `asset_id` and one of the {`catalog_id`, `project_id`, `space_id`} must be set
The `asset_id` of a column must be in the format of `<asset_id>#COLUMN#<column_identifier>`

For Artifact

The `artifact_id` and `artifact_type` must be set">

Deletes asset relationships

POST /v2/assets/unset_relationships

Use this API to delete up to 20 asset relationships.

The relationship name must correspond to a relationship type defined on the source type.
The source must be an asset or governance artifact of the type specified in the relationship type definition.
The target must be an asset or governance artifact of the type specified in the relationship type definition.
If the specified relationship does not exist between the source and the target, it will be ignored.

For Asset

The `asset_id` and one of the {`catalog_id`, `project_id`, `space_id`} must be set

For Column

The `asset_id` and one of the {`catalog_id`, `project_id`, `space_id`} must be set
The `asset_id` of a column must be in the format of `<asset_id>#COLUMN#<column_identifier>`

For Artifact

The `artifact_id` and `artifact_type` must be set

Request

Request Body

relationships

Response

207 - Check response body for status of each asset relationships being deleted.

results

array

Result(s) of relationship deletion operation(s)

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Get an asset

GET /v2/assets/{asset_id}

Use this API to retrieve an asset located in catalog or project. Access to an asset is controlled by a combination of the privacy level and the members of the asset. For a governed catalog, data assets are protected from unauthorized access by the governance policies that are defined in Data Catalog. Data assets in ungoverned catalogs are not subject to governance policies.

Request

Path Parameters

asset_id

Required *

string

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

To delete an asset in a project or space, all of the following must hold:

Caller must have the EDITOR or ADMIN role in the project/space

To delete a public asset in a catalog, any of the following must hold:

Caller must have the ADMIN role in the catalog
Caller must have the EDITOR role in the catalog and caller must have either the OWNER or EDITOR role on the asset

To delete a private asset in a catalog, all of the following must hold:

Caller must have either the ADMIN or EDITOR role in the CATALOG
Caller must have either the OWNER, EDITOR, or VIEWER role in the asset

Purge Options to Delete an Asset

Marks an existing asset for delete

DELETE /v2/assets/{asset_id}

Use this API to delete an existing asset.

Permissions Required to Delete an Asset

To delete an asset in a project or space, all of the following must hold:

Caller must have the EDITOR or ADMIN role in the project/space

To delete a public asset in a catalog, any of the following must hold:

Caller must have the ADMIN role in the catalog
Caller must have the EDITOR role in the catalog and caller must have either the OWNER or EDITOR role on the asset

To delete a private asset in a catalog, all of the following must hold:

Caller must have either the ADMIN or EDITOR role in the CATALOG
Caller must have either the OWNER, EDITOR, or VIEWER role in the asset

Purge Options to Delete an Asset

Request

Path Parameters

asset_id

Required *

string

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Fields that can be patched:

`/metadata/name`
`/metadata/description`
`/metadata/tags`
`/metadata/origin_country`
`/metadata/resource_key`
`/metadata/source_system/last_modification_timestamp`, Expected Format: `yyyy-MM-ddTHH:mm:ssX`
`/metadata/child_source_systems/{idx}/last_modification_timestamp`, Expected Format: `yyyy-MM-ddTHH:mm:ssX`
`/metadata/source_system_history` - array, use `add` operation with path `/metadata/source_system_history/-` to append a new element
`/metadata/rov/mode` - allowed values are 0 (public), 8 (private) or 16 (hidden)
`/metadata/rov/collaborator_ids`
`/metadata/rov/member_roles`
`/metadata/rov/member_roles/{iam id}/roles` - array, allowed values are OWNER/EDITOR/VIEWER, see below for details

Updating Asset Collaborators and Owners

Either the metadata/rov/collaborator_ids field or the metadata/rov/member_roles field can be updated, but not both.

The collaborator_ids field shown in the asset is derived from the information in member_roles, so updating one of these fields will automatically update the other. The collaborator_ids field shows the members in the member_roles field that have either the asset editor role or the asset viewer role. This field is present for backward compatibility with earlier versions of the catalog service.

Collaborators added to the metadata/rov/collaborator_ids field will be assigned a default asset role based on their role in the catalog. Catalog editors will be assigned the asset editor role, and Catalog viewers will be assigned the asset viewer role.

Users added to the metadata/rov/member_roles present must have either the OWNER role, the OWNER role and EDITOR role, or the OWNER role and VIEWER role. Other combinations of roles are not allowed. Asset users with the VIEWER or EDITOR role must be members of the catalog. In addition, asset users with the OWNER role must also be members if the catalog with either the EDITOR or ADMIN role unless certain service ids are used. For projects and spaces, new owners must have a role in the project/space.

Permissions Required to Modify Asset

To update non-governed fields an asset in a project or space, all of the following must hold:

Caller must have the EDITOR or ADMIN role in the project/space

To update non-governed fields in a private asset in a catalog, all of the following must hold:

Caller must have either the ADMIN or EDITOR role in the CATALOG
Caller must have either the OWNER, EDITOR, or VIEWER role in the asset

To update non-governed fields in a public asset in a catalog, any of the following must hold:

Caller must have the ADMIN role in the CATALOG
Caller must have the EDITOR role in the CATALOG and caller must have either the OWNER or EDITOR role in the asset

Permissions required to modify governed metadata fields

The "tags" field is the only governed field. For governed catalogs a policy check is made to determine whether updates to it are allowed and if an asset transformation is needed. The outcome of the policy check can either be "ALLOW", "DENY", or "TRANSFORM"

If the outcome is "ALLOW", the operation is allowed if the caller has either the "ADMIN" or "EDITOR" catalog role
If the outcome is "TRANSFORM", the permission checks described above for non-governed fields are applied
If the outcome is "DENY", the permission checks described above for non-governed fields are applied

Allowed Operations

The combination of asset roles and catalog roles determines what asset operations are allowed by users.

These abilities apply to public assets:

All members of the catalog can find the asset and see its properties.
All members of the catalog who have the Editor, Auditor, or Admin roles can use the asset.

These abilities apply to private assets:

All asset collaborators can find the asset and see its properties. Asset collaborators with the Editor, Auditor, or Admin role can use the asset.">

Update an asset

PATCH /v2/assets/{asset_id}

Overview

Use this API to update certain metadata fields in assets.

Fields that can be patched:

`/metadata/name`
`/metadata/description`
`/metadata/tags`
`/metadata/origin_country`
`/metadata/resource_key`
`/metadata/source_system/last_modification_timestamp`, Expected Format: `yyyy-MM-ddTHH:mm:ssX`
`/metadata/child_source_systems/{idx}/last_modification_timestamp`, Expected Format: `yyyy-MM-ddTHH:mm:ssX`
`/metadata/source_system_history` - array, use `add` operation with path `/metadata/source_system_history/-` to append a new element
`/metadata/rov/mode` - allowed values are 0 (public), 8 (private) or 16 (hidden)
`/metadata/rov/collaborator_ids`
`/metadata/rov/member_roles`
`/metadata/rov/member_roles/{iam id}/roles` - array, allowed values are OWNER/EDITOR/VIEWER, see below for details

Updating Asset Collaborators and Owners

Either the metadata/rov/collaborator_ids field or the metadata/rov/member_roles field can be updated, but not both.

Permissions Required to Modify Asset

To update non-governed fields an asset in a project or space, all of the following must hold:

Caller must have the EDITOR or ADMIN role in the project/space

To update non-governed fields in a private asset in a catalog, all of the following must hold:

Caller must have either the ADMIN or EDITOR role in the CATALOG
Caller must have either the OWNER, EDITOR, or VIEWER role in the asset

To update non-governed fields in a public asset in a catalog, any of the following must hold:

Caller must have the ADMIN role in the CATALOG
Caller must have the EDITOR role in the CATALOG and caller must have either the OWNER or EDITOR role in the asset

Permissions required to modify governed metadata fields

If the outcome is "ALLOW", the operation is allowed if the caller has either the "ADMIN" or "EDITOR" catalog role
If the outcome is "TRANSFORM", the permission checks described above for non-governed fields are applied
If the outcome is "DENY", the permission checks described above for non-governed fields are applied

Allowed Operations

The combination of asset roles and catalog roles determines what asset operations are allowed by users.

These abilities apply to public assets:

All members of the catalog can find the asset and see its properties.
All members of the catalog who have the Editor, Auditor, or Admin roles can use the asset.

These abilities apply to private assets:

All asset collaborators can find the asset and see its properties. Asset collaborators with the Editor, Auditor, or Admin role can use the asset.

Request

Request Body

CatalogJsonPatch

JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info. <br/> Note: <br/> Any ‘~’ characters need to be escaped as ~0 in the path field. <br/> Any ‘/’ characters need to be escaped as ~1 in the path field. <br/> For example, in {"foo/" : {"~bar" : "value"}}, the path for "~bar" is "/foo~1/~0bar".

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

duplicate_action

string

hide_deprecated_response_fields

boolean

exclude

string

Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.

Response

200 - OK

metadata

CatalogResponseAssetMetadata

entity

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Create an attachment

POST /v2/assets/{asset_id}/attachments

Creates an attachment.

Request

Request Body

CatalogAttachment

Attachment meta-data.
The "asset_type" is required.
The "mime" is a reliable way to indicate the nature and format of the attachment. It should be used instead of other implementation-specific means, e.g., file extension.
If not supplied, or if the value given is less than 1, data_partitions defaults to 1 (for non-remote and non-referenced attachments).
For remote attachments, both connection_id and connection_path are required.
For referenced attachments, both object_key and object_key_is_read_only are required.

asset_type

Indicate if the partitions are time based.

hierarchical

boolean

Indicate if the partitions are stored hierarchical or flat.

timestamp

string

The timestamp the partition information is collected, in format yyyy-MM-dd'T'HH:mm:ss.SSSX or yyyy-MM-dd'T'HH:mm:ssX

latest_partitions

array

The latest partitions.

Path Parameters

asset_id

Required *

string

Asset GUID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

duplicate_action

string

Response

201 - Created

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Get an attachment

GET /v2/assets/{asset_id}/attachments/{attachment_id}

Retrieve an attachment.

Request

Path Parameters

asset_id

Required *

string

Asset GUID

attachment_id

Required *

string

boolean

Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Delete an attachment

DELETE /v2/assets/{asset_id}/attachments/{attachment_id}

Delete an attachment.

Request

Path Parameters

asset_id

Required *

string

Asset GUID

attachment_id

Required *

string

Attachment GUID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

duplicate_action

string

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Update attachment metadata

PATCH /v2/assets/{asset_id}/attachments/{attachment_id}

Update attachment metadata. Only the following fields are allowed to update:

name
description
mime
size
partitions
transfer_complete

Request

Request Body

CatalogJsonPatch

JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info. <br/>[ { "op": "add", "path": "/name", "value": "my_attachment"},
{ "op": "replace", "path": "/mime", "value": "text/csv" },
{ "op": "remove", "path":"/description"} ] <br/> Note: <br/>

Any ‘~’ characters need to be escaped as ~0 in the path field. <br/> Any ‘/’ characters need to be escaped as ~1 in the path field. <br/> For example, in {"foo/" : {"~bar" : "value"}}, the path for "~bar" is "/foo~1/~0bar".
The transfer_complete field can only be set to true if its current value is false and the type of attachment is managed.

Path Parameters

asset_id

Required *

string

Asset GUID

attachment_id

Required *

string

Attachment GUID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

409 - Conflict

422 - Unprocessable Entity

500 - Internal Server Error

Mark an attachment as transfer complete

POST /v2/assets/{asset_id}/attachments/{attachment_id}/complete

Marks an attachment as transfer complete.

Request

Path Parameters

asset_id

Required *

string

Asset GUID

attachment_id

Required *

string

Attachment GUID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Auto update attachment's datasource_type from connection asset

PATCH /v2/assets/{asset_id}/attachments/{attachment_id}/datasource_type

Auto update attachment's datasource_type from connection asset

Request

Path Parameters

asset_id

Required *

string

Asset GUID

attachment_id

Required *

string

Attachment GUID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

409 - Conflict

422 - Unprocessable Entity

500 - Internal Server Error

Get resources info for an attachment

GET /v2/assets/{asset_id}/attachments/{attachment_id}/resources

Get resources info for an attachment.

Request

Path Parameters

asset_id

Required *

string

Asset GUID

attachment_id

Required *

string

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Increase resources for an attachment

PUT /v2/assets/{asset_id}/attachments/{attachment_id}/resources

Increase resources for an attachment.

Request

Request Body

CatalogAttachmentIncRes

attachment resource to increase, e.g. {"data_partitions":5, "private_url":false}

data_partitions

Required *

integer

private_url

boolean

Path Parameters

asset_id

Required *

string

Asset GUID

attachment_id

Required *

string

Attachment GUID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

List all attributes

GET /v2/assets/{asset_id}/attributes

Use this API to retrieve all attributes of an asset.

Request

Path Parameters

asset_id

Required *

string

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

column_info attribute

The built-in `column_info` type defines metadata (e.g. description, tags) for columns contained in a data asset which represents a relational database table or columnar data file (e.g. csv file).

Create a `column_info` asset attribute to add column descriptions and/or tags if that attribute does not already exist on the asset. <br/>Once the `column_info` attribute has been created, entries can be added, updated, or removed using the `PATCH /v2/assets/{asset_id}/attributes/column_info` endpoint.

The `column_info` attribute is a map structure where the key is a column name corresponding to an existing entry in the asset's `entity.data_asset.columns` array. <br/>For example, here is the request payload to create a `column_info` attribute that assigns a description and tags to `ACCOUNT_HOLDER_ID` and `NAME` columns: ``` { "name": "column_info", "entity": { "ACCOUNT_HOLDER_ID": { "column_description": "Globally unique identifier of the account holder.", "column_tags": [ "identifier", "unique_key" ] }, "NAME": { "column_description": "Full legal name of the account holder.", "column_tags": [ "legal_name" ] } } } ``` ">

Create an attribute

POST /v2/assets/{asset_id}/attributes

Use this API to create an asset attribute. An attribute is identically named with, and has fields that are partially defined by, an asset type. The `name` specified in the request payload must match an existing built-in or user-defined asset type.

column_info attribute

The built-in `column_info` type defines metadata (e.g. description, tags) for columns contained in a data asset which represents a relational database table or columnar data file (e.g. csv file).

Request

Request Body

CatalogAttribute

Attribute metadata. The "entity" is required.

name

Required *

string

entity

object

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

duplicate_action

string

Response

201 - Created

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Get an attribute

GET /v2/assets/{asset_id}/attributes/{attribute_key}

Use this API to retrieve an attribute of an asset.

Request

Path Parameters

asset_id

Required *

string

asset_id

attribute_key

Required *

string

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Delete an attribute

DELETE /v2/assets/{asset_id}/attributes/{attribute_key}

Use this API to delete an attribute of an asset.

Request

Path Parameters

asset_id

Required *

string

asset_id

attribute_key

Required *

string

attribute_key

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

duplicate_action

string

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Updating the column_info attribute

Use this API for updating an existing `column_info` attribute to set or replace the `column_description` or `column_tags` for any column.

> Note: Use `POST /v2/assets/{asset_id}/attributes` to create the `column_info` attribute if it does not exist on the asset. > Use `GET /v2/assets/{asset_id}/attributes/column_info` to check the existence of the attribute.

Payload Examples

To add a `column_info` entry that specifies a description and tags for the `INVOICE_ID` column: `[{"op":"add","path":"/INVOICE_ID","value":{"column_description":"Unique identifier of the invoice", "column_tags":["tag1", "tag2"]}}]`

To add or update a description on the existing `column_info` entry for the `ADDRESS` column: `[{"op":"add","path":"/ADDRESS/column_description","value":"customer street address"}]` To unset/remove the `ADDRESS` column's description: `[{"op": "remove", "path":"/ADDRESS/column_description"}]` To remove the entire `column_info` entry for the `ADDRESS` column: `[{"op": "remove", "path":"/ADDRESS"}]`

To update value of `properties` of data_asset: ``` { "entity": { "data_asset": { "mime_type": "text/csv", "dataset": true, "properties": [ { "name": "schema_name", "value": "GOSALES1021" }, { "name": "table_name", "value": "COUNTRY" } ] } } } ``` Request body: ``` [ { "op": "replace", "path": "/properties/1/value", "value": "COUNTRY2" } ] ```

To update value of `data_source_deployment`: ``` { "entity": { "ibm_data_source": { "data_source_type_id": "8c1a4480-1c29-4b33-9086-9cb799d7b157", "data_source_deployment": "on_cloud", "data_source_flags": [], "data_source_state": "ACTIVE", "data_source_encoding": "UTF-8", "data_source_protection_method": "guardium" } } } ``` Request body: ``` [ { "op": "replace", "path": "/data_source_deployment", "value": "cpd" } ] ```

JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info. > Note: > Any ‘~’ characters need to be escaped as ~0 in the path field. > Any ‘/’ characters need to be escaped as ~1 in the path field. > For example, in {"foo/" : {"~bar" : "value"}}, the path for "~bar" is "/foo~1/~0bar". ">

Update attributes

PATCH /v2/assets/{asset_id}/attributes/{attribute_key}

Use this API to update/modify an asset attribute.

Updating the column_info attribute

Use this API for updating an existing `column_info` attribute to set or replace the `column_description` or `column_tags` for any column.

Payload Examples

Request

Request Body

CatalogJsonPatch

JSON array of patch operations as defined in RFC 6902.<br/>

Path Parameters

asset_id

Required *

string

asset_id

attribute_key

Required *

string

attribute_key

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

exclude

string

Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.

duplicate_action

string

Response

200 - Created

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Clone an asset

POST /v2/assets/{asset_id}/clone

Use this API to clone catalog asset to project. This will create new copy of asset metadata, including asset attachments.

Request

Request Body

CatalogAssetCopyTo

Request body should include project ID, and may include asset permissions override.

``` { "project_id": "string", "member_roles": { "Member's IAM ID": { "user_iam_id": "Member's IAM ID", "roles": ["EDITOR"] }, "Access Group ID": { "access_group_id": "Access Group ID", "roles": ["VIEWER"] }, "Another IAM ID": { ... } } } ```
Field 'member_roles' is optional.

If specified, 'member_roles' apply to newly cloned asset.
If not supplied, newly cloned asset gets 'member_roles' from its source asset.
If caller doesn't have permissions to set any of the roles then 'member_roles' is completely ignored.
If supplied, 'member_roles' should include at least one OWNER role.
If caller has only EDITOR role on the source asset and if 'member_roles' does not include all the owners of the source asset then it will be ignored.

'project_id' is the target project id.

projectId

Required *

string

member_roles

object

Optional owners and other collaborators to assign to newly copied target assets

mode

integer

Set the privacy level mode to be Public (0), Private (8), or Hidden (16)

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

catalog_id

Required *

string

catalog_id must be provided

duplicate_action

string

hide_deprecated_response_fields

boolean

Response

201 - Created

metadata

CatalogResponseAssetMetadata

entity

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Permissions Required to Modify Asset Members

To add or remove asset owners for a private asset in a catalog, any of the following must hold:

Caller must have OWNER role on the asset
Caller must have the ADMIN role on catalog and caller must have either the OWNER, EDITOR, or VIEWER role in the asset

To add or remove asset owners for a public asset in a catalog, any of the following must hold:

Caller must have OWNER role on the asset
Caller must have the ADMIN role in the catalog

To add or remove asset collaborators, other than asset owner, for a private asset in a catalog, any of the following must hold:

Caller must have OWNER role on the asset
Caller must have EDITOR role on the asset
Caller must have the ADMIN role on catalog and caller must have either the OWNER, EDITOR, or VIEWER role in the asset

To add or remove asset collaborators, other than asset owner, for a public asset in a catalog, any of the following must hold:

Caller must have OWNER role on the asset
Caller must have EDITOR role on the asset
Caller must have the ADMIN role on catalog

Allowed Operations

The combination of asset roles and catalog roles determines what asset operations are allowed by users.

These abilities apply to public assets:

All members of the catalog can find the asset and see its properties.
All members of the catalog who have the Editor, Auditor, or Admin catalog roles can use the asset.

These abilities apply to private assets:

All asset collaborators can find the asset and see its properties. Asset collaborators with the Editor, Auditor, or Admin catalog role can use the asset. ">

Add/Update asset collaborators

PATCH /v2/assets/{asset_id}/collaborators

Overview

This API adds and removes users as collaborators and owners on an asset. A collaborator or owner is identified by user ID. Note that access groups are not supported as asset collaborators or owners. Access groups can be configured as catalog members.

Either the `metadata/rov/collaborator_ids` field or the `metadata/rov/member_roles` field can be updated, but not both. The `collaborator_ids` field shown in the asset is derived from the information in `member_roles`, so updating one of these fields will automatically update the other. The `collaborator_ids` field shows the members in the `member_roles` field that have either the asset editor role or the asset viewer role. This field is present for backward compatibility with earlier versions of the catalog service.

Collaborators added to the `metadata/rov/collaborator_ids` field will be assigned a default asset role based on their role in the catalog. Catalog editors will be assigned the asset editor role, and Catalog viewers will be assigned the asset viewer role.

Users added to the `metadata/rov/member_roles` present must have either the OWNER role, the OWNER role and EDITOR role, or the OWNER role and VIEWER role. Other combinations of roles are not allowed. Asset users with the VIEWER or EDITOR role must be members of the catalog. In addition, asset users with the OWNER role must also be members of the catalog with either the EDITOR or ADMIN role unless certain service ids are used. For projects and spaces, new owners must have a role in the project/space.

Permissions Required to Modify Asset Members

To add or remove asset owners for a private asset in a catalog, any of the following must hold:

Caller must have OWNER role on the asset
Caller must have the ADMIN role on catalog and caller must have either the OWNER, EDITOR, or VIEWER role in the asset

To add or remove asset owners for a public asset in a catalog, any of the following must hold:

Caller must have OWNER role on the asset
Caller must have the ADMIN role in the catalog

To add or remove asset collaborators, other than asset owner, for a private asset in a catalog, any of the following must hold:

Caller must have OWNER role on the asset
Caller must have EDITOR role on the asset
Caller must have the ADMIN role on catalog and caller must have either the OWNER, EDITOR, or VIEWER role in the asset

To add or remove asset collaborators, other than asset owner, for a public asset in a catalog, any of the following must hold:

Caller must have OWNER role on the asset
Caller must have EDITOR role on the asset
Caller must have the ADMIN role on catalog

Allowed Operations

The combination of asset roles and catalog roles determines what asset operations are allowed by users.

These abilities apply to public assets:

All members of the catalog can find the asset and see its properties.
All members of the catalog who have the Editor, Auditor, or Admin catalog roles can use the asset.

These abilities apply to private assets:

All asset collaborators can find the asset and see its properties. Asset collaborators with the Editor, Auditor, or Admin catalog role can use the asset.

Request

Request Body

CatalogJsonPatch

JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info. ``` [{ "op": "add", "path": "/metadata/rov/collaborator_ids/test-iam-id", "value": { "user_id": "test@us.ibm.com", "user_iam_id": "test-iam-id" } }, { "op": "replace", "path": "/metadata/rov/collaborator_ids/test-iam-id", "value": { "user_id": "test2-iam-id", "user_iam_id": "test-iam-id" } }, { "op": "remove", "path": "/metadata/rov/collaborator_ids/test2-iam-id" } ] ``` (DEPRECATED) ``` [{ "op": "add", "path": "/metadata/rov/collaborators/test@us.ibm.com", "value": { "user_id": "test@us.ibm.com" } }, { "op": "replace", "path": "/metadata/rov/collaborators/test@us.ibm.com", "value": { "user_id": "test2@us.ibm.com" } }, { "op": "remove", "path": "/metadata/rov/collaborators/test2@us.ibm.com" } ] ``` Note: Any ‘~’ characters need to be escaped as ~0 in the path field. Any ‘/’ characters need to be escaped as ~1 in the path field. For example, in `{"foo/" : {"~bar" : "value"}}`, the path for "~bar" is `/foo~1/~0bar`.

Path Parameters

asset_id

Required *

string

Asset GUID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

hide_deprecated_response_fields

boolean

exclude

string

Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.

Response

200 - OK

metadata

CatalogResponseAssetMetadata

entity

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

409 - Conflict

422 - Unprocessable Entity

500 - Internal Server Error

Get asset document conflicts

GET /v2/assets/{asset_id}/conflicts

Use this API to retrieve asset document conflicts in database.

Request

Path Parameters

asset_id

Required *

string

boolean

Whether to retrieve conflict revision document content

Response

200 - OK

resources

array

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Delete asset document conflicts

DELETE /v2/assets/{asset_id}/conflicts

Use this API to delete asset document conflicts in database.

Request

Request Body

CatalogDeleteAssetDocumentConflictsRequest

Document conflicts to delete

revs

Required *

array

List of conflicting documents revs

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

POST /v2/assets/{asset_id}/deepcopy

Use this API to deep copy an asset to a project, catalog, or space. Unlike clone, publish, and promote, this API enables cascading the copy operation to referenced assets. <br/><br/> When copying from a project to a space, the on_promote relationship option is used to determine whether the related assets for a given relationship type should be copied. In addition, you must have Admin or Editor permissions on both the project and the space.<br/><br/>Deep copy sends the same Rabbit MQ messages as clone, publish, and promote. Messages are sent for all assets that are copied.<br/><br/>This API supports copying from a project to a catalog (publish), from a project to a space (promote), and from a catalog to a project (clone).<br/></br>This API supports using a refresh token in place of an access token. This can be helpful if the deep copy is expected to be a long running operation. The deep copy uses the access token to authenticate with other services, so it is important that it not expire while the operation is in progress.<be/>When a refresh token is specified, it is used to generate an initial access token as well as additional access tokens if the initial access token expires

Request

Request Body

Request body should include target (container) ID, and may include asset permissions and metadata overrides. Fields 'mode' and 'member_roles' are optional.

If specified, they apply to newly copied (target) assets.
If not supplied, newly copied asset gets mode and 'member_roles' from its corresponding source asset.
Valid values for 'mode' are 0 (public), 8 (private) and 16 (hidden).
If caller doesn't have permissions to set any of the roles then 'member_roles' is completely ignored.
If supplied, 'member_roles' should include at least one OWNER role.

'space_id' is the target space ID i.e. target container ID.

'metadata' is optional and may contain attributes to overwrite the values in original asset;currently only name, description and tags may be overwritten.

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

project_id

string

project_id

catalog_id

string

catalog_id

revision_id

string

Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.

duplicate_action

string

Response

options

CatalogDeepCopyOptions

copy_task_id

string

copy_status_href

string

copied_asset

CatalogResponseAsset

202 - Accepted - indicates that the copy request is being completed in the background.

options

CatalogDeepCopyOptions

Errors thrown during the operation

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

Image creator id

url

string

Image download url

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Upload an image for asset

PUT /v2/assets/{asset_id}/images

Upload an image for asset. Use this api, you must put the image's binary data to the HTTP body.<br>For example:<br>    <i>curl -X "PUT" "api_url" -H "Authorization: $access token" --data-binary "@/image_dir_path/abc.png"</i>

Request

Path Parameters

asset_id

Required *

string

Asset GUID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

Image creator id

url

string

Image download url

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Delete the image of asset

DELETE /v2/assets/{asset_id}/images/{image_id}

Delete the image of asset.

Request

Path Parameters

asset_id

Required *

string

Asset GUID

image_id

Required *

string

Image id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Get asset or column notes

GET /v2/assets/{asset_id}/notes

Use this API to retrieve a paginated list of notes from an asset or a column within an asset. Any user who has viewer permission on an asset can retrieve its notes.

Request

Path Parameters

asset_id

Required *

string

string

Type of notes to include in the search result: <br><table border="1"><thead><tr><th>Note Type</th><th>Description</th></tr></thead><tbody><tr><td><code>`ALL`</code></td><td>Include all asset and column notes</td></tr><tr><td><code>`ASSET`</code></td><td>Include asset notes only - cannot be used with the `column_names` parameter</td></tr><tr><td><code>`COLUMN`</code></td><td>Include column notes only</td></tr></tbody></table>

Response

200 - OK

resources

array

limit

integer

count

integer

first

CatalogLink

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Create notes on an asset

POST /v2/assets/{asset_id}/notes

Use this API to create notes for an asset and for columns within an asset. Accredited Service Editors and Viewers, and any user who has edit permission on an asset can create a note.

Request

Request Body

CatalogAssetNotesCreationRequest

Asset notes to be created - limited to 20 notes per request

notes

Required *

array

notes to be created for an asset and for columns of an asset

Path Parameters

asset_id

Required *

string

Asset ID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

revision_id

string

Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.

Response

207 - Check response body for results of processing each requested note

results

array

Result(s) of asset note creation operation(s)

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get an asset or column note

GET /v2/assets/{asset_id}/notes/{note_id}

Use this API to retrieve a note from an asset or a column within an asset. Any user who has viewer permission on an asset can retrieve a note.

Request

Path Parameters

asset_id

Required *

string

Asset ID

note_id

Required *

string

Note ID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

revision_id

string

Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.

Response

200 - OK

metadata

object

Asset note metadata

entity

object

Asset note entity

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Delete an asset or a column note

DELETE /v2/assets/{asset_id}/notes/{note_id}

Use this API to delete an asset or a column note. Accredited Service Editors and Viewers, and any user who has edit permission on an asset can delete a note.

Request

Path Parameters

asset_id

Required *

string

Asset ID

note_id

Required *

string

Asset or column note ID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

revision_id

string

Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Update an asset or column note

PATCH /v2/assets/{asset_id}/notes/{note_id}

Use this API to update a note on an asset or a column within an asset. Accredited Service Editors and Viewers, and any user who has edit permission on an asset can update a note.

Request

Request Body

CatalogJsonPatch

JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info. <br/>Example :<br/> `[ {"op": "replace", "path": "/note", "value": "Description of a Note" } ]` <br/> Note: <br/> Only supported operation is `replace`. <br/> Any ‘~’ characters need to be escaped as ~0 in the path field. <br/> Any ‘/’ characters need to be escaped as ~1 in the path field. <br/> For example, in `{"foo/" : {"~bar" : "value"}}`, the path for `~bar` is `/foo~1/~0bar`.

Path Parameters

asset_id

Required *

string

Asset ID

note_id

Required *

string

Note ID

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

revision_id

string

Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.

Response

200 - OK

metadata

object

Asset note metadata

entity

object

Asset note entity

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Update the owner of an asset

PUT /v2/assets/{asset_id}/owner

Use this API to assign new owner of an asset. You must be the current owner of the asset or a collaborator of the asset with Admin permissions to change the owner. If the asset has multiple owners and the specified user is not currently an owner, the last owner in the owner list (which is the one shown in the owner_id field) is replaced with the specified owner. If the specified user is already an owner of the asset, the user is moved to the end of the owner list so that it is reported in the owner_id field.

This API is deprecated, since this is an older API and supports only single asset owner, not assets with multiple owners. Moving forward owners should be created or updated using below APIs

`/v2/assets/{asset_id}`

`/v2/assets/{asset_id}/collaborators`

Request

Request Body

CatalogAssetOwner

Asset Owner

owner

string

owner_id

string

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

hide_deprecated_response_fields

boolean

exclude

string

Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.

Response

200 - OK

metadata

CatalogResponseAssetMetadata

entity

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Update privacy settings of an asset

PUT /v2/assets/{asset_id}/perms

Use this API to change privacy settings on an asset.<br/>

The owner of the asset or asset collaborators with the Admin role can change the owner of the asset or delete the asset.
Asset collaborators with the Editor, Auditor, or Admin role can change the asset members or the privacy setting.

Request

Request Body

CatalogAssetRov

Asset ROV

mode

integer

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

hide_deprecated_response_fields

boolean

exclude

string

Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.

Response

200 - OK

metadata

CatalogResponseAssetMetadata

entity

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Promote an asset

POST /v2/assets/{asset_id}/promote

Use this API to promote project assets to space. You must have Admin or Editor permissions on both the project and the space.

Request

Request Body

Request body should include space ID, and may include asset permissions and metadata overrides. Fields 'mode' and 'member_roles' are optional.

If specified, they apply to newly promoted asset.
If not supplied, newly promoted asset gets mode and 'member_roles' from source asset.
Valid values for 'mode' are 0 (public), 8 (private) and 16 (hidden).
If caller doesn't have permissions to set any of the roles then 'member_roles' is completely ignored.
If supplied, 'member_roles' should include at least one OWNER role.
If caller has only EDITOR role on the source asset and if 'member_roles' does not include all the owners of the source asset then it will be ignored.

'space_id' is the target space id.'

metadata' is optional and may contain attributes to overwrite the values in original asset; currently only name, description and tags may be overwritten.

Path Parameters

asset_id

Required *

metadata

CatalogResponseAssetMetadata

entity

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Publish an asset

POST /v2/assets/{asset_id}/publish

Use this API to publish project assets to catalog. You can publish data assets from a project into a catalog. You must have Admin or Editor permissions on both the project and the catalog.

Request

Request Body

Request body should include catalog ID, and may include asset permissions and metadata overrides. Fields 'mode' and 'member_roles' are optional.

If specified, they apply to newly published asset.
If not supplied, newly published asset gets mode and 'member_roles' from source asset.
Valid values for 'mode' are 0 (public), 8 (private) and 16 (hidden).
If caller doesn't have permissions to set any of the roles then 'member_roles' is completely ignored.
If supplied, 'member_roles' should include at least one OWNER role.
If caller has only EDITOR role on the source asset and if 'member_roles' does not include all the owners of the source asset then it will be ignored.

'catalog_id' is the target catalog id. To support backwards compatibility when it is not supplied, the asset is published to the catalog associated with the project.

'metadata' is optional and may contain attributes to overwrite the values in original asset; currently only name, description and tags may be overwritten.

Path Parameters

asset_id

Required *

metadata

CatalogResponseAssetMetadata

entity

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get ratings of an asset

GET /v2/assets/{asset_id}/ratings

Get ratings for the specified asset.

Request

Path Parameters

asset_id

Required *

string

string

Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.

Response

200 - OK

resources

array

limit

integer

count

integer

first

CatalogLink

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Rate an asset

POST /v2/assets/{asset_id}/ratings

Use this API to rate an asset.

Request

Request Body

CatalogAssetRatingEntity

Asset rating to be created

rating

Required *

integer

user's rating of an asset

review

string

user's review of an asset

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

revision_id

string

Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.

Response

201 - Created

metadata

CatalogAssetRatingMetadata

AssetRatingMetadata

entity

CatalogAssetRatingEntity

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get the count of each rating value for the specified asset

GET /v2/assets/{asset_id}/ratings/stats

Get the counts of each rating value for the specified asset.

Request

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

revision_id

string

Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.

Response

200 - OK

asset_id

string

identifier for asset

revision_id

integer

revision for asset

stats

array

count of ratings for each rating value

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Delete an asset rating

DELETE /v2/assets/{asset_id}/ratings/{asset_rating_id}

Use this API to delete an asset rating.

Request

Path Parameters

asset_id

Required *

string

asset_id

asset_rating_id

Required *

string

asset_rating_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

revision_id

string

Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Use this API to update an asset rating.

PATCH /v2/assets/{asset_id}/ratings/{asset_rating_id}

Update an asset rating

Request

Request Body

CatalogAssetRatingEntity

Asset rating to be updated

rating

Required *

integer

user's rating of an asset

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

revision_id

string

Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.

Response

200 - OK

metadata

CatalogAssetRatingMetadata

AssetRatingMetadata

entity

CatalogAssetRatingEntity

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Finds relationship types used by an asset

GET /v2/assets/{asset_id}/relationship_types

Finds relationship types that are used by a given asset. This API only returns the first page of results. It does not accept a bookmark. Any additional pages of results must be be fetched using the next page url included in the response.<br/></br>You can refer to the options in the response to get the full list of relationship names.<br><br> This API is deprecated - use `POST /v2/assets/search_relationships` instead.

Request

Path Parameters

asset_id

Required *

string

Asset ID

Query Parameters

catalog_id

string

Catalog ID

project_id

string

Project ID

space_id

string

Space ID

limit

integer

Optional limit to use when finding relationship types

orderby

array

orderby. This parameter can be repeated to add additional sort fields. <br><br>Default: relationship_display_name_asc

Supported sort fields (these are case insensitive):

relationship_name_asc
relationship_name_desc
relationship_display_name_asc
relationship_display_name_desc
create_time_asc
create_time_desc

Response

200 - Success

object

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

429 - Too Many Requests

GET /v2/assets/{asset_id}/relationships

Finds assets related to a given asset. This API supports limiting the results to a specific set of relationships as well as providing pagination and sorting options.<br/><br/>Note:When self references are present (i.e. when the source and target asset in the relationship are the same), more rows than specified by the limit may be returned. When this happens, the total rows reported is accurate and the bookmark points to next page of results.<br><br> This API is deprecated - use `POST /v2/assets/get_relationships` instead.

Request

Path Parameters

asset_id

Required *

string

array

orderby. This parameter can be repeated to add additional sort fields. <br><br>Default: update_time_asc

Supported sort fields (these are case insensitive):

create_time_asc
create_time_desc
update_time_asc
update_time_desc
creator_id_asc
creator_id_desc
updater_id_asc
updater_id_desc

relname

array

Limits results to only include the specified relationships. By default, all relationships are included. Repeat the query parameter to specify multiple relationship names.

lookup_asset_names

boolean

Whether to lookup the asset names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.

lookup_container_names

boolean

Whether to lookup the container names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.

Response

200 - Success

options

object

resources

array

total_rows

integer

object

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Create asset relationships

PUT /v2/assets/{asset_id}/relationships/{relationship_name}

Use this API to create relationships between a source asset and up to 20 target artifacts.

The relationship name must correspond to a relationship type defined on the source asset's type.
The target artifacts must be assets of the type specified in the relationship type definition.
If the specified relationship does not exist between a source and target asset, a new relationship is created.
If either end of the relationship is defined as multiplicity-one, any existing value of a multiplicity-one end is replaced.

This API is deprecated - use `POST /v2/assets/set_relationships` instead.

Request

Request Body

CatalogCreateRelationshipsRequestBody

Target artifacts

relationship_targets

Required *

array

target artifacts

Path Parameters

asset_id

Required *

string

Asset ID

relationship_name

Required *

string

Name of relationship defined on the source asset type

Query Parameters

catalog_id

string

Catalog ID

project_id

string

Project ID

space_id

string

Space ID

Response

207 - Check response body for results of processing each target artifact

results

array

Result(s) of relationship creation operation(s)

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Deletes asset relationships

DELETE /v2/assets/{asset_id}/relationships/{relationship_name}

Use this API to remove a relationship between an asset and one or more target artifacts. The relationship name must correspond to a relationship type defined on the source asset's type. If the specified relationship does not exist between the source and one or more target assets, it will be ignored. For this api, all of the relationship targets need to be in the same catalog, project, or space. If the target space/catalog/project is omitted, it is assumed to be the same as the source.<br><br> This API is deprecated - use `POST /v2/assets/unset_relationships` instead.

Request

Path Parameters

asset_id

Required *

string

Source Asset Id

relationship_name

Required *

string

string

Target Asset Space

target_asset_id

Required *

array

target asset id. To delete multiple relationships, this parameter can be repeated.

Response

200 - OK. Check response body for results of processing each target artifact

error_results

array

source_asset

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Determine if a relationship exists between an asset and a target artifact

HEAD /v2/assets/{asset_id}/relationships/{relationship_name}

Query Parameters

catalog_id

string

Catalog ID

project_id

string

Project ID

space_id

string

Space ID

Response

204 - The relationship exists

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

410 - Gone - If either asset in the relationship is in the deleted state

500 - Internal Server Error

Get a list of revisions for an asset

GET /v2/assets/{asset_id}/revisions

Use this API to retrieve an ordered list of revisions for an asset, most to least recent.

Request

Path Parameters

asset_id

Required *

string

string

The revision number to start from, or 'latest'. Latest revision is the default.

hide_deprecated_response_fields

boolean

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Commit a revision of an asset

POST /v2/assets/{asset_id}/revisions

Use this API to commit a revision of an asset.

Request

Request Body

CatalogAssetCommitOptions

Commit options

commit_message

string

Path Parameters

asset_id

Required *

string

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

500 - Internal Server Error

Delete a revision

DELETE /v2/assets/{asset_id}/revisions

Use this API to delete a revision of an asset.

Request

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

revision_id

Required *

string

You must provide a revision id (1, 2, 3, ...)

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Find and repair stuck temporary design documents by creating cache entries that resume their processing

POST /v2/cams/admin/index_repairs

Use this API to find and repair broken indexes

Request

Path Parameters

Query Parameters

catalog_id

array

Optionally limits to checking to certain catalogs. For projects and spaces you must use the id of the private catalog. Repeat this parameter to check multiple catalogs. If this is omitted, all catalogs are checked

sleep_every

integer

Allows rate limiting the creation of cache entries. To disable rate limiting, set to -1. If set, the operation pauses every time this number of cache entries have been created.

sleep_time_mins

integer

When using cache entry rate limiting, this controls how long the service pauses between creating groups of cache entries.

max_cache_entries_to_create

integer

Allows restricting total the number of cache entries created.

preview_only

boolean

Response

202 - Accept, the processing was successfully started

options

object

The options being used for the indexing repair task.

status_link

string

Link that can be used to get the status of the indexing repair task.

task_id

string

The id of the indexing repair task that was created.

400 - Bad Request

401 - Unauthorized

403 - Forbidden

Gets the status of a temporary design document repair operation

GET /v2/cams/admin/index_repairs/{id}

Use this API to get the status of the task to find and repair stuck temporary design documents

Request

Path Parameters

id

Required *

string

Query Parameters

Response

The ids of any catalogs that were unable to be processed.

failure_message

string

The error message if the processing failed.

400 - Bad Request

401 - Unauthorized

403 - Forbidden

Reconfigure the asset container

POST /v2/cams/admin/reconfigure

Use this API to reconfigure the asset container. The supported items are:<br/>

type_search_indexes - reconfigure type search indexes for all asset types. It requires the user to have permission to register asset types.

Request

Path Parameters

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

item

Required *

string

The item to reconfigure, e.g. type_search_indexes

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

DELETE /v2/cams/admin/roles_cache_entry

Request

Path Parameters

Query Parameters

catalog_id

string

The catalog id

project_id

string

The project id

space_id

string

The space id

user_id

Required *

string

The id of the user whose role to remove from the cache

Response

200 - Cache entry was deleted

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Cache entry was not found

Add a task result to the task

DELETE /v2/cams/admin/tasks/delete

Add a task result for future reference and servicability.

Request

Request Body

Lucene Query Syntax to search for task result objects to be deleted.

Response

200 - OK

statusCode

integer

statusMessage

500 - Internal Server Error

Add a task result to the task

POST /v2/cams/admin/tasks/search

Add a task result for future reference and servicability.

Request

Request Body

Lucene Query Syntax to search for task result objects. See the Add Task Result api method for an example of the object type you'll get back. They come as an array

Response

200 - OK

id

string

rev

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get metrics of the asset lists

GET /v2/cams/metrics/asset_list_count

Get metrics of the asset lists. <br><br>The caller should use the `href` returned by the service to navigate through pages and should not try to manually construct URLs for pagination. The `href` for the first page is always available, and the `href` for the next page is only available if there may be a next page. <br><br>The `total_rows` field is only available when `summary_level` is `CATALOG`. <br><br>The caller must be in at least one of the allow-lists based on the product offering to perform the operation:

`DATA_PRODUCT` - `data_product_account_viewers`, `data_product_account_managers`

Request

Path Parameters

Query Parameters

month

string

The month of the metrics to retrieve. The value must be in format `yyyy-MM`. If not supplied, the metrics of the current month are retrieved.

bss_account_ids

string

errors

array

Get metrics of the users who accessed the catalogs

GET /v2/cams/metrics/user_access_count

Get metrics of the users who accessed the catalogs. <br><br>The caller should use the `href` returned by the service to navigate through pages and should not try to manually construct URLs for pagination. The `href` for the first page is always available, and the `href` for the next page is only available if there may be a next page. <br><br>The `total_rows` field is only available when `summary_level` is `CATALOG`. <br><br>The caller must be in at least one of the allow-lists based on the product offering to perform the operation: (Note: the `WKC` product offering represents IBM Knowledge Catalog):

`DATA_PRODUCT` - `data_product_account_viewers`, `data_product_account_managers`
`WATSONX_GOVERNANCE` - `watsonx_governance_account_viewers`, `watsonx_governance_account_managers`
`WKC` - `wkc_account_viewers`, `wkc_account_managers`

Request

Path Parameters

The maximum number of items to return. If not specified, it will be set to 200.

start

string

Start token for pagination

Response

200 - OK

limit

integer

The limit on the number of results returned.

total_count

integer

The total count on the number of results returned, accounting for filtering but not pagination.

first

CatalogBaseCollectionPage

A page in a pagination collection.

CatalogBaseCollectionNextPage

The next page in the collection.

resources

errors

array

List all catalogs for a specific account

GET /v2/catalogs

Use this API to get a list of catalogs or projects or spaces, or to get the total number of public catalogs, for a given account. You can use 'roles' parameter to filter results by roles for standard callers.<br/>

Standard Callers: to list all catalogs where caller is collaborator, omit "bss_account_id" field and "include" field.<br/>
Accredited Services: to list all catalogs or projects or spaces for a specific account, enter bss account value in "bss_account_id" field and one of 'catalogs', 'projects', or 'spaces' in "include" field.<br/>
Accredited Services: to get the number of public catalogs for a specific account, enter bss account value in "bss_account_id" field and 'total_count' in "include" field.

Request

Path Parameters

Query Parameters

limit

integer

limit

bookmark

string

bookmark

skip

integer

skip

include

string

Limited to use by accredited services (which must also supply 'bss_account_id'). Currently, the only supported values are 'catalogs', 'projects', 'spaces' or 'total_count'. Not supplying any of these values results in public 'catalogs', 'projects', AND 'spaces' being returned for a specific account.<br/>

Use 'catalogs' for including all public catalogs for a specific bss_account_id.<br/>
Use 'projects' for including all projects for a specific bss_account_id.<br/>
Use 'spaces' for including all spaces for a specific bss_account_id.<br/>
Use 'total_count' for including total number of public catalogs for a specific account.

bss_account_id

string

"Used for listing catalogs, projects, or spaces for the account, or for retrieving the number of public catalogs for the account. Must be supplied when caller is an accredited service."

"If caller is a non-service id user, then the catalogs from that user's bss account are included in the list.

roles

string

Filter results by user roles. Use comma separated list for multiple roles. Valid role value: admin, editor, viewer. This param is not allowed if caller is from accredited service or ICIP mode is enabled.

orderby

array

orderby. This parameter can be repeated to add additional sort fields. <br><br>Default: null

Supported sort fields (these are case insensitive):

catalog_name_asc
catalog_name_desc
create_time_asc
create_time_desc
update_time_asc
update_time_desc

exclude_subtypes

boolean

(DEPRECATED) Indicates whether results should include catalogs with a subtype. If not specified, catalogs with a subtype are excluded.This parameter is deprecated. Use 'subtype' instead.

subtype

array

Filter results by catalogs with the specified subtypes.

If nothing is specified, by default catalogs with subtype are not returned.

If set to 'NO_SUBTYPES', catalogs with subtype are not returned
If set to 'ALL_SUBTYPES', only catalogs with a subtype are returned
If set to 'ALL_SUBYTPES, NO_SUBTYPES', both catalogs which have subtypes and not are returned
If set to 'subtypeA, subtypeB' , only catalogs with those subtypes are returned.

name

string

Filter results by catalogs with a case insensitive name. This matches substrings.

governance_type

string

Filter results by catalogs with the specified governance type. Allowed values: governed, ungoverned, all. Default: all

Response

200 - OK

catalogs

array

nextBookmark

string

nextSkip

integer

totalCount

integer

400 - Bad Request

401 - Unauthorized

403 - Forbidden

catalogadmin@mycompany.com", "bucket": { "bucket_type": "assetfiles" } } ``` ">

Create a catalog

POST /v2/catalogs

Use this API to create a catalog to organize your assets and collaborators. You can use a catalog to easily find and share data for your organization, regardless of the location or format of the data.

On IBM Cloud, to create a catalog you must have the Manager role in your organization's IBM Knowledge Catalog account.<br/> In CPD, to create a catalog you must have the Administrator role.

The catalog name can be 1 to 256 printable Unicode characters - ISO control characters and Unicode Special characters are not permitted.

On IBM Cloud, IBM Cloud Object Storage (S3 API) credentials are required in the request body's `bucket` structure. This provides encrypted storage for file assets that are copied to the catalog.

string

UID

subtype

string

configurations

CatalogAssetContainerConfiguration

duplicate_action

string

Action to take if duplicate assets are found for a given asset

default_duplicate_strategy

string

Default duplicate detection strategy for assets of types that do not have duplicate detection strategy defined

duplicate_strategies

array

Duplicate detection strategies of assets with specified asset types in this catalog/project/space

reporting_authorized

boolean

Authorize reporting in this catalog

default_purge_on_delete

boolean

Whether assets has to be purged on delete

default_purge_after_days

integer

Query Parameters

check_bucket_existence

boolean

Whether an existence check should be performed on the catalog bucket

check_duplicate_name

boolean

Whether to check if catalogs with the same name already exist

Response

201 - Created

metadata

object

Metadata of the Catalog instance

entity

object

Entity of the Catalog instance

href

string

URL of the Catalog instance

400 - Bad Request

401 - Unauthorized

403 - Forbidden

429 - Too Many Request

Retrieve the default catalog

GET /v2/catalogs/default

Use this API to retrieve the default catalog.

Request

Response

200 - OK

metadata

object

Metadata of the Catalog instance

entity

object

Entity of the Catalog instance

href

string

URL of the Catalog instance

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

string

UID

subtype

string

configurations

object

bucket

object

Path Parameters

Query Parameters

check_bucket_existence

boolean

Whether an existence check should be performed on the catalog bucket

check_duplicate_name

boolean

Whether to check if catalogs with the same name already exist

Response

201 - Created

catalog

CatalogCatalog

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

500 - Internal Server Error

Rehome one or more synced assets.

POST /v2/catalogs/default/rehome

Use this API for rehoming assets in a catalog that had been synced from an external OMRS repository to be native IKC assets. The API supports rehoming a single asset, or a bulk rehome of all synced data assets of specific external repository.

If the request is accepted, the response header contains the rehome request ID `x-future-id` which can then be used to monitor the request status via `/v2/catalogs/default/rehome/status?request_id=<x-future-id>`.

> Service ID is required to call this API.

Request

Path Parameters

Query Parameters

asset_id

string

Synced asset to be rehomed - if omitted, all synced assets of `source_metadata_collection_id` repository will be rehomed

source_metadata_collection_id

string

Source metadata collection id required if all assets of single external repository need to be rehomed

is_bulk_rehome

Required *

boolean

Set to true to bulk re-home all synced data assets in a catalog

catalog_id

string

Catalog containing the synced assets to be re-homed. If not specified, synced assets in the default catalog are re-homed.

Response

202 - Accepted - indicates request has been accepted

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Monitor status of rehome task

GET /v2/catalogs/default/rehome/status

Use this API to check the status of a rehome asset(s) request, using the x-future-id response header value returned by a previous `/v2/catalogs/default/rehome` request.

Request

Path Parameters

Query Parameters

request_id

string

x-future-id response header value returned by a previous rehome request

Response

200 - OK - indicates successful completion of the rehome request

202 - Accepted - indicates the rehome request corresponding to the specified request_id is still processing

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Export as a zip file containing appropriate csv files for the selected assets

POST /v2/catalogs/export_assets

This API is responsible for preparing a zip file containing csv files related to the selected assets for export.

Request

Request Body

A json object containing a list of asset IDs; maximum of 100.

Path Parameters

Query Parameters

catalog_id

Required *

string

You must provide either a catalog id, a project id, or a space id, but not more than one

export_asset_id

Required *

string

The id of the ibm_export_asset type asset

export_type

Required *

array

object

headers

object

stringHeaders

object

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Process an import asset

POST /v2/catalogs/import_assets

This API begins processing of import assets. This function is used to import lineage mappings from EMD CSV documents.

Request

Path Parameters

force

boolean

object

headers

object

stringHeaders

object

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Request temporary security credentials

POST /v2/catalogs/temporary_credentials

Request temporary security credentails that can be used for storing asset attachment files.

<B>The endpoint is currently only applicable for AWS deployments.</B>

If role_arn and external_id are supplied, the caller must be a sevice id in the allow-list 'aws_s3_administrator'. The requested credentials will have permission for accessing the resources in the bucket of the catalog or the bucket itself depending on the supplied information. The allowed combinations of the fields are:

role_arn, external_id: list and create buckets in the account that the role is defined in
role_arn, external_id, bucket_name, shared (optional, default to false), catalog_id (must be supplied if shared is true): put/get/list/delete objects in the bucket, and list multipart uploads and delete the bucket if the bucket is not shared.

If catalog_id is supplied, the caller must be a member of the catalog, or a service id that is in the allow-list 'aws_s3_administrator', 'accredited_service_editors', 'accredited_service_viewers', or 'accredited_service_exporters'. The requested credentials will have permission for accessing the resources in the bucket of the catalog or the bucket itself based on the membership.

admin or service id in allow-list 'aws_s3_administrator': put/get/list/delete objects in the bucket, and list multipart uploads and delete the bucket if the bucket is not shared.
editor or service id in allow-list 'accredited_service_editors': put/get/delete objects in the bucket
viewer or service id in allow-list 'accredited_service_viewers' or 'accredited_service_exporters': get objects in the bucket

200 - OK

access_key_id

string

AWS access key, used to identify the user interacting with AWS

secret_access_key

string

AWS secret access key, used to authenticate the user interacting with AWS

session_token

string

AWS session token. This token is retrieved from an AWS token service, and is used for authenticating that this user has received temporary permission to access some resource.

session_policy

string

Session policy applied on the role session created for the temporary credentials. The field is only available in development environment and not in production environment for performance reason.

expires_at

integer

The epoch timestamp when the credentials will expire.

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get a catalog by catalog ID

GET /v2/catalogs/{catalog_id}

Members of the catalog can use this API to retrieve information about a catalog.

Request

Path Parameters

catalog_id

Required *

string

Catalog GUID or UID

Query Parameters

bss_account_id

string

You must provide bss_account_id when querying for uid

Response

200 - OK

metadata

object

Metadata of the Catalog instance

entity

object

Entity of the Catalog instance

href

string

URL of the Catalog instance

400 - Bad Request

401 - Unauthorized

403 - Forbidden

Delete a catalog by catalog ID

DELETE /v2/catalogs/{catalog_id}

Use this API to delete a catalog if you have the Admin role.Deleting a catalog removes all items that are associated with the catalog, such as metadata for all assets in the catalog.

Request

Path Parameters

catalog_id

Required *

string

Catalog GUID

Query Parameters

delete_bucket

boolean

delete_bucket

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

Update catalog

PATCH /v2/catalogs/{catalog_id}

Use this API to update the name or description of the catalog.

Request

Request Body

CatalogJsonPatch

JSON array of patch operations as defined in RFC 6902.<br/>[ { "op": "replace", "path": "/entity/name", "value": "new-name" },<br/>{ "op": "replace", "path": "/entity/description", "value": "new-description" } ] <br/> Note: <br/> Any ‘~’ characters need to be escaped as ~0 in the path field. <br/> Any ‘/’ characters need to be escaped as ~1 in the path field. <br/> For example, in {"foo/" : {"~bar" : "value"}}, the path for "~bar" is "/foo~1/~0bar".

Path Parameters

catalog_id

Required *

string

catalog GUID

Query Parameters

check_duplicate_name

boolean

Whether to check if catalogs with the same name already exist. Only applicable if the name is to be updated.

Response

200 - OK

metadata

object

Metadata of the Catalog instance

entity

object

Entity of the Catalog instance

href

string

URL of the Catalog instance

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

500 - Internal Server Error

Get a catalog-level collection by collection ID

GET /v2/catalogs/{catalog_id}/collections/{collection_id}

Use this API to retrieve a catalog-level collection in catalog.

Request

Path Parameters

catalog_id

Required *

string

catalog GUID

collection_id

Required *

string

Collection GUID

Query Parameters

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Update a catalog-level collection for a catalog

PUT /v2/catalogs/{catalog_id}/collections/{collection_id}

Update a catalog-level collection for a catalog

Request

Request Body

CatalogCollection

Collection updates

name

string

application_label

string

assets

array

tags

array

Path Parameters

catalog_id

Required *

string

catalog GUID

collection_id

Required *

string

Collection GUID

Query Parameters

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Delete a catalog-level collection by collection id

DELETE /v2/catalogs/{catalog_id}/collections/{collection_id}

Use this API to retrieve a catalog-level collection in catalog.

Request

Path Parameters

catalog_id

Required *

string

catalog GUID

collection_id

Required *

string

Collection GUID

Query Parameters

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

List all members of the catalog

GET /v2/catalogs/{catalog_id}/members

Get members for the catalog.

Request

Path Parameters

catalog_id

Required *

string

catalog GUID

Query Parameters

limit

integer

limit

bookmark

string

bookmark

member_type

string

member_type

Response

200 - OK

total_results

integer

members

array

nextBookmark

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Add members to a catalog

POST /v2/catalogs/{catalog_id}/members

Adds members to a catalog. A catalog member can be a user (specified as a user name or user ID), a service ID, or an access group.

Request

Request Body

CatalogMemberSet

Members with roles

members

Required *

array

Path Parameters

catalog_id

Required *

string

catalog GUID

Query Parameters

Response

200 - OK

members

array

failures

array

trace

string

201 - Created

members

array

failures

array

trace

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Delete members from a catalog

DELETE /v2/catalogs/{catalog_id}/members/bulk

Delete members from a catalog.You can delete a member or more if you are the owner of the catalog or a member of the catalog with Admin or Editor permissions on the catalog.

Request

Path Parameters

catalog_id

Required *

string

catalog GUID

Query Parameters

member_ids

Required *

string

Comma-separated list of Member GUIDs, with a maximum of 20.

member_type

string

Type of the members specified in the `member_ids` parameter. Specify `user` or `group` if all members are user or access group IDs. If `member_ids` contains a mixture of user or group IDs, then specify `all` for `member_type` or alternatively do not specify any value. If `member_type` is `all` or not specified, use `member_types` to indicate the type of each member in `member_ids`

member_types

string

Comma-separated list of types for each member specified in `member_ids`. The supported types are `user` and `group`. If both `member_types` and `member_type` parameters are specified, `member_types` takes precedence over `member_type`. If `member_types` is not specified, and `member_type` is not specified or is `all`, the API will attempt to determine the member type based on the member ID. In a CPD environment, user and access group IDs are numeric and have no prefix indicating whether the ID represents a user or group ID, so `member_types` should be specified if `member_ids` contains a mixture of user and access group IDs

Response

207 - Check response body for status of each member being deleted

responses

array

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Get catalog membership for a specific user

GET /v2/catalogs/{catalog_id}/members/{member_id}

Returns any memberships this user has on the catalog, including direct membership and any access group memberships.

Request

Path Parameters

catalog_id

Required *

string

catalog GUID

member_id

Required *

string

member ID

Query Parameters

resolve_member_roles

boolean

Should resolve member roles from usergroup(s) and collaborator roles

member_type

string

profile_id

string

IAM Profile ID for Trusted Profile users: If the getMemberV2 API is called to fetch details for a Trusted Profile, the member_id is the IAM ID of the actual user, and the profile_id will be the IAM ID of the trusted user. For IBM users and App ID users, this value should be null.

Response

200 - OK

members

array

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Delete a member from a catalog

DELETE /v2/catalogs/{catalog_id}/members/{member_id}

Delete a member from a catalog.

Request

Path Parameters

catalog_id

Required *

string

catalog GUID

member_id

Required *

string

Member GUID

Query Parameters

member_type

string

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Update members in a catalog

PATCH /v2/catalogs/{catalog_id}/members/{member_id}

Update a member of a catalog.

Request

Request Body

CatalogMemberRole

Member updates

role

string

Path Parameters

catalog_id

Required *

string

catalog GUID

member_id

Required *

Identity and Access Management ID (IAM) of the member

access_group_id

string

ID of the access group member

role

string

Role of the member in the Catalog

roles

array

href

string

create_time

string

Read only - The date and time when the member is added to the catalog

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

List all properties of a catalog

GET /v2/catalogs/{catalog_id}/properties

Use this API to get all properties of catalog.

Request

Path Parameters

catalog_id

Required *

string

catalog GUID

Query Parameters

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Update catalog properties

PATCH /v2/catalogs/{catalog_id}/properties

Use this API to patch catalog properties.

Request

Request Body

CatalogJsonPatch

JSON array of patch operations as defined in RFC 6902.<br/>[ { "op": "add", "path": "/properties/new-property", "value": "new-value" } ] <br/> Note: <br/> Any ‘~’ characters need to be escaped as ~0 in the path field. <br/> Any ‘/’ characters need to be escaped as ~1 in the path field. <br/> For example, in {"foo/" : {"~bar" : "value"}}, the path for "~bar" is "/foo~1/~0bar".

Path Parameters

catalog_id

Required *

string

catalog GUID

Query Parameters

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

500 - Internal Server Error

Get a single property in a catalog

GET /v2/catalogs/{catalog_id}/properties/{property_key}

Use this API to get the property of catalog by given property key.

Request

Path Parameters

catalog_id

Required *

string

catalog GUID

property_key

Required *

string

catalog property key

Query Parameters

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Update catalog connections

PATCH /v2/catalogs/{catalog_id}/reconfigure

Use this API to patch catalog properties.

Request

Path Parameters

catalog_id

Required *

string

catalog GUID

Query Parameters

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

409 - Conflict

500 - Internal Server Error

Get the catalog state

GET /v2/catalogs/{catalog_id}/state

CatalogDataAsset

Data Asset Metadata

metadata

CatalogAssetMetadata

AssetMetadata Model

name

Required *

string

Choose Any Name for your Asset

description

string

Required *

string

source_system

object

Source System Info

child_source_systems

array

source_system_history

array

History of external repository assets that were the source of an imported/synced/rehomed asset.

entity

Required *

object

attachments

array

Path Parameters

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get a data asset

GET /v2/data_assets/{data_asset_id}

Use this API to retrieve metadata about a data asset. The response document will contain three top-level fields:<br/>

'metadata': contains metadata common to all types of assets
'entity': contains metadata specific to the asset_type - in this case 'data_asset'
'attachments': an array containing one item of metadata per attached resource<br/><br/>The data described by the above metadata is stored in attached resources. Examples of attached resources are database tables, csv files, word documents, extended metadata documents, etc. Because an item in the 'attachments' array only contains metadata about an attached resource, accessing the actual attached resource requires additional server calls. Exactly which additional server calls are needed depends on the kind of attached resource. Follow the steps below to access an attached resource.<br/><br/> Step 1: find the index i of the item in the above 'attachments' array whose 'asset_type' value matches the type of the attached resource you want to access. For a 'data_asset' attached resource look for the item i where 'attachments[i].asset_type' is 'data_asset'.<br/><br/>There are two important pairs of fields (among many others) which may appear in 'attachments[i]'. Only one of those pairs will actually appear. Which pair appears influences which steps to perform next.<br/>
Pair 1: 'connection_id' and 'connection_path':
- The above two fields will appear in 'attachments[i]' if the value of 'attachments[i].is_remote' is true.
- 'attachments[i].is_remote' WILL be true if the attached resource is a database table. In this case, 'attachments[i].connection_path' will contain a schema name and table name.
- 'attachments[i].is_remote' MAY be true if the attached resource is, for example, a csv file. In this case, 'attachments[i].connection_path' will contain a folder path and file name.<br/><br/>If the above pair of fields are present in 'attachments[i]' then:<br/> Step 2: use the value of the 'attachments[i].connection_id' field to make a call to the GET /v2/connections/{connection_id} API. You'll need appropriate credentials.<br/> Step 3: use the values in the 'entity.properties' field of the result from Step 2 to either create a connection to the database containing the table or to retrieve the file.<br/><br/>Note: even if 'attachments[i].is_remote' is true and the above pair of fields are present in 'attachments[i]', if the attached resource is located in the catalog/project bucket then you may optionally perform the two steps discussed for Pair 2 ('object_key' and 'handle') below.<br/>
Pair 2: 'object_key' and 'handle':
- The above two fields will appear in 'attachments[i]' if the value of 'attachments[i].is_remote' is false. In this case, 'attachments[i].handle' will contain information about the attached resource.<br/> Step 2: use the value of the 'attachments[i].id' field as the value for 'attachment_id' in a call to the GET /v2/assets/{asset_id}/attachments/{attachment_id} API. The value to use for 'asset_id' in the call to the attachments API is the same as the value that was used for 'data_asset_id' in the original call to the GET /v2/data_assets/{data_asset_id} API.<br/> Step 3: use the value in the 'url' field of the result from Step 2 to download (for example, with a browser) a copy of the file.

Request

Path Parameters

data_asset_id

Required *

string

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get columns of a data asset

GET /v2/data_assets/{data_asset_id}/columns

Use this API to retrieve columns of a data asset located in catalog or project. Access to an asset is controlled by a combination of the privacy level and the members of the asset. For a governed catalog, data assets are protected from unauthorized access by the governance policies that are defined in Data Catalog. Data assets in ungoverned catalogs are not subject to governance policies.

Request

Path Parameters

data_asset_id

Required *

string

200 - OK

total_rows

integer

resources

array

bookmark

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

500 - Internal Server Error

Create a folder asset

POST /v2/folder_assets

You can use this API to add folder assets to a catalog. Folder assets are similar to folders or directories in a file system. In the same way that a directory in a file system can contain many files, a folder asset can represent groups of files or objects all sharing a common path. An example of a path may be '/sales_data/by_month/february'. There may be many different files with that common path, but we only need to register just the common path when we create a folder asset.<br/><br/>Along with other types of assets, such as data assets, folder assets share a common set of properties such as name, description, asset type, visibility, tags, classifications, etc. In addition to other types of assets, folder assets are denoted by a `folder_asset` json object within the common `entity` object. The `folder_asset` json object contains a `connection_id`, and a `connection_path`. E.g.,

``` { "metadata":{...}, "entity":{ "folder_asset":{ "connection_id":"f1fea17c-a7e5-49e4-9f8e-23cef3e11ed5", "connection_path":"/bucket1/folder1/folder1.1" } } } ``` <br/>A folder asset can be mediated by a connection. In other words, you can access the contents of the folder asset only through a connection in the connection service. The connection can be to any external data store such as DashDB, Salesforce.com,IBM's Cloud Object Storage, etc. You must specify the `connection_id` and the `connection_path` within the `folder_asset` json object. <br/><br/>Folder assets can also be local to the catalog or project, similar to local or referenced data attachments. For such a folder asset you don't need the connection_id in the `folder_asset` json. You only need to provide the connection_path. The API can use it's internal connection to asset storage associated with the catalog/project/space (Cloud Object Storage in IBM Cloud, or Asset Files storage in CPD) for accessing that folder.<br/><br/>A connection path is like the path of a folder or a directory in a file system. Using IBM Cloud Object Storage as an example, a `connection_path` for a folder object might be `/Bucket1/monthly_data_collection/March`. Any objects falling under that path are part of the folder asset. This API cannot show you those files directly. Instead, you can use your IBM Cloud Object Storage connection to traverse to that folder location and retrieve the files.

Request

Request Body

CatalogFolderAsset

Folder Asset Metadata

metadata

CatalogAssetMetadata

AssetMetadata Model

name

Required *

string

Choose Any Name for your Asset

description

string

Required *

string

source_system

object

Source System Info

child_source_systems

array

source_system_history

array

History of external repository assets that were the source of an imported/synced/rehomed asset.

entity

Required *

object

attachments

array

Path Parameters

href

string

attachments

CatalogAttachment

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get a folder asset

GET /v2/folder_assets/{asset_id}

Use this API to retrieve metadata about a folder asset.

Request

Path Parameters

asset_id

Required *

string

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get a signed URL of an item to be downloaded

GET /v2/folder_assets/{asset_id}/contents

If you have created folder assets for things that you store in IBM Cloud Object Storage, you can download individual contents of that folder. Every item within a folder has a path within that folder. For example there may be a folder asset in IBM Cloud Object Storage whose path is `/bucket1/retail_sales/cosmetics`. Within that folder, there may be several individual files. You can download these files with this API. When you call the API, you will receive a URL that, when you invoke it with a GET HTTP command, you can download a file that is within that folder.

Request

Path Parameters

asset_id

Required *

string

Enter the id of the folder asset whose content you want to download.

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

path

Required *

string

The path to the object from where the folder leaves off. For example if your folder path is `/Bucket1/homedecore` and your object path is `/bathrooms/sinkaccessories/soapdish1000.jpg` then the API will return a signed URL that includes the full object key `/Bucket1/homedecore/bathrooms/sinkaccessories/soapdish1000.jpg`.

content_type

string

The type of content you will download. Default is `application/octet-stream`

content_disposition

string

content_disposition specifies how you want the content downloaded. The default is as an attachment (i.e. a separate file).

Response

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

List all assets in the trash (Marked for delete)

GET /v2/trashed_assets

Retrieve all assets in the trash (Marked for delete.

Request

Path Parameters

limit

integer

limit

bookmark

string

bookmark

Response

201 - Created

400 - Bad Request

401 - Unauthorized

403 - Forbidden

trashed_assets_count

integer

Count of trashed assets

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Delete all assets from trash

DELETE /v2/trashed_assets/purge_all

Delete all assets from trash.

If number of assets in trash is less than or equal to 20 , the assets will be deleted synchrnonously and response will be 204 - No Content.

If number of assets in trash is more than 20, the assets will be deleted asynchrnonously, response will be 202 - Accepted and the status can be tracked using `/v2/trashed_assets/count`.

Request

Path Parameters

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

202 - Accepted

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Get a soft-deleted object from trash

GET /v2/trashed_assets/{asset_id}

Get a soft-deleted object from trash.

Request

Path Parameters

asset_id

Required *

string

string

Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.

hide_deprecated_response_fields

boolean

Response

200 - OK

metadata

CatalogResponseAssetMetadata

entity

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Delete an asset from the trash

DELETE /v2/trashed_assets/{asset_id}

Purge an asset from the trash.

Request

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Restore an asset from the trash

POST /v2/trashed_assets/{asset_id}/restore

Restore an asset from the trash.

Request

Path Parameters

asset_id

Required *

string

asset_id

Query Parameters

catalog_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

project_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

space_id

string

You must provide either a catalog id, a project id, or a space id, but not more than one

exclude

string

Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.

hide_deprecated_response_fields

boolean

duplicate_action

string

Response

200 - OK

metadata

CatalogResponseAssetMetadata

entity

object

attachments

array

Depending on the API, either asset_attachments or attachments will be present.

href

string

asset_id

string

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal Server Error

Field Example entity.name ?_sort=+entity.name metadata.create_time ?_sort=-metadata.create_time

Use the following parameters to filter the results:

Field	Example
entity.name	?entity.name=MyConnection
entity.datasource_type	?entity.datasource_type=<asset_id>
entity.context	?entity.context=source
entity.properties	?entity.properties={"name":"value"}
entity.flags	?entity.flags=+personal_credentials
metadata.creator_id	?metadata.creator_id=userid

Filtering is done by specifying the fields to filter on.

To filter on the properties of a connection, the exact values to compare must be provided in the entities.properties field and all values supplied must exactly match a property of a connection.

The entity.flags field specifies the flags a connection can have to be included in the list results. By default, all connections with no flags are returned.

Adding the name of a flag to entity.flags will add the connections with that flag to the list results. The name can be optionally prefixed with a plus sign (+) to indicate that it is being added.

Adding the name of a flag to entity.flags with a minus sign (-) prefix will remove those connections with that flag from the list results. All additions are done before the subtractions. ">

List defined connections

GET /v2/connections

Lists defined connections.

Connections created with shared credentials will return secrets such as database passwords and API keys in clear text. Such secrets are stored encrypted but will be decrypted by the API when retrieved by the caller in order to access the data source defined by the connection. Clear text credentials are allowed because it is understood that the caller has already been explicitly added as a collabaorator in the project or catalog in which the connection is stored and is thus implicitly permitted access to the credentials required to connect to a data source.

Connections created with personal credentials will only display clear text credentials to the same user who provided them.

Use the following parameters to sort the results:

Field	Example
entity.name	?_sort=+entity.name
metadata.create_time	?_sort=-metadata.create_time

Use the following parameters to filter the results:

Field	Example
entity.name	?entity.name=MyConnection
entity.datasource_type	?entity.datasource_type=<asset_id>
entity.context	?entity.context=source
entity.properties	?entity.properties={"name":"value"}
entity.flags	?entity.flags=+personal_credentials
metadata.creator_id	?metadata.creator_id=userid

Filtering is done by specifying the fields to filter on.

To filter on the properties of a connection, the exact values to compare must be provided in the entities.properties field and all values supplied must exactly match a property of a connection.

The entity.flags field specifies the flags a connection can have to be included in the list results. By default, all connections with no flags are returned.

Adding the name of a flag to entity.flags will add the connections with that flag to the list results. The name can be optionally prefixed with a plus sign (+) to indicate that it is being added.

Adding the name of a flag to entity.flags with a minus sign (-) prefix will remove those connections with that flag from the list results. All additions are done before the subtractions.

Request

Path Parameters

Whether to return information about connection and interaction properties.

Response

200 - Connections with metadata.

resources

array

List of connections

first

HrefModel

last

HrefModel

offset

integer

The number of assets skipped before this page.

total_count

integer

The total number of assets available.

401 - You are not authorized to list the defined connections.

403 - You are not permitted to perform this action.

Define connection

POST /v2/connections

Defines a connection.

By default, a connection is created with shared credentials. Though credentials' secrets are stored encrypted, all credentials including secrets will be visible in clear text to API users who retrieve the connection and who are collaborators of the project or catalog in which a connection with shared credentials has been created.

Alternatively, a connection can be created with personal credentials by using the personal_credentials flag. The credentials' secrets will be visible only to the user who created the connection.

Request

Request Body

ConnectionsConnectionEntity

The definition of the connection.

datasource_type

Required *

sovereign_location_code

string

The code of the sovereign location.

Path Parameters

Query Parameters

test

boolean

Whether to test the connection before saving it. By default an attempt to establish a connection will be made, and the connection will not be saved if the connection cannot be established.

persist

boolean

Whether to persist assets or changes on assets. If set to false, it makes the service to perform all the actions on the way, execute testing, inject properties (like satellite properties or vault properties), if applicable, and then return the object as it would look like if persisted + with all the usual additioanl elements of response properties returned via Java API (like interaction_properties), but metadata record itself that gets filled with properties from the response from CAMS service is not filled, so it only contains those properties that are set directly from the entity taken from payload.

Response

201 - The connection was created.

metadata

ConnectionsConnectionAssetSystemMetadata

System metadata about an asset

entity

ConnectionsConnectionEntity

The connection definition.

400 - The connection test failed. See the error message for details.

trace

string

errors

array

401 - You are not authorized to define a connection.

403 - You are not permitted to perform this action.

Get connection

GET /v2/connections/{connection_id}

Gets details of a specific connection definition.

Connections created with personal credentials will only display clear text credentials to the same user who provided them.

Request

Path Parameters

Query Parameters

entity.product

string

Specify the product the data source type must support to be returned. The available products are 'catalog', 'cpd', 'datastage', 'dv', 'igc', 'mdi', 'ml' and 'studio'. If no entity.product is specified, no filtering is applied. To specify multiple products, use a comma-separated string, such as entity.product=catalog,studio.

interaction_properties

boolean

Whether to return information about source and target interaction properties.

decrypt_secrets

boolean

Whether to return decrypted secrets for unrestricted connections.

Response

200 - The connection object.

metadata

ConnectionsConnectionAssetSystemMetadata

System metadata about an asset

entity

ConnectionsConnectionEntity

The connection definition.

401 - You are not authorized to get details about the connection.

403 - You are not permitted to perform this action.

404 - The connection cannot be found.

trace

403 - You are not permitted to perform this action.

Update connection

PATCH /v2/connections/{connection_id}

Updates the definition of a connection.

Request

Request Body

Fields to update within the connection.

Path Parameters

Query Parameters

test

boolean

Whether to test the connection before saving it. By default an attempt to establish a connection will be made, and the connection will not be saved if the connection cannot be established.

persist

boolean

Response

The ID of the connection in reference catalog that this connection refers to for properties values.

gateway_id

string

flags

array

Specifies how a connection is to be treated internally.

origin_country

string

Country which data originated from. - ISO 3166 Country Codes.

owner_id

string

Owner or creator of connection. Provided when a service ID token is used to create connection.

rov

ConnectionsConnectionRov

Rules of visibility for connections.

properties

ConnectionsConnectionProperties

Connection properties.

interaction_properties

ConnectionsConnectionInteractionProperties

Interaction properties allowed for a connection.

source_system

ConnectionsCommonCustomObject

Custom data to be associated with a given object

source_system_history

array

asset_category

string

The asset category

child_source_systems

array

tags

array

location_definition

ConnectionsLocationDefinition

Indicates the location used by this connection.

400 - The connection test failed. See the error message for details.

trace

string

errors

array

401 - You are not authorized to update the connection definition.

403 - You are not permitted to perform this action.

Copy connection

POST /v2/connections/{connection_id}/copy

Copy a connection.

The copy connection is created with same attributes as source connection, and the credentials will be removed from target connection. If source connection is personal, then copy connection will also have the personal_credentials flag.

Request

Path Parameters

Query Parameters

Response

201 - The connection was created.

metadata

ConnectionsConnectionAssetSystemMetadata

System metadata about an asset

entity

ConnectionsConnectionEntity

The connection definition.

400 - The connection test failed. See the error message for details.

trace

string

errors

array

401 - You are not authorized to define a connection.

403 - You are not permitted to perform this action.

Discover assets

POST /v2/connections/assets

Discovers assets from the data source accessed via a connection description.

Request

Request Body

ConnectionsConnectionEntity

The connection definition.

datasource_type

Required *

ref_catalog_id

string

The ID of the catalog that this connection refers to for properties values.

ref_asset_id

string

The ID of the connection in reference catalog that this connection refers to for properties values.

sovereign_location_code

string

The code of the sovereign location.

Path Parameters

Query Parameters

path

Required *

The data returned when the fetch parameter contains the value "data".

details

ConnectionsDiscoveredAssetDetails

Details about a discovered asset.

first

HrefModel

last

HrefModel

offset

integer

The number of assets skipped before this page.

total_count

integer

The total number of assets available.

logs

array

Log events created during the discovery of the assets.

401 - You are not authorized to discover assets.

403 - You are not permitted to perform this action.

Discover assets

GET /v2/connections/{connection_id}/assets

Discovers assets from the data source accessed via the connection.

Request

Path Parameters

connection_id

Required *

The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.

fetch

string

detail

boolean

Specify whether to return additional asset-specific details. If not specified, these details are not returned.

context

string

Specify whether assets are discovered for the purpose of reading (source) or writing (target). If not specified, source is used by default.

properties

string

A JSON object containing a set of properties to configure aspects of the asset browsing.

filters

string

A JSON object containing a set of properties to define filtering of the assets to be returned.

Response

The data returned when the fetch parameter contains the value "data".

details

ConnectionsDiscoveredAssetDetails

Details about a discovered asset.

first

HrefModel

last

HrefModel

offset

integer

The number of assets skipped before this page.

total_count

integer

The total number of assets available.

logs

array

Log events created during the discovery of the assets.

401 - You are not authorized to discover assets in the data source accessed through the connection.

403 - You are not permitted to perform this action.

The ID of the project to use. catalog_id, project_id, or space_id is required.

space_id

string

The ID of the space to use. catalog_id, project_id, or space_id is required.

userfs

boolean

true for a project needs assets managed by the /userfs API, i.e. if it has git integration

limit

integer

The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.

offset

integer

The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.

The data returned when the fetch parameter contains the value "data".

details

ConnectionsDiscoveredAssetDetails

Details about a discovered asset.

first

HrefModel

last

HrefModel

offset

integer

The number of assets skipped before this page.

total_count

integer

The total number of assets available.

logs

array

Log events created during the discovery of the assets.

401 - You are not authorized to discover the asset.

403 - You are not permitted to perform this action.

The ID of the project to use. catalog_id, project_id, or space_id is required.

space_id

string

The ID of the space to use. catalog_id, project_id, or space_id is required.

userfs

boolean

true for a project needs assets managed by the /userfs API, i.e. if it has git integration

Response

200 - The actions supported for the connection.

actions

array

The actions supported for the data source.

401 - You are not authorized to list the actions for the connection.

403 - You are not permitted to perform this action.

Perform action

PUT /v2/connections/{connection_id}/actions/{action_name}

Performs an action on the data source accessed using the connection.

Request

Request Body

The ID of the catalog to use. catalog_id, project_id, or space_id is required.

project_id

string

The ID of the project to use. catalog_id, project_id, or space_id is required.

space_id

string

The ID of the space to use. catalog_id, project_id, or space_id is required.

userfs

boolean

true for a project needs assets managed by the /userfs API, i.e. if it has git integration

Response

200 - Any output produced by the action.

400 - The perform action request is invalid.

trace

string

errors

array

401 - You are not authorized to perform an action on a data source accessed through the connection.

403 - You are not permitted to perform this action.

Download a file

GET /v2/connections/files/{file_name}

Download a file

Request

Path Parameters

file_name

Required *

string

The name of file to download

Query Parameters

hash

Required *

string

The hash of file to download

Response

200 - The file object.

401 - You are not authorized to get content of the file.

403 - You are not permitted to perform this action.

404 - The file cannot be found.

Upload a file

POST /v2/connections/files/{file_name}

Upload a file and get back a signed handle in 'Location' header with a hash

Request

Request Body

Path Parameters

file_name

Required *

string

The name of file to upload

Query Parameters

Response

201 - The file object.

401 - You are not authorized to get content of the file.

403 - You are not permitted to perform this action.

404 - The file cannot be found.

Delete a file

DELETE /v2/connections/files/{file_name}

Delete a file

Request

Path Parameters

file_name

Required *

string

The name of file to delete

Query Parameters

hash

Required *

string

The hash of file to delete

Response

200 - The file was deleted.

401 - You are not authorized to get content of the file.

403 - You are not permitted to perform this action.

404 - The file cannot be found.

List files

GET /v2/connections/files

List files available in mounted directory

Request

Path Parameters

Query Parameters

limit

integer

The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.

offset

integer

The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.

Response

200 - List of available files

resources

array

List of uploaded files

offset

integer

The number of assets skipped before this page.

total_count

integer

The total number of assets available.

401 - You are not authorized to get the list of files.

403 - You are not permitted to perform this action.

404 - The file cannot be found.

Migrate files

PUT /v2/connections/files

Migrates files from old locations to new one

Request

Path Parameters

Query Parameters

listOnly

boolean

Indicator, if only list files to be migrated.

catalogs

boolean

Indicator, if migrate connections from catalogs.

projects

boolean

Indicator, if migrate connections from projects.

spaces

boolean

Indicator, if migrate connections from spaces.

Response

200 - List of newly uploaded files

resources

array

List of migrated connections

total_count

integer

The number of assets available.

log_file

string

The name of the log with migration process logging.

exceptions

array

List of exceptions encountered durring the migration process.

401 - You are not authorized to migrate files.

403 - You are not permitted to perform this action.

field name description entity.label The name of the data source type in a readable form. entity.type The major type of the data source type. ">

List defined types of data sources

GET /v2/datasource_types

Gets all defined types of data sources.

The following fields are available for use with the sort parameter:

field name	description
entity.label	The name of the data source type in a readable form.
entity.type	The major type of the data source type.

Request

Path Parameters

Specify the environment the data source types must support to be included in the returned list. The available environments are 'cloud', 'streams' and 'local'. If no entity.environment is specified, the default for service's deploy environment is used. To specify multiple environments, use a comma-separated string, such as entity.environment=cloud,streams.

entity.product

string

product_selector_scope

string

Scope of ui-only product selector property. Applies to output under common_properties key. Genreated ui contains additional checkbox to switch between first of the requested products and the rest. If only a single one is given it switches between that product and remaining products supported by the data source.

generate_transitive_conditions

boolean

Whether to generate extra conditions in common properties format that will make them behave in a transitive manner under default configuration options of Elyra i.e. when a condition is part of a chain it will enable/disable everything down the chain rather than just hiding the control. Support for this option has been removed. Option itself was not removed to preserve binary compatibility but it no longer has any effect.

show_data_source_definitions_only

boolean

Whether to filter the list of available datasource types and return only those that have their dataSourceDefinitionId parameter set and its value is the same as the value of the datasource type id. That means that returned are only datasource types which should have proper deep enforcement in Data Privacy Service supported and are the canonical types (not the connectors that use the same engine, but have a different flavor).

Response

200 - Collection of data source types.

resources

array

List of data source types

first

HrefModel

last

HrefModel

offset

integer

The number of assets skipped before this page.

total_count

integer

The total number of assets available.

401 - You are not authorized to list the defined types of data sources.

403 - You are not permitted to perform this action.

Define data source type

POST /v2/datasource_types

array

Path properties

properties

ConnectionsCommonCustomObject

Custom data to be associated with a given object

property_definitions

array

status

string

The status of the data source.

child_source_systems

array

origin_country

string

Country which data originated from. - ISO 3166 Country Codes.

owner_id

string

Owner or creator of connection. Provided when a service ID token is used to create connection.

rov

ConnectionsConnectionRov

Rules of visibility for connections.

mode

integer

The Rules of Visibility mode. Value can be:

member_roles

object

Contains map of key as user_iam_id and value as member_roles

source_system

ConnectionsCommonCustomObject

Custom data to be associated with a given object

source_system_history

array

tags

array

Tags associated with a data source type.

actions

GET /v2/datasource_types/{datasource_type}

Get details for type of data source.

Request

Path Parameters

datasource_type

Required *

string

The data source type.

Query Parameters

connection_properties

boolean

Whether to return information about connection properties.

interaction_properties

boolean

Whether to return information about source and target interaction properties.

discovery

boolean

Whether to return information about discovery capabilities.

actions

boolean

ConnectionsConnectionAssetSystemMetadata

System metadata about an asset

entity

ConnectionsDatasourceTypeEntity

The definition of a data source type.

401 - You are not authorized to retrieve the type details of the data source.

403 - You are not permitted to perform this action.

Delete data source type

DELETE /v2/datasource_types/{datasource_type}

Deletes a data source type definition. This call does not check whether the data source type is used by connections or other assets. The caller must check this before deleting a data source type.

Request

Path Parameters

datasource_type

Required *

string

The data source type.

Query Parameters

Response

204 - The data source type was deleted.

401 - You are not authorized to delete a data source type.

403 - You are not permitted to perform this action.

Update datasource type

PATCH /v2/datasource_types/{datasource_type}

Updates the definition of a datasource type.

Request

Request Body

Fields to update within the data source type.

Path Parameters

datasource_type

Required *

string

The data source type.

Query Parameters

Response

Custom data to be associated with a given object

property_definitions

array

status

string

The status of the data source.

child_source_systems

array

origin_country

string

Country which data originated from. - ISO 3166 Country Codes.

owner_id

string

Owner or creator of connection. Provided when a service ID token is used to create connection.

rov

ConnectionsConnectionRov

Rules of visibility for connections.

source_system

ConnectionsCommonCustomObject

Custom data to be associated with a given object

source_system_history

array

tags

array

Tags associated with a data source type.

actions

array

The actions supported for the data source.

400 - The data source type patch request is not valid. See the error message for details.

trace

string

errors

array

401 - You are not authorized to update the data source type definition.

403 - You are not permitted to perform this action.

Create a metadata enrichment area asset

POST /v2/metadata_enrichment/metadata_enrichment_area

Creates a new metadata enrichment asset and the corresponding job definition. If a data scope is provided the decoration of data scope assets will be started in background and the response will contain the execution ID of that background process. After background processing has finished a RabbitMQ event is sent to CAMS topic exchange <b>CatalogServiceMessageHub</b> with topic <b>v2.metadata_enrichment.{mdeAreaId}.create_enrichment_area</b> and message body as described in model <b>RabbitMqNotificationMessage</b>. If no data scope is provided an empty enrichment area is created without starting a background decoration task. In that case the field asyncExecutionInfo will be missing in the response. If query paramter <b>enrichImmediate</b> is true, which is the default setting, and the data scope is not empty a new enrichment job run will be triggered automatically.

Request

Request Body

DataDiscoveriesMetadataEnrichmentAreaRequest

Object containing information for creating a metadata enrichment area asset

name

Required *

object

publish_job

object

metadata enrichment area publish job

id

string

Id of the metadata publish job

name

string

enrichment_options

object

enrichment options. Required when creating and optional when updating.

governance_scope

array

Required when creating and optional when updating.

sampling

object

sampling options. Required when creating and optional when updating.

datascope_of_reruns

object

Data scope of reruns

tags

array

list of tags

Path Parameters

Query Parameters

enrichImmediate

boolean

should enrichment be run immediately after area creation

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

201 - Success

metadata

object

Metadata about a metadata enrichment area asset. Set by system, not changeable by the user.

entity

object

Properties of the metadata enrichment area asset.

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Retrieve metadata enrichment settings

GET /v2/metadata_enrichment/metadata_enrichment_area/settings

Retrieve metadata enrichment settings

Request

Path Parameters

Query Parameters

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Create or update metadata enrichment settings

PUT /v2/metadata_enrichment/metadata_enrichment_area/settings

Create or update metadata enrichment settings

Request

Request Body

Metadata enrichment settings

Path Parameters

Query Parameters

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Retrieve details of a Metadata Enrichment Area asset

GET /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}

Retrieve details of a metadata enrichment area asset

Request

Path Parameters

metadata_enrichment_area_id

Required *

string

Id of the metadata enrichment area asset.

Query Parameters

include_summary

boolean

whether to include data asset count summary in the response

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

metadata

object

Metadata about a metadata enrichment area asset. Set by system, not changeable by the user.

entity

object

Properties of the metadata enrichment area asset.

401 - Unauthorized

403 - Forbidden

404 - Not found

410 - Gone

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Delete a metadata enrichment asset

DELETE /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}

Delete a metadata enrichment area asset

Request

Path Parameters

metadata_enrichment_area_id

Required *

string

Id of the metadata enrichment area asset.

Query Parameters

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

204 - No Content

401 - Unauthorized

403 - Forbidden

404 - Not found

410 - Gone

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

edit a metadata enrichment area asset

PATCH /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}

list of tags

Path Parameters

metadata_enrichment_area_id

Required *

string

Id of the metadata enrichment area asset.

Query Parameters

force

boolean

Force the operation even when the metadata enrichment area is being updated.

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

metadata

object

Metadata about a metadata enrichment area asset. Set by system, not changeable by the user.

entity

object

Properties of the metadata enrichment area asset.

401 - Unauthorized

403 - Forbidden

404 - Not found

410 - Gone

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Add or remove assets from data scope

PATCH /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope

Add or remove assets from data scope

Request

Request Body

Object carrying the update request.

Path Parameters

metadata_enrichment_area_id

Required *

string

Id of the metadata enrichment area asset.

Query Parameters

force

boolean

Force the operation even when the metadata enrichment area is being updated.

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

202 - Accepted

401 - Unauthorized

403 - Forbidden

404 - Not found

410 - Gone

500 - Error

trace

string

Id of the metadata enrichment area asset.

Query Parameters

async

boolean

whether to process the request asynchronously

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

202 - Accepted

execution_id

string

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Assign business terms to columns of data assets

POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/columns/assign_terms

Add terms to given asset columns. This api is executed synchronously. It verifies that all assets are part of the given MDE area. If validation fails method ends with an error.

Request

Request Body

DataDiscoveriesColumnTermAssignmentOptions

List of columns of data assets and terms to assign

dataasset_columns

Required *

array

terms

Required *

array

Path Parameters

metadata_enrichment_area_id

Required *

string

Id of the metadata enrichment area asset.

Query Parameters

async

boolean

whether to process the request asynchronously

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

202 - Accepted

execution_id

string

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Assign or remove a data class to columns of data assets

POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/columns/dataclass

Assign or remove data class to columns of data assets

Request

Request Body

List of columns of data assets and id of data class and operation to be performed

Path Parameters

metadata_enrichment_area_id

Required *

string

Id of the metadata enrichment area asset.

Query Parameters

async

boolean

whether to process the request asynchronously

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Remove business terms from columns of data assets.

POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/columns/remove_terms

Removes either all terms or selected terms from given asset columns. When terms are provided with the payload only the given terms are removed from the given columns. If no terms are provided all terms are removed.

Request

Request Body

DataDiscoveriesColumnTermAssignmentOptions

List of columns of data assets and terms to assign

dataasset_columns

Required *

array

terms

Required *

array

Path Parameters

metadata_enrichment_area_id

Required *

string

Id of the metadata enrichment area asset.

Query Parameters

async

boolean

whether to process the request asynchronously

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

202 - Accepted

execution_id

string

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Adds or updates the review timestamp for given columns.

POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/columns/review

Adds/updates the 'reviewed' time stamp to/of the given asset columns.This api is executed synchronously. It fetches the assets that belong to the given columns via CAMS bulk get and verifies that all given assets are part of the given MDE area and are ready for review which means that either profiling or term assignment must be finished. It also validates that the columns exist on the asset. If validation fails the method returns an error. Otherwise for all given columns the review timestamp gets updated via CAMS bulk patch. Returns the new review timestamp.

Request

Request Body

Array containing list of asset Ids with columns.

Path Parameters

metadata_enrichment_area_id

Required *

string

Id of the metadata enrichment area asset.

Query Parameters

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

review_date

integer

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Removes review timestamp for given columns.

POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/columns/unreview

Removes the 'reviewed' time stamp from the given asset columns. This api is executed synchronously. It fetches alle assets that belong to the given columns via CAMS bulk get and verifies that all given assets are part of the given MDE area. Assets that have no review data are skipped. It also validates that the columns exist on the asset. If validation fails the method returns an error. Otherwise for all given columns the review timestamp will be removed via CAMS bulk patch.

Request

Request Body

Array containing list of asset Ids with columns.

Path Parameters

metadata_enrichment_area_id

Required *

string

Id of the metadata enrichment area asset.

Query Parameters

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

204 - No content

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Enrich selected data assets

POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/enrich

Enrich selected data assets

Request

Request Body

job_run_id

string

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

Id of the metadata enrichment area asset.

Query Parameters

async

boolean

whether to process the request asynchronously

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

202 - Accepted

execution_id

string

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Review a given list of data assets.

POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/review

Adds/updates the 'reviewed' time stamp to/of given data assets. This api is executed synchronously. It fetches the given assets via CAMS bulk get and verifies that all given assets are part of the given MDE area and are ready for review which means that either profiling or term assignment must be finished. If validation fails the method returns an error. Otherwise the review timestamp of all assets gets updated via CAMS bulk patch. Returns the new review timestamp.

Request

Request Body

Array containing list of asset Ids.

Path Parameters

metadata_enrichment_area_id

Required *

string

Id of the metadata enrichment area asset.

Query Parameters

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

review_date

integer

400 - Bad Request. If parameters are missing or at least one of the given assets is not ready for review

401 - Unauthorized

403 - Forbidden

404 - Not found. If at least one of the given assets is not member of the given metadata enrichment area.

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Removes review timestamp from the given assets

POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/data_scope/enrichment_assets/unreview

Removes the 'reviewed' time stamp from the given data assets. This api is executed synchronously. It fetches the given assets via CAMS bulk get and verifies that all given assets are part of the given MDE area. Assets that have no review data are skipped. If validation fails the method returns an error. Otherwise the review timestamp is removed from of all assets via CAMS bulk patch.

Request

Request Body

Array containing list of asset Ids.

Path Parameters

metadata_enrichment_area_id

Required *

string

Id of the metadata enrichment area asset.

Query Parameters

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

204 - No content

400 - Bad Request. If parameters are missing.

401 - Unauthorized

403 - Forbidden

404 - Not found. If at least one of the given assets is not member of the given metadata. enrichment area.

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Publish all assets or a subset of assets of a Metadata Enrichment Area to a catalog

POST /v2/metadata_enrichment/metadata_enrichment_area/{metadata_enrichment_area_id}/publish_assets

Publish assets asynchronously. If publishScope is 'selected_assets' either /asset_ids or /filter/search_criteria has to be specified. If publisScope is 'all_assets' none of both must be specified.

Request

Request Body

DataDiscoveriesPublishRequest

Publish assets to a catalog

catalog

Required *

string

catalog Id

duplicate_action

object

action if asset already exists

asset_ids

array

IDs of assets to enrich metadata

filter

object

type

Required *

object

type of search

asset_type

Required *

string

Asset type for catalog search.

Required *

tells if all assets in mde area should be published or only selected assets

Response

200 - Success

job_id

string

job_run_id

string

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Create a Metadata Import asset

POST /v2/metadata_imports

Create a Metadata Import asset.

Request

Request Body

DataDiscoveriesMetadataImportRequest

Object containing information for creating a metadata import asset

unified_lineage

boolean

label to identify new architecture

datasource_definition_info

object

ingestion_agent_id

string

ingest_method

string

ingest_connection

string

name

Required *

string

name of the metadata import asset

import_type

object

The type of the import. The possible values are 'metadata' and 'lineage'.

connection_id

string

Id of the connection which is being discovered

connection_id_list

array

List of connection_id which is being discovered

file_list

array

List of configuration/datasource files for which metadata/lineage has to be extracted.

file_configuration

object

encoding

string

enable_replacement

string

replacements

array

workspace_root_paths

array

List of workspace rootPath.

asset_ref_map

object

asset ref map when trying to export and import a project .

reimport_options

object

object

added_date

string

area_id

string

goal

object

The goal the import. The possible values are 'metadata','lineage',`data_model`, `data_integration`, `data_integration_discover`, `business_intelligence`, `business_intelligence_discover` and `open_manta`

Path Parameters

Query Parameters

create_job

boolean

If this value is set to true, a Job is created together. The relation is also done between mdetadata import asset. The response message includes entity.jobId. The job name is generated from the name of metadata import with a unique suffix.

job_name

string

A candidate of Job name. The job is created with a specified name. If the name already exists, an error is returned. The create_job parameter should be set to true.

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

201 - Success

metadata

object

Metadata about a metadata import asset. Set by system, not changeable by the user.

entity

object

Properties of the metadata import asset.

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Bulk delete data assets in Metadata discovery

POST /v2/metadata_imports/bulk_delete_assets

Delete assets in bulk

Request

Request Body

Array containing list of data asset Ids.

Path Parameters

Query Parameters

catalog_id

string

The catalog_id and / or project_id must be provided. If catalog_id is provided, the catalog must exist and the caller must be an admin or editor member of the catalog. Only data discovery runs associated with the catalog will be returned.

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

201 - Success

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Bulk delete metadata import assets in Metadata discovery

DELETE /v2/metadata_imports/bulk_delete_metadataImport_assets

Delete metadata import assets in bulk

Request

Path Parameters

Query Parameters

asset_ids

Required *

string

Comma separated list of metadata import asset IDs.

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

201 - Success

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Bulk publish data assets in Metadata discovery

POST /v2/metadata_imports/bulk_publish_assets

Publish assets in bulk

Request

Request Body

Array containing list of data asset Ids.

Path Parameters

Query Parameters

catalog_id

string

connection_id

Required *

string

The connection_id may be optionally provided to retrieve data discovery runs associated with the connection.

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

201 - Success

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Get a list of supported datasource types

GET /v2/metadata_imports/connections

INTERNAL: Get list of supported connection types.

Request

Response

200 - Success

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Start a Metadata Import job

POST /v2/metadata_imports/job_runs

INTERNAL: Run a Metadata Import job.

Request

Request Body

DataDiscoveriesJob

Job definition object

metadata

object

AssetMetadata Model

name

Required *

string

description

string

asset_id

string

asset_category

Required *

string

asset_type

Required *

string

origin_country

tags

array

entity

object

The underlying job definition.

job

object

Path Parameters

Query Parameters

job_id

Required *

string

Id of the metadata import job.

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

201 - Success

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

cancel a Metadata Import run

POST /v2/metadata_imports/job_runs/cancel

INTERNAL: Cancel a metadata import job run

Request

Request Body

Job definition object

Path Parameters

Query Parameters

jobrun_id

Required *

string

Id of the metadata import job run.

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

401 - Unauthorized

403 - Forbidden

404 - Not found

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Reconcile the status of the job run record w.r.t the Discovery status

POST /v2/metadata_imports/job_runs/reconcile

INTERNAL: Reconcile the status of the job run record w.r.t the Discovery status

Request

Request Body

DataDiscoveriesJobRun

Job Run

metadata

object

AssetMetadata Model

name

Required *

string

description

string

asset_id

string

asset_category

Required *

string

asset_type

Required *

string

origin_country

Path Parameters

Query Parameters

jobrun_id

Required *

string

Id of the metadata import job run.

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

body

array

patch operations

400 - Bad Request

401 - Unauthorized

404 - Not found

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Restart the pending a job run

POST /v2/metadata_imports/recover_task

Restart the pending a job run. It should be called after restore from the backup data. This API is not unavailable on IBM Cloud. The Admin role is necessary to call this API.

Request

Request Body

DataDiscoveriesRecoveryCondition

Object containing information for recovering import

recovery_date

string

The timestamp when the data was restored (in format YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss.sssZ, matching the date-time format as specified by RFC 3339)

pending_type

object

The status that will be restarted. The possible values are 'starting' and 'running'. The 'running' includes 'starting' status, too.

Response

200 - Success

status

string

An overall status for recovery routine

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Validate the attempt to delete job associated with Metadata import asset

POST /v2/metadata_imports/validate_metadata_import_job

Validate the attempt to delete job associated with Metadata import asset

Request

Path Parameters

Query Parameters

job_id

Required *

string

Id of the metadata import job.

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

201 - Success

401 - Unauthorized

403 - Forbidden

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Validates a SAP Business Metadata connection

POST /v2/metadata_imports/validate_sap_connection

Validates a SAP Business Metadata connection.

Request

Path Parameters

Query Parameters

connection_id

Required *

string

The connection_id may be optionally provided to retrieve data discovery runs associated with the connection.

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Retrieve details of a Metadata Import

GET /v2/metadata_imports/{metadata_import_id}

Retrieve details of a metadata import

Request

Path Parameters

metadata_import_id

Required *

string

Id of the metadata import asset.

Query Parameters

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

metadata

object

Metadata about a metadata import asset. Set by system, not changeable by the user.

entity

object

Properties of the metadata import asset.

401 - Unauthorized

403 - Forbidden

404 - Not found

410 - Gone

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

delete a metadata import asset

DELETE /v2/metadata_imports/{metadata_import_id}

delete a metadata import asset

Request

Path Parameters

metadata_import_id

Required *

string

Id of the metadata import asset.

Query Parameters

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

204 - No content

401 - Unauthorized

403 - Forbidden

404 - Not found

410 - Gone

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

edit a metadata import asset

PATCH /v2/metadata_imports/{metadata_import_id}

string

paths

array

list of paths

include_list

array

include list in path

exclude_list

array

exclude list in path

unified_lineage

boolean

label to identify new architecture

Path Parameters

metadata_import_id

Required *

string

Id of the metadata import asset.

Query Parameters

project_id

Required *

string

The project_id must be provided. The project must exist and the caller must be an admin or editor member of the project.

Response

200 - Success

metadata

object

Metadata about a metadata import asset. Set by system, not changeable by the user.

entity

object

Properties of the metadata import asset.

401 - Unauthorized

403 - Forbidden

404 - Not found

410 - Gone

500 - Error

trace

string

A randomly-generated lowercase base-36 string uniquely identifying the request

errors

array

An array with at least one error

Field Match type Example dataset_id Equals ?dataset_id=5210c7d-cf6b ">

List data profiles

GET /v2/data_profiles

Status: Complete

Get the list of data profiles in the specified project or catalog for a given dataAsset, provided the caller has the necessary rights to do so. The returned results can be filtered by using one or more of the listed parameters.

Field	Match type	Example
dataset_id	Equals	?dataset_id=5210c7d-cf6b

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

dataset_id

Required *

string

The ID of the data set to use.

include_entity

boolean

Whether to include the entity component. If set to false, only the metadata component is populated in the response.

lite_mode

boolean

Include minimum payload for profiling results. If set to true, only minimum required details for DPS are available in the response.

column

string

Return the analysis results for specified column. This option will be ignored for data profile run using data flow.

Response

200 - Success.

resources

array

Collection of data profiles

401 - You are not permitted to perform this action.

403 - You are not authorized to list the available data profiles.

404 - Not Found.

500 - An error occurred. The data profiles cannot be listed.

trace

string

Trace information

errors

array

Errors occurred

AMQP 1.0 Messages

When a new data profile is created, a message is fired with a state of the new data profile in the body.

Topic

v2.data_profiles.:guid.POST ,where the ":guid" represents the profile_id of the created Data Profile

Subscribe to it by using "v2.data_profiles.*.POST" Binding Key.

Example Message

Topic: v2.data_profiles.5210c7d-cf6b-4204-95d2-95d84ecbe382.POST

Message:

{
 &quot;event&quot;: &quot;CREATE_DATA_PROFILE&quot;,
 &quot;actor&quot;: {          
   &quot;user_name&quot;: &quot;john@acme.com&quot;          
 },
 &quot;published&quot;: &quot;2015-05-10T15:04:15Z&quot;,
 &quot;url&quot;: { /* The href of the DataProfile created */}
 &quot;status_code&quot;: { /* The Http Status code , 201 if the DataProfile is created successfully */}
 &quot;state&quot;: { /* the data profile object equivalent to the one obtained by GET /v2/data_profiles/{profile_id} API */ }
 &quot;details&quot;: {
    &quot;catalog_id&quot;: &quot;f3c59258-abdd-4e24-828b-0495ec519339&quot;,
    &quot;dataset_id&quot;: &quot;e522db21-59e8-44ab-81b2-bb40c3030a6f&quot;,
    &quot;profile_id&quot;: &quot;5165d439-96f0-40d4-90b2-93795deab61b&quot;,
    &quot;is_governed&quot;: false { /* set to true if the catalog is_governed else set it to false}
   }
}

Create data profile

POST /v2/data_profiles

Status: Complete

Creates a data profile for a given data set in the specified project or catalog, provided the caller has the necessary rights to do so. Subsequent calls to use the data profile must specify the relevant project or catalog ID that the data profile was created in.

The request payload must include the 'metadata' section containing the data set id and catalog/project id.

The request payload can have the 'entity' section which is optional specifying the data profile options. If these options are not specified, default options are taken. To create several data profiles at once in the specified project or catalog, specify an array of data set in the attribute dataset_ids instead of a single data set in the attribute dataset_id. In this case, the data profiles are created in a single job that can be found in the execution section of the returned data profile entity.

AMQP 1.0 Messages

When a new data profile is created, a message is fired with a state of the new data profile in the body.

Topic

v2.data_profiles.:guid.POST ,where the ":guid" represents the profile_id of the created Data Profile

Subscribe to it by using "v2.data_profiles.*.POST" Binding Key.

Example Message

Topic: v2.data_profiles.5210c7d-cf6b-4204-95d2-95d84ecbe382.POST

Message:

{
 &quot;event&quot;: &quot;CREATE_DATA_PROFILE&quot;,
 &quot;actor&quot;: {          
   &quot;user_name&quot;: &quot;john@acme.com&quot;          
 },
 &quot;published&quot;: &quot;2015-05-10T15:04:15Z&quot;,
 &quot;url&quot;: { /* The href of the DataProfile created */}
 &quot;status_code&quot;: { /* The Http Status code , 201 if the DataProfile is created successfully */}
 &quot;state&quot;: { /* the data profile object equivalent to the one obtained by GET /v2/data_profiles/{profile_id} API */ }
 &quot;details&quot;: {
    &quot;catalog_id&quot;: &quot;f3c59258-abdd-4e24-828b-0495ec519339&quot;,
    &quot;dataset_id&quot;: &quot;e522db21-59e8-44ab-81b2-bb40c3030a6f&quot;,
    &quot;profile_id&quot;: &quot;5165d439-96f0-40d4-90b2-93795deab61b&quot;,
    &quot;is_governed&quot;: false { /* set to true if the catalog is_governed else set it to false}
   }
}

The ID of the dataset

dataset_ids

array

The IDs of the datasets to use during bulk processing

correlation_id

string

The ID to be used for tracking end to end flow.

url

string

The Location URL where DataProfile is created.

project_id

string

The ID of the project to use. Either catalog_id or project_id is required.

catalog_id

Required *

data_profile_outstanding

object

The data profile definition.

columns

array

attachment_id

string

href

string

The location url where the data profile is created.

Path Parameters

Query Parameters

start

boolean

Whether to start the profiling service immediately after the data profile is created.

use_mde

boolean

Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).

Charge term assignment

boolean

Whether to charge the bulk profiling to include term assignment charges.

Response

201 - Success.

202 - Accepted.

401 - You are not authorized to create a data profile.

403 - You are not permitted to perform this action.

The ID of the project to use. catalog_id or project_id is required.

dataset_id

Required *

string

The ID of the data set to use.

lite_mode

boolean

Include minimum payload for profiling results. If set to true, only minimum required details for DPS are available in the response.

Response

200 - Success.

metadata

DataProfilesDataProfileMetadataInfo

Profiling specific metadata

metadata_outstanding

DataProfilesDataProfileMetadataInfo

Profiling specific metadata

record_info

DataProfilesDataProfileRecordInfo

Information about the number of records

entity

object

The underlying asset entity.

href

string

The location url where the data profile is created.

401 - You are not authorized to get the data profile you specified.

403 - You are not permitted to perform this action.

404 - The data profile you specified cannot be found.

trace

string

Trace information

errors

array

Errors occurred

500 - An error occurred. The data profile you specified cannot be fetched.

trace

string

Trace information

errors

array

Errors occurred

Delete data profile

DELETE /v2/data_profiles/{profile_id}

Status: Complete

Deletes a specified data profile in a project or catalog, provided the caller has the necessary rights to do so.

The data profile is not deleted if the profiling process is still running unless the stop_in_progress_runs parameter is set to true.

Request

Path Parameters

profile_id

Required *

string

The profile ID to use.

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

dataset_id

Required *

string

The ID of the data set to use.

stop_in_progress_profiling_runs

boolean

Whether to stop all running profiling processes. Data profiles that are running must be stopped before they can be deleted.

use_mde

boolean

Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).

Response

204 - Success.

401 - You are not authorized to delete data profiles.

403 - You are not permitted to perform this action.

404 - Data profile not found.

415 - Data source not supported for profiling.

500 - An error occurred. The data profile cannot be deleted.

AMQP 1.0 Messages

When a data profile is modified, a message is fired with a state of the modified data profile in the body.

Topic

v2.data_profiles.:guid.PATCH

Subscribe to it by using "v2.data_profiles.*.PATCH" Binding Key.

Example Message

Topic: v2.data_profiles.5210c7d-cf6b-4204-95d2-95d84ecbe382.PATCH

Message:

{
 &quot;event&quot;: &quot;UPDATE_DATA_PROFILE&quot;,
 &quot;actor&quot;: {          
   &quot;user_name&quot;: &quot;john@acme.com&quot;,           
 },
 &quot;published&quot;: &quot;2015-05-10T15:04:15Z&quot;,
 &quot;url&quot;: { /* The href of the DataProfile created */}
 &quot;status_code&quot;: { /* The Http Status code , 200 if the DataProfile is updated successfully */}
 &quot;state&quot;: { /* the data profile object equivalent to the one obtained by GET /v2/data_profiles/{profile_id} API */ }
 &quot;details&quot;: {
    &quot;catalog_id&quot;: &quot;f3c59258-abdd-4e24-828b-0495ec519339&quot;,
    &quot;dataset_id&quot;: &quot;e522db21-59e8-44ab-81b2-bb40c3030a6f&quot;,
    &quot;profile_id&quot;: &quot;5165d439-96f0-40d4-90b2-93795deab61b&quot;,
    &quot;is_governed&quot;: false { /* set to true if the catalog is_governed else set it to false}
    }
}

Update data profile

PATCH /v2/data_profiles/{profile_id}

Status: Complete

Updates a data profile in the project or catalog specified in the data profile, provided the caller has the necessary rights to do so.

During update, the entire data profile is replaced, apart from any read-only or response-only attributes.

If the profiling processes is running and the start parameter is set to true, then a data profile is only updated if the stop_in_progress_runs parameter is set to true.

The updates must be specified by using the JSON patch format, described in RFC 6902.

AMQP 1.0 Messages

When a data profile is modified, a message is fired with a state of the modified data profile in the body.

Topic

v2.data_profiles.:guid.PATCH

Subscribe to it by using "v2.data_profiles.*.PATCH" Binding Key.

Example Message

Topic: v2.data_profiles.5210c7d-cf6b-4204-95d2-95d84ecbe382.PATCH

Message:

{
 &quot;event&quot;: &quot;UPDATE_DATA_PROFILE&quot;,
 &quot;actor&quot;: {          
   &quot;user_name&quot;: &quot;john@acme.com&quot;,           
 },
 &quot;published&quot;: &quot;2015-05-10T15:04:15Z&quot;,
 &quot;url&quot;: { /* The href of the DataProfile created */}
 &quot;status_code&quot;: { /* The Http Status code , 200 if the DataProfile is updated successfully */}
 &quot;state&quot;: { /* the data profile object equivalent to the one obtained by GET /v2/data_profiles/{profile_id} API */ }
 &quot;details&quot;: {
    &quot;catalog_id&quot;: &quot;f3c59258-abdd-4e24-828b-0495ec519339&quot;,
    &quot;dataset_id&quot;: &quot;e522db21-59e8-44ab-81b2-bb40c3030a6f&quot;,
    &quot;profile_id&quot;: &quot;5165d439-96f0-40d4-90b2-93795deab61b&quot;,
    &quot;is_governed&quot;: false { /* set to true if the catalog is_governed else set it to false}
    }
}

Request

Request Body

The updates to make in the data profile.

Path Parameters

profile_id

Required *

string

The profile ID to use.

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

dataset_id

Required *

string

The ID of the data set to use.

stop_in_progress_profiling_runs

boolean

Whether to stop all running profiling processes. Data profiles that are running must be stopped before they can be deleted.

use_mde

boolean

Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).

start

boolean

Whether to start the profiling service immediately after the data profile is updated.

Response

200 - Success.

401 - You are not authorized to update the data profile you specified.

403 - You are not permitted to perform this action.

404 - The data profile you specified cannot be found.

500 - An error occurred. The data profile you specified cannot be updated.

AMQP 1.0 Messages

When a data profile is modified, a message is fired with a state of the modified data profile in the body.

Topic

v2.data_profiles.:guid.PATCH

Subscribe to it by using "v2.data_profiles.*.PATCH" Binding Key.

Example Message

Topic: v2.data_profiles.5210c7d-cf6b-4204-95d2-95d84ecbe382.PATCH Message:

{
 &quot;event&quot;: &quot;UPDATE_DATA_PROFILE&quot;,
 &quot;actor&quot;: {          
   &quot;user_name&quot;: &quot;john@acme.com&quot;,           
 },
 &quot;published&quot;: &quot;2015-05-10T15:04:15Z&quot;,
 &quot;url&quot;: { /* The href of the DataProfile created */}
 &quot;status_code&quot;: { /* The Http Status code , 200 if the DataProfile is updated successfully */}
 &quot;state&quot;: { /* the data profile object equivalent to the one obtained by GET /v2/data_profiles/{profile_id} API */ }
 &quot;details&quot;: {
    &quot;catalog_id&quot;: &quot;f3c59258-abdd-4e24-828b-0495ec519339&quot;,
    &quot;dataset_id&quot;: &quot;e522db21-59e8-44ab-81b2-bb40c3030a6f&quot;,
    &quot;profile_id&quot;: &quot;5165d439-96f0-40d4-90b2-93795deab61b&quot;,
    &quot;is_governed&quot;: false { /* set to true if the catalog is_governed else set it to false}
    }
}

Update data profiles

POST /v2/data_profiles/bulk

Status: Complete

Updates data profiles in the project or catalog for one or more assets, provided the caller has the necessary rights to do so.

During update, the entire data profiles are replaced, apart from any read-only or response-only attributes.

If any profiling process is running and the start parameter is set to true, then a data profile is only updated if the stop_in_progress_runs parameter is set to true.

The updates must be specified by using the JSON patch format, described in RFC 6902.

AMQP 1.0 Messages

When a data profile is modified, a message is fired with a state of the modified data profile in the body.

Topic

v2.data_profiles.:guid.PATCH

Subscribe to it by using "v2.data_profiles.*.PATCH" Binding Key.

Example Message

Topic: v2.data_profiles.5210c7d-cf6b-4204-95d2-95d84ecbe382.PATCH Message:

{
 &quot;event&quot;: &quot;UPDATE_DATA_PROFILE&quot;,
 &quot;actor&quot;: {          
   &quot;user_name&quot;: &quot;john@acme.com&quot;,           
 },
 &quot;published&quot;: &quot;2015-05-10T15:04:15Z&quot;,
 &quot;url&quot;: { /* The href of the DataProfile created */}
 &quot;status_code&quot;: { /* The Http Status code , 200 if the DataProfile is updated successfully */}
 &quot;state&quot;: { /* the data profile object equivalent to the one obtained by GET /v2/data_profiles/{profile_id} API */ }
 &quot;details&quot;: {
    &quot;catalog_id&quot;: &quot;f3c59258-abdd-4e24-828b-0495ec519339&quot;,
    &quot;dataset_id&quot;: &quot;e522db21-59e8-44ab-81b2-bb40c3030a6f&quot;,
    &quot;profile_id&quot;: &quot;5165d439-96f0-40d4-90b2-93795deab61b&quot;,
    &quot;is_governed&quot;: false { /* set to true if the catalog is_governed else set it to false}
    }
}

Request

Request Body

The updates to make in the one or more data profiles.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

Response

200 - Success.

401 - You are not authorized to update the data profile you specified.

403 - You are not permitted to perform this action.

404 - The catalog / project you specified cannot be found.

500 - An error occurred. The catalog / project you specified cannot be updated.

Stop profiling process

PUT /v2/data_profiles/{profile_id}/execution

Status: Complete

Stops an in-progress profiling run in the specified project or catalog, provided the caller has the necessary rights to do so. This API will request the action to be performed and return, not perform the action and wait for it to complete.

Request

Request Body

DataProfilesDataProfileRunStatusRequest

The requested action to perform on the profile run.

action

string

The requested action (Response only).

Path Parameters

profile_id

Required *

string

The profile ID to use.

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

dataset_id

Required *

string

The ID of the data set to use.

use_mde

boolean

Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).

Response

202 - Requested.

401 - You are not authorized to stop the profiling process.

403 - You are not permitted to perform this action.

The ID of the project to use. catalog_id or project_id is required.

dataset_id

Required *

string

The ID of the data set to use.

Response

200 - Success.

logs

array

A collection of data profile job run log entries.

401 - You are not authorized to get the profiling logs.

403 - You are not permitted to perform this action.

404 - The data profile you specified cannot be found.

trace

string

Trace information

errors

array

Errors occurred

500 - An error occurred. Failed to get profiling logs.

trace

string

Trace information

errors

array

Errors occurred

Get the list of data quality dimensions available.

GET /v2/data_profiles/dqdimensions

Status: Complete

Get the list of data quality dimensions available.

Request

Response

200 - Success.

dimensions

array

A collection of data quality dimensions.

403 - You are not permitted to perform this action.

500 - An error occurred. Failed to get quality dimensions.

trace

string

Trace information

errors

array

Errors occurred

Modify asset level classification

PATCH /v2/data_profiles/classification

Status: Complete

Modifies asset level classification detail in the data_profile attribute in the specified project or catalog, provided the caller has the necessary rights to do so. This API is used for CRUD operations on asset level classification.

The patch request for classification should contain the classification details that are to be added to the data_profile attribute.

The updates must be specified by using the JSON patch format, described in RFC 6902.

Request

Request Body

The asset level classification details that are added to the data_profile attribute.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

dataset_id

Required *

string

The ID of the data set to use.

use_mde

boolean

Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).

Response

200 - Success.

400 - Invalid classification details provided as part of the patch call.

401 - You are not authorized to modify the data_profile attribute with asset level classification details.

403 - You are not permitted to perform this action.

404 - The asset classification cannot be found.

500 - An error occurred. The data_profile attribute cannot be modified with asset level classification detail.

Get data profile options

GET /v2/data_profiles/options

Status: Complete

Get the data profile options for the Account specified in the IAM token. If the account level data profile options is not available check if it is specified at project or catalog account level, provided the caller has the necessary rights to do so.

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

use_mde

boolean

Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).

Response

200 - Success.

metadata

DataProfilesDataProfileOptionsMetadata

Metadata about data profile options

entity

object

The underlying asset entity.

401 - You are not permitted to perform this action.

403 - You are not authorized to list the available data profiles options.

404 - Not Found.

500 - An error occurred. The data profiles options cannot be listed.

trace

string

Trace information

errors

array

Errors occurred

501 - This API is not Implemented.

Create data profile options

POST /v2/data_profiles/options

data_profile_options

Required *

object

The options of the profiling execution.

Path Parameters

Query Parameters

use_mde

boolean

Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).

Response

201 - Success.

401 - You are not authorized to create data profile options.

403 - You are not permitted to perform this action.

404 - The data profile options cannot be found.

500 - An error occurred. The data profile options cannot be created.

501 - This API is not Implemented.

Delete data profile options

DELETE /v2/data_profiles/options

Status: Complete

Delete the list of data profile options in the specified project or catalog, provided the caller has the necessary rights to do so. If the user specifies the catalog_id or the project_id then the data profile options specified for the catalog or project is deleted. If none of the query parameters,catalog_id or project_id is specified, the default is to delete the account level data profile options.

Request

Path Parameters

Query Parameters

bss_account_ids

string

Comma separated list of the BSS Account IDs to use (restriced usage).

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

use_mde

boolean

Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).

Response

204 - Success.

401 - You are not permitted to perform this action.

403 - You are not authorized to list the available data profiles options.

404 - Not Found.

500 - An error occurred. The data profiles options cannot be listed.

501 - This API is not Implemented.

Update the data profile options.

PATCH /v2/data_profiles/options

Status: Complete

Updates the data profile options for a given Account in the specified project or catalog, provided the caller has the necessary rights to do so. The data profile options that can be modified are max_row_count,row_percentage,max_distribution_size,max_numeric_stats_bin disabled flag in classification options,ibm_class_codes and custom_class_codes.

If the user specifies the catalog_id or the project_id then the data profile options specified for the catalog or project is updated. Update the account level data profile options if catalog_id or project_id is not specified.

Request

Request Body

The data profile options to add.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

use_mde

boolean

Whether to use Metadata enrichment for profiling. If set to true, Metadata enrichment features are eanbled (will use new Lite services).

Response

200 - Success.

401 - You are not authorized to update the data profile options.

403 - You are not permitted to perform this action.

404 - The data profile options you specified cannot be found.

500 - An error occurred. The data profile options cannot be updated.

501 - This API is not Implemented.

Persist profiling results

POST /v2/data_profiles/results

Status: Complete

Persist profiling results of dataset in a project or catalog. (For internal use only)

Request

Request Body

DataProfilesProfilingResults

The data profile option to create.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

dataset_id

Required *

string

The ID of the data set to use.

tenant_id

Required *

string

The tenant ID to use.

correlation_id

string

The ID to be used for tracking end to end flow.

Response

200 - Success.

401 - You are not authorized to persist results.

403 - You are not permitted to perform this action.

404 - Asset or profile is missing

500 - An error occurred. The profiling results cannot be saved.

501 - This API is not Implemented.

Update data profile results status

POST /v2/data_profiles/results/status

Status: Complete

Update data profile result status of dataset in a project or catalog. (For internal use only)

Request

Request Body

DataProfilesDataProfileResultStatus

The data profile result status to update.

status

Required *

string

The data profile status.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

string

The ID to be used for tracking end to end flow.

Response

200 - Success.

401 - You are not authorized to update data profile result status.

403 - You are not permitted to perform this action.

404 - Asset or profile is missing

500 - An error occurred. The data profile result status cannot be saved.

501 - This API is not Implemented.

Get bivariate results of given asset.

GET /v2/data_profiles/bivariate_results

Status: Complete

Get bivariate results of dataset in a project or catalog. (For internal use only)

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

dataset_id

Required *

string

The ID of the data set to use.

Response

200 - Success.

401 - You are not authorized to persist results.

403 - You are not permitted to perform this action.

404 - Asset is missing

500 - An error occurred. The bivariate results cannot be retrieved.

501 - This API is not Implemented.

Persist bivariate results of given asset.

POST /v2/data_profiles/bivariate_results

Status: Complete

Persist bivariate results of dataset in a project or catalog. (For internal use only)

Request

Request Body

DataProfilesBivariateResults

The bivariate results to persist.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

dataset_id

Required *

string

The ID of the data set to use.

Response

200 - Success.

401 - You are not authorized to persist results.

403 - You are not permitted to perform this action.

404 - Asset is missing

500 - An error occurred. The bivariate results cannot be saved.

501 - This API is not Implemented.

Export data profile

GET /v2/data_profiles/export

Status: Complete

Export data profile of dataset in a project or catalog. (For internal use only)

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

200 - Success.

file_paths

array

List of file paths that hold the profiling results. These files should be added to the project export archive.

401 - You are not authorized to persist results.

403 - You are not permitted to perform this action.

404 - Asset or profile is missing

500 - An error occurred. The profiling results cannot be saved.

501 - This API is not Implemented.

Import data profile

POST /v2/data_profiles/import

Status: Complete

Import data profile of dataset in a project or catalog. (For internal use only)

Request

Request Body

DataProfilesDataProfileImport

The data profile to import.

source_path

string

Source path where the import archive is deflated. If this value is provided, the profiling results are read from source_path/assets/profiling directory by setting the root=true. If this value is not provided, results files are read from profiling directory by setting the root=false.

asset_ref_map

DataProfilesDataProfileImportAssetRefMap

Map of the old asset ids to new asset ids

owner_id

string

IBM cloud IAM user id of the creator of the asset.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

dataset_id

Required *

string

The ID of the data set to use.

Response

200 - Success.

401 - You are not authorized to persist results.

403 - You are not permitted to perform this action.

404 - Asset or profile is missing

500 - An error occurred. The profiling results cannot be saved.

501 - This API is not Implemented.

This filters rows from the frequency distribution.

POST /v2/data_profiles/{profile_id}/unique_values

This filters rows from the frequency distribution.

Request

Request Body

DataProfilesFrequencyDistributionRequestBody

project_id

string

catalog_id

string

dataset_id

Required *

string

column_name

Path Parameters

profile_id

Required *

string

The profile ID to use.

Query Parameters

Response

200 - Success.

total_count

integer

array

Errors occurred

Migrate data profile quality results to new Data Quality service

POST /v2/data_profiles/migrate

Status: Complete

Migrate data profile quality results of dataset in a project or catalog to new Data Quality service.

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. catalog_id or project_id is required.

project_id

string

The ID of the project to use. catalog_id or project_id is required.

dataset_id

string

The ID of the data set to use.(Use comma separated data set Id's for multiple data sets)

Response

200 - Successfully initiated migration process.

logs

array

400 - Bad request. Provided parameters could be invalid.

401 - You are not authorized, either token is expired or invalid.

403 - You are not permitted to perform this action. Only Editor or Admin are allowed.

404 - Catalog or Project not found.

500 - An error occurred. The profiling results cannot be migrated to data quality service.

501 - This API is not Implemented.

List Hummingbird tasks

GET /v1/hb_tasks

Status: Complete

Get the list of Hummingbird tasks for a specified accout or type, provided the caller has the necessary rights to do so.

Request

Path Parameters

Query Parameters

bss_account_id

string

The BSS Account ID to use.

job_type

string

The type of the job.

all_details

boolean

Fetch complete details of job.

Response

200 - Success.

401 - You are not permitted to perform this action.

403 - You are not authorized to list the available Hummingbird tasks.

404 - Not Found.

500 - An error occurred. The HB tasks cannot be listed.

trace

string

errors

array

Create a Hummingbird task

Required *

string

Type of of the component

tool_name

Required *

string

Tool name of the component

service_offering

Required *

string

Service offering name e.g. watson_knowledge_catalog

instance

Required *

string

The id of the instance the CUH needs to be charged to. e.g. an id of the wkc instance

capacity_units

integer

Capacity units multiplication factor

minimum_usage

integer

Minimum usage in milliseconds to be charged for this job

hardware_specification

object

If capacity_units is not provided then this can be used to alter the multiplication factor by the runtimes api.

compute_units

DataProfilesComputeUnits

A ComputeUnits holds details to determine if a particular account has surpassed its CUH.

stop_on_max_compute_units

Required *

boolean

Stop job submission if an account has surpassed its allocated CUH

notify_on_max_compute_units

Required *

boolean

Send a notification if an account has surpassed its allocated CUH

max_compute_units_per_month

Required *

number

Maximum allocated CUH per month for current account plan

Response

200 - Success.

401 - You are not authorized to create a Hummingbird task.

403 - You are not permitted to perform this action.

404 - The data profile cannot be found.

500 - An error occurred. The Hummingbird task cannot be created.

Stop Hummingbird tasks

POST /v1/hb_tasks/stop

Status: Complete

Stops given Hummingbird task ids. If the Hummingbird task is already completed or is not found then it will be ignored. If the task is locked by other process then it will be ignored as well.

Request

Request Body

DataProfilesHbTaskIds

The Hummingbird task ids to stop.

hb_task_ids

Required *

array

The array of hb_task_id to use during bulk processing

Response

200 - Success.

401 - You are not authorized to cancel Hummingbird tasks.

403 - You are not permitted to perform this action.

500 - An error occurred. The Hummingbird tasks cannot be stopped.

Delete Hummingbird tasks

POST /v1/hb_tasks/delete

Status: Complete

Delete given Hummingbird task ids. If a Hummingbird task is not found then it will be ignored. If the Hummingbird task is running and stop_in_progress_job is not true then it will be ignored. If the task is locked by other process then it will be ignored as well.

Request

Request Body

DataProfilesHbTaskIds

The Hummingbird task ids to delete.

hb_task_ids

Required *

array

The array of hb_task_id to use during bulk processing

Path Parameters

Query Parameters

stop_in_progress_job

boolean

Stop running job.

Response

200 - Success.

401 - You are not authorized to cancel a Hummingbird task.

403 - You are not permitted to perform this action.

500 - An error occurred. The Hummingbird tasks cannot be deleted.

Get HB task

GET /v1/hb_tasks/{hb_task_id}

Status: Complete

Gets a Hummingbird task.

Request

Path Parameters

hb_task_id

Required *

string

The ID of the HB task to use.

Query Parameters

Response

A RuntimeRegistrationParameters holds details to be sent to runtimes api to report CUH for HB job.

compute_units

DataProfilesComputeUnits

A ComputeUnits holds details to determine if a particular account has surpassed its CUH.

401 - You are not authorized to get the data profile you specified.

403 - You are not permitted to perform this action.

404 - The HB task you specified cannot be found.

trace

string

errors

array

500 - An error occurred. The HB task you specified cannot be fetched.

trace

string

errors

array

Delete Hummingbird task

DELETE /v1/hb_tasks/{hb_task_id}

Status: Complete

Deletes a specified Hummingbird task.

This api will throw an exception if stop_in_progress_job parameter is not true and if job is running.

Request

Path Parameters

hb_task_id

Required *

string

The ID of the HB task to use.

Query Parameters

stop_in_progress_job

boolean

Stop running job.

Response

204 - Success.

401 - You are not authorized to delete Hummingbird task.

403 - You are not permitted to perform this action.

404 - Hummingbird task not found.

500 - An error occurred. The Hummingbird task cannot be deleted.

Start Hummingbird task

POST /v1/hb_tasks/{hb_task_id}/start

Status: Complete

Start the specified Hummingbird task, if it is in QUEUED state.

The Hummingbird task is starte in engine, if it is in queued state

Request

Path Parameters

hb_task_id

Required *

string

The ID of the HB task to use.

Query Parameters

Response

204 - Success.

400 - The Hummingbird task is not QUEUED.

401 - You are not authorized to start Hummingbird task.

403 - You are not permitted to perform this action.

404 - Hummingbird task not found.

500 - An error occurred. The failed to start Hummingbird task.

Stop Hummingbird task

POST /v1/hb_tasks/{hb_task_id}/stop

Status: Complete

Stop the specified Hummingbird task.

The Hummingbird task is force stopped in engine

Request

Path Parameters

hb_task_id

Required *

string

The ID of the HB task to use.

Query Parameters

Response

204 - Success.

401 - You are not authorized to delete Hummingbird task.

403 - You are not permitted to perform this action.

404 - Hummingbird task not found.

500 - An error occurred. The failed to stop Hummingbird task.

Get Hummingbird task logs

GET /v1/hb_tasks/{hb_task_id}/logs

Status: Complete

Get the spark job logs for Hummingbird task. In order to retrieve the job logs, the HB spark job must be successfully submitted. This will generate a job_id. When successful, this api would return the Hummingbird spark job log.

Request

Path Parameters

hb_task_id

Required *

string

The ID of the HB task to use.

Query Parameters

Response

200 - Success.

401 - You are not authorized to get Hummingbird task logs.

403 - You are not permitted to perform this action.

404 - Hummingbird task not found.

500 - An error occurred. Failed to retrieve Hummingbird task logs.

Get service information

GET /v1/hb_tasks/version

Status: Complete

Returns the service version.

Request

Response

The service version string

500 - An error occurred. No information about the service can be returned.

trace

string

errors

array

List all data quality rules or a subset of them

GET /data_quality/v3/projects/{project_id}/rules

Get a list of data quality rules in the project.

Request

Path Parameters

Query Parameters

start

The start token of the resource from where the page should begin.

limit

The maximum number of resources to return.

id

Comma-separated list of data quality rule identifiers.

Response

200 - Success.

limit

integer

The maximum number of resources to return.

total_count

integer

Total number of resources available.

first

DataQualityPageLink

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

rules

errors

array

Create data quality rule

POST /data_quality/v3/projects/{project_id}/rules

Create a data quality rule.

Request

Request Body

DataQualityRulePrototype

Data quality rule to create.

name

object

The output database details when the output needs to be saved in a database table. This field can be omitted if value for `links` is provided.

maximum_record_count

integer

Maximum number of records to be written to the output. The value `-1` indicates that all records should be written to the output.

columns

data_stage

DataQualityRuleDataStagePrototype

Representation of the data stage flow resource to create. If this property is omitted, no subflow is created for the data quality rule.

flow

Required *

object

Data stage flow to create.

propagate_all_incoming_columns

boolean

If selected, columns from the incoming link are propagated to the output in addition to the selected output.

read_only

boolean

If true, the referenced DataStage flow already exists and should not be created, updated or deleted.

Response

201 - Success.

name

string

The name of the data quality rule. The name of the quality rule will be unique in a given project.

description

string

The description of the data quality rule. If this property is omitted, no description is set.

dimension

DataQualityDimensionReference1

Identity of a data quality dimension resource.

apply_all_present_dimensions

boolean

input

DataQualityRuleInput

Data quality rule input details.

output

DataQualityRuleOutput

The output details of a data quality rule.

joins

array

The joins between data assets referenced in bindings and output. This property is not required if the rule is to be run on a single data asset. This property is also not required if a `data_stage` element is provided.

sampling

DataQualityRuleSampling

The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.

data_stage

DataQualityRuleDataStage

Data stage flow details.

id

string

Resource identifier.

is_valid

boolean

Flag indicating whether the rule is valid or not.

href

errors

array

Delete data quality rules

DELETE /data_quality/v3/projects/{project_id}/rules

Delete the data quality rules for the given list of rule identifiers.

Request

Path Parameters

Query Parameters

id

Required *

Comma-separated list of data quality rule identifiers.

delete_output

boolean

The option to delete related output tables when deleting data quality rules.

cancel_unfinished_jobs

boolean

The option to cancel unfinished jobs before deleting or updating data quality rules.

Response

204 - Success.

apply_all_present_dimensions

boolean

input

Required *

DataQualityRuleInputPrototype

Data quality rule input details.

sql

object

Data quality rule input sql details. This property can be omitted if `definitions` values is provided.

definitions

array

Provides data quality rule input definition details. This property can be omitted if `sql` value is provided.

output

DataQualityRuleOutputPrototype

The output details of a data quality rule. If this property is omitted, no output records are saved.

database

object

The output database details when the output needs to be saved in a database table. This field can be omitted if value for `links` is provided.

maximum_record_count

integer

Maximum number of records to be written to the output. The value `-1` indicates that all records should be written to the output.

columns

Required *

array

A list of columns in the rule output.

links

array

joins

array

sampling

DataQualityRuleSamplingPrototype

The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.

sampling_type

string

The sampling method to use.

size

integer

The maximum size of the sample. This is the maximum number of source records that are tested against the rule logic.

interval

integer

The sampling interval for the sampling type `sequential`.

seed

integer

The sampling seed for the sampling type `random`. If no value for this property is provided, a value is generated from the current timestamp.

fraction

number

The sampling fraction for the sampling type `random`.

data_stage

DataQualityRuleDataStagePrototype

Representation of the data stage flow resource to create. If this property is omitted, no subflow is created for the data quality rule.

flow

Required *

object

Data stage flow to create.

propagate_all_incoming_columns

boolean

If selected, columns from the incoming link are propagated to the output in addition to the selected output.

read_only

boolean

If true, the referenced DataStage flow already exists and should not be created, updated or deleted.

Path Parameters

project_id

Required *

The identifier of the project to use.

Query Parameters

Response

200 - The data quality rule is valid.

name

string

The name of the data quality rule. The name of the quality rule will be unique in a given project.

description

string

The description of the data quality rule. If this property is omitted, no description is set.

dimension

DataQualityDimensionReference1

Identity of a data quality dimension resource.

apply_all_present_dimensions

boolean

input

DataQualityRuleInput

Data quality rule input details.

output

DataQualityRuleOutput

The output details of a data quality rule.

joins

array

sampling

DataQualityRuleSampling

The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.

data_stage

DataQualityRuleDataStage

Data stage flow details.

id

string

Resource identifier.

is_valid

boolean

Flag indicating whether the rule is valid or not.

href

errors

array

Get data quality rule

GET /data_quality/v3/projects/{project_id}/rules/{id}

Gets the data quality rule with the given identifier.

Request

Response

200 - Success.

name

string

The name of the data quality rule. The name of the quality rule will be unique in a given project.

description

string

The description of the data quality rule. If this property is omitted, no description is set.

dimension

DataQualityDimensionReference1

Identity of a data quality dimension resource.

apply_all_present_dimensions

boolean

input

DataQualityRuleInput

Data quality rule input details.

output

DataQualityRuleOutput

The output details of a data quality rule.

joins

array

sampling

DataQualityRuleSampling

The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.

data_stage

DataQualityRuleDataStage

Data stage flow details.

id

string

Resource identifier.

is_valid

boolean

Flag indicating whether the rule is valid or not.

href

string

Path Parameters

Query Parameters

delete_output

boolean

The option to delete related output tables when deleting data quality rules.

cancel_unfinished_jobs

boolean

The option to cancel unfinished jobs before deleting or updating data quality rules.

Response

204 - Success.

Update data quality rule

PATCH /data_quality/v3/projects/{project_id}/rules/{id}

Updates a data quality rule as specified in the payload details of the update rule request. The updates must be specified by using the JSON patch format, described in RFC 6902. <p> The following attributes can be patched: - name (value can only be replaced) - definition (value can only be replaced) - description (value can be added, removed, or replaced) - dimension (value can be added, removed, or replaced) - input (value can be added, removed or replaced) - output (value can be added, removed, or replaced) - joins (value can be added, removed, or replaced) - sampling (value can be added, removed, or replaced) - data_stage/propagate_all_incoming_columns (value can be added, removed, or replaced)

Request

Request Body

The updates to make in the data quality rule.

Path Parameters

Query Parameters

cancel_unfinished_jobs

boolean

The option to cancel unfinished jobs before deleting or updating data quality rules.

keep_rule_relationships

boolean

The option to keep the current data quality rule input binding relationships while updating the data quality rule.

Response

200 - Success.

name

string

The name of the data quality rule. The name of the quality rule will be unique in a given project.

description

string

The description of the data quality rule. If this property is omitted, no description is set.

dimension

DataQualityDimensionReference1

Identity of a data quality dimension resource.

apply_all_present_dimensions

boolean

input

DataQualityRuleInput

Data quality rule input details.

output

DataQualityRuleOutput

The output details of a data quality rule.

joins

array

sampling

DataQualityRuleSampling

The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.

data_stage

DataQualityRuleDataStage

Data stage flow details.

id

string

Resource identifier.

is_valid

boolean

Flag indicating whether the rule is valid or not.

href

string

Response

The location URL of a resource.

definition_counts

errors

array

List history of all data quality rule run results or a subset of them

GET /data_quality/v3/projects/{project_id}/rules/{rule_id}/executions

Gets the list of data quality rule runs. By default, the runs are sorted newest to oldest.

Request

Path Parameters

Query Parameters

start

The start token of the resource from where the page should begin.

limit

The maximum number of resources to return.

sort

string

The property name by which the results should be sorted. For descending order, use the hyphen (-) prefix with the value. If you omit this query parameter, the order value is `-started_at`, which means, results are sorted by the `started_at` value in descending order. The allowed fields are `started_at`, `passing_record_count`, `failing_record_count`, `tested_record_count`, `status.state`.

Response

200 - Success.

limit

integer

The maximum number of resources to return.

total_count

integer

Total number of resources available.

first

DataQualityPageLink

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

executions

errors

array

Get the data quality rule run

GET /data_quality/v3/projects/{project_id}/rules/{rule_id}/executions/{id}

Gets the data quality rule run result with the given identifier.

Request

Path Parameters

rule_id

Required *

The data quality rule identifier.

id

Required *

The run identifier to use.

project_id

Required *

The identifier of the project to use.

Query Parameters

Response

The location URL of a resource.

definition_counts

errors

array

List all data quality definitions or a subset of them

GET /data_quality/v3/projects/{project_id}/definitions

Gets the list of all data quality definitions.

Request

Path Parameters

Query Parameters

start

The start token of the resource from where the page should begin.

limit

The maximum number of resources to return.

id

Comma-separated list of data quality definition identifiers.

Response

200 - Success.

limit

integer

The maximum number of resources to return.

total_count

integer

Total number of resources available.

first

DataQualityPageLink

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

definitions

errors

Identity of a data quality dimension resource. If this property is omitted, no data quality dimension is associated with the resource.

id

Required *

string

Resource identifier.

Response

errors

array

Delete data quality definitions

DELETE /data_quality/v3/projects/{project_id}/definitions

Delete the data quality definitions with the given identifiers.

Request

Path Parameters

Query Parameters

id

Required *

Comma separated list of data quality definition identifiers.

Response

204 - Success.

id

Required *

string

Resource identifier.

Path Parameters

project_id

Required *

The identifier of the project to use.

Query Parameters

partial_expression

boolean

True if the expression to validate is an output column expression. False if the expression to validate is a data quality definition expression. Default value is false.

Response

200 - Success.

variables

string

Response

errors

array

Delete data quality definition

DELETE /data_quality/v3/projects/{project_id}/definitions/{id}

Delete the data quality definition with the given identifier.

Request

Response

204 - Success.

Update data quality definition

PATCH /data_quality/v3/projects/{project_id}/definitions/{id}

Updates a data quality definition as specified in the payload details of the update definition request. The updates must be specified by using the JSON patch format, described in RFC 6902. <p> The following attributes can be patched. - name (value can only be replaced) - description (value can be added, removed, or replaced) - expression (value can only be replaced) - dimension (value can be added, removed, or replaced)

Request

Request Body

The updates to make in the data quality definition.

Response

Path Parameters

project_id

Required *

The identifier of the project to use.

Query Parameters

start

The start token of the resource from where the page should begin.

limit

The maximum number of resources to return.

Response

200 - Success.

limit

integer

The maximum number of resources to return.

total_count

integer

Total number of resources available.

first

DataQualityPageLink

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

dimensions

array

An array of data quality dimensions.

401 - Your authorization to access this method is missing, invalid, or expired.

string

errors

array

Replace project settings for data quality rules

PUT /data_quality/v3/projects/{project_id}/settings

Replace project settings for data quality rules.

Request

Request Body

DataQualitySettingsPrototype

Project settings for data quality rules.

errors

array

Get data quality rule from catalog

GET /data_quality/v3/catalogs/{catalog_id}/rules/{id}

Gets the data quality rule from catalog with the given identifier.

Request

Response

200 - Success.

name

string

The name of the data quality rule. The name of the quality rule will be unique in a given project.

description

string

The description of the data quality rule. If this property is omitted, no description is set.

dimension

DataQualityDimensionReference1

Identity of a data quality dimension resource.

apply_all_present_dimensions

boolean

input

DataQualityRuleInput

Data quality rule input details.

output

DataQualityRuleOutput

The output details of a data quality rule.

joins

array

sampling

DataQualityRuleSampling

The sampling options to be used during data quality rule run. If no sampling options are set, the rule is run against all the rows of the source.

data_stage

DataQualityRuleDataStage

Data stage flow details.

id

string

Resource identifier.

is_valid

boolean

Flag indicating whether the rule is valid or not.

href

string

Response

The location URL of a resource.

401 - Your authorization to access this method is missing, invalid, or expired.

trace

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.assets.read

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

start

The start token of the resource from where the page should begin. If omitted, begins with first resource.

limit

The maximum number of resources to return.

include_children

boolean

If true include the children in the returned resource. If false, only return the resource without its eventual children.

type

The type of the resource to search. If omitted, filtering on type is not applied

Response

200 - Success.

limit

integer

The maximum number of resources to return.

total_count

integer

Total number of resources available.

first

DataQualityPageLink

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

assets

errors

array

Create Data quality assets

POST /data_quality/v4/assets

Create a data quality asset.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.assets.create

Request

Request Body

DataQualityAssetPrototype

Data quality asset to create.

name

Required *

object

Name of a data quality resource.(Name need not be unique)

parent

object

The Id of an eventual parent, or null if this asset has no parent

native_id

Required *

link

string

Link to corresponding data quality component. No default link is available, it is empty if not provided.

weight

Required *

number

The weight of this asset in the computation of the data quality scores

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

Response

The weight of this asset in the computation of the data quality scores

children

errors

array

Get a data quality asset

GET /data_quality/v4/assets/{id}

Get the data quality asset with the given identifier.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.assets.read

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

include_children

boolean

If true include the children in the returned resource. If false, only return the resource without its eventual children.

Response

The weight of this asset in the computation of the data quality scores

children

array

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.assets.delete

Auditing

Calling this method generates the following auditing event.

wdp-data_quality.issue.delete

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

delete_children

boolean

If true, delete all children recursively. Otherwise, only selected one is deleted.

Response

204 - Success.

Update or patch a data quality asset

PATCH /data_quality/v4/assets/{id}

Update a data quality asset as specified in the payload details of the request.

The updates must be specified by using the JSON patch format, described in RFC 6902. <p> The following attributes can be updated: - /name (value can only be replaced) - /weight (value can only be replaced)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.assets.update

Request

Request Body

The updates to make in the data quality rule.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

Response

The weight of this asset in the computation of the data quality scores

children

array

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.assets.read

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

native_id

The native id, as known by the DQ producer, of the resource to search. If not provided, other identity parameters must be provided.

type

The type of the resource to search. If omitted, filtering on type is not applied

wkc_asset_id

The IBM Knowledge Catalog asset ID in cams. If omitted, the field is not set.

include_children

boolean

If true include the children in the returned resource. If false, only return the resource without its eventual children.

Response

The weight of this asset in the computation of the data quality scores

children

array

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.checks.read

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

start

The start token of the resource from where the page should begin. If omitted, begins with first resource.

limit

The maximum number of resources to return.

include_children

boolean

If true include the children in the returned resource. If false, only return the resource without its eventual children.

type

The type of the resource to search. If omitted, filtering on type is not applied

Response

200 - Success.

limit

integer

The maximum number of resources to return.

total_count

integer

Total number of resources available.

first

DataQualityPageLink

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

checks

errors

array

Create data quality checks

POST /data_quality/v4/checks

Create a data quality check.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.checks.create

Request

Request Body

DataQualityCheckPrototype

Data quality check to create.

dimension

Required *

object

the dimension this check belongs to

id

Required *

string

Resource identifier.

name

Required *

object

Name of a data quality resource.(Name need not be unique)

native_id

Required *

object

Unique identifier set by the creator of the resource

parent

object

The Id of an eventual parent, or null if this check has no parent

type

Required *

object

The type of the data quality resource

link

string

Link to corresponding data quality component. No default link is available, it is empty if not provided.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

Response

The optional eventual children of this data quality check.

issues

errors

array

Get a data quality check

GET /data_quality/v4/checks/{id}

Get the data quality check with the given identifier.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.checks.read

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

include_children

boolean

If true include the children in the returned resource. If false, only return the resource without its eventual children.

Response

The optional eventual children of this data quality check.

issues

array

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.checks.delete

Auditing

Calling this method generates the following auditing event.

wdp-data_quality.issue.delete

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

delete_children

boolean

If true, delete all children recursively. Otherwise, only selected one is deleted.

Response

204 - Success.

Update or patch a data quality check

PATCH /data_quality/v4/checks/{id}

Update a data quality check as specified in the payload details of the request.

The updates must be specified by using the JSON patch format, described in RFC 6902. <p> The following attributes can be updated: - /name (value can only be replace) - /dimension/id (value can be add, remove or replace) - /details (value can be add, remove or replace)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.checks.update

Request

Request Body

The updates to make in the data quality rule.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

Response

The optional eventual children of this data quality check.

issues

array

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.checks.read

Request

Path Parameters

Query Parameters

native_id

Required *

The native id, as known by the DQ producer, of the resource to search.

type

Required *

The type of the resource to search.

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

include_children

boolean

If true include the children in the returned resource. If false, only return the resource without its eventual children.

Response

The optional eventual children of this data quality check.

issues

array

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.dimensions.read

Request

Path Parameters

Query Parameters

start

The start token of the resource from where the page should begin. If omitted, begins with first resource.

limit

The maximum number of resources to return.

Response

200 - Success.

limit

integer

The maximum number of resources to return.

total_count

integer

Total number of resources available.

first

DataQualityPageLink

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

dimensions

errors

array

Create a data quality dimension

POST /data_quality/v4/dimensions

Create a data quality dimension.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.dimensions.create

Request

Request Body

DataQualityDimensionPrototype

Data quality dimension to create.

name

Required *

object

Name of a data quality resource.(Name need not be unique)

description

string

The optional description of the dimension. Provide a description to understand the reason for its existence.

Response

201 - Success

is_default

errors

array

Get the data quality dimension with the given identifier

GET /data_quality/v4/dimensions/{id}

Get the data quality dimension with the given identifier.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.dimensions.read

Request

Response

200 - Success.

is_default

boolean

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.dimensions.delete

Request

Response

204 - Success.

Update a data quality dimension as specified in the payload details of the request

PATCH /data_quality/v4/dimensions/{id}

Update a data quality dimension as specified in the payload details of the request.

The updates must be specified by using the JSON patch format, described in RFC 6902. <p> The following attributes can be updated: - /name (value can only be replaced) - /description (value can be added, removed, or replaced)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.dimensions.update

Request

Request Body

The updates to make in the data quality rule.

Response

200 - Success.

is_default

boolean

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.dimensions.read

Request

Path Parameters

Query Parameters

name

Required *

The name of the resource to search or a part of the name of the resources to search.

Response

200 - Success.

limit

integer

The maximum number of resources to return.

total_count

integer

Total number of resources available.

first

DataQualityPageLink

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

dimensions

errors

array

Get a list of data quality issues

GET /data_quality/v4/issues

Get a list of data quality issues.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.issues.read

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

start

The start token of the resource from where the page should begin. If omitted, begins with first resource.

limit

The maximum number of resources to return.

reported_for.id

Comma-separated list of data quality asset identifier to search issues of. If not provided, filtering on asset is not applied.

check.id

Comma-separated list of data quality check id identifier to search issues of. If not provided, filtering on a check is not applied.

check.native_id

Comma-separated list of data quality check native id identifier to search issues of. If not provided, filtering on a check is not applied. Only one of checkId or checkNativeId should be provided; if both are provided, an error will be thrown.

check.name

The name or part of the name of data quality check identifier to search issues of. If not provided, filtering on name of check is not applied.

check.dimension.id

Comma-separated list of data quality dimension identifiers.

latest_only

boolean

If true, returns only the latest issue summary of each DQ check. If false, returns the latest and archived issues.

type

The type of the resource to search. If omitted, filtering on type is not applied

include_children

boolean

If true include the children in the returned resource. If false, only return the resource without its eventual children.

sort_by

string

The issue attribute to sort on. If omitted, sorting on last update time is applied

sort_direction

string

The direction to sort with. If omitted, sorting attribute descending is applied

Response

200 - Success.

limit

integer

The maximum number of resources to return.

total_count

integer

Total number of resources available.

first

DataQualityPageLink

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

issues

errors

array

Create a data quality issue

POST /data_quality/v4/issues

Create a data quality issue.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.issues.create

Auditing

Calling this method generates the following auditing event.

wdp-data_quality.issue.create

Request

Request Body

DataQualityIssuePrototype

Data quality issue to create.

check

Required *

object

the check that produces this issue

reported_for

Required *

object

The Id of the asset on which this issue was found

link

string

Link to corresponding data quality component. No default link is available, it is empty if not provided.

number_of_occurrences

integer

The absolute number of occurrences of the issues which have been identified on the asset. If this is missing, percent_occurrences must be provided.

number_of_tested_records

integer

The total number of records which have been tested by the Data Quality Check. If this is missing, percent_occurrences must be provided.

percent_occurrences

number

The relative frequency of the issue (percentage of tested records having the issue), as a number between 0.0 and 1.0. If omitted, it is calculated using number_of_occurrences and number_of_tested_records.

status

string

The status of the issue.

ignored

Required *

boolean

Flag indicating whether the issue is ignored or not.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

Response

201 - Success

check

object

the check that produces this issue

reported_for

object

The Id of the asset on which this issue was found

link

string

Link to corresponding data quality component. No default link is available, it is empty if not provided.

number_of_occurrences

integer

The absolute number of occurrences of the issues which have been identified on the asset. If this is missing, percent_occurrences must be provided.

number_of_tested_records

integer

The total number of records which have been tested by the Data Quality Check. If this is missing, percent_occurrences must be provided.

percent_occurrences

number

status

string

The status of the issue.

ignored

errors

array

Get the data quality issue with the given identifier

GET /data_quality/v4/issues/{id}

Get the data quality issue with the given identifier.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.issues.read

Request

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

Response

200 - Success.

check

object

the check that produces this issue

reported_for

object

The Id of the asset on which this issue was found

link

string

Link to corresponding data quality component. No default link is available, it is empty if not provided.

number_of_occurrences

integer

The absolute number of occurrences of the issues which have been identified on the asset. If this is missing, percent_occurrences must be provided.

number_of_tested_records

integer

The total number of records which have been tested by the Data Quality Check. If this is missing, percent_occurrences must be provided.

percent_occurrences

number

status

string

The status of the issue.

ignored

errors

array

Update a data quality issue as specified in the payload details

of the request.

PATCH /data_quality/v4/issues/{id}

Update a data quality issue as specified in the payload details of the request.

The updates must be specified by using the JSON patch format, described in RFC 6902. <p> The following attributes can be updated: - /ignored (value can only be replaced)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.issues.update

Auditing

Calling this method generates the following auditing event.

wdp-data_quality.issue.update

Request

Request Body

The updates to make in the data quality rule.

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

Response

200 - Success.

check

object

the check that produces this issue

reported_for

object

The Id of the asset on which this issue was found

link

string

Link to corresponding data quality component. No default link is available, it is empty if not provided.

number_of_occurrences

integer

The absolute number of occurrences of the issues which have been identified on the asset. If this is missing, percent_occurrences must be provided.

number_of_tested_records

integer

The total number of records which have been tested by the Data Quality Check. If this is missing, percent_occurrences must be provided.

percent_occurrences

number

status

string

The status of the issue.

ignored

boolean

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.issues.read

Request

Path Parameters

Query Parameters

reported_for.id

Required *

The data quality asset identifier

check.id

Required *

The data quality check identifier to search issues of.

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

Response

200 - Success.

archived_issues

array

An array of previous data quality issues detected during the same check on the given asset.

children

errors

array

POST /data_quality/v4/create_issues

Create several data quality issues. The related DQ assets referenced by their native ID are created if they do not already exist.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.issues.create

Auditing

Calling this method generates the following auditing event.

wdp-data_quality.issue.bulk.create

Request

Request Body

DataQualityIssuesBatchPrototype

Data quality issues to create and their related DQ assets.

issues

Required *

array

list of issues to create.

assets

array

Optional list of assets to create. For each of these assets the system will check if an asset with the same native_id exists. If yes, it will ignore it, if not it will create it

existing_checks

array

Optional list of existing checks. For each pair of (asset, check) given, system will create, update or remove an issue depending on the current issue stored for this pair and the new issue given in the payload (or not for deletion).

Path Parameters

Query Parameters

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

Response

201 - Success.

limit

integer

The maximum number of resources to return.

total_count

integer

Total number of resources available.

first

DataQualityPageLink

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

DataQualityPageLinkToken

The link to a page in paginated collection.

issues

errors

array

Get a list of data quality scores for a given asset

GET /data_quality/v4/scores

Get a list of data quality scores for a given asset.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.scores.create

Request

Path Parameters

Query Parameters

asset.id

Required *

The data quality asset identifier

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

dimension.id

The data quality dimension identifier. If not provided, filtering on dimension is not applied.

include_children

boolean

If true include the children in the returned resource. If false, only return the resource without its eventual children.

score_older_by_days

integer

Score of asset or dimension that is older by given days.

Response

200 - Success.

total_count

integer

Total number of scores available.

asset

DataQualityAssetInfo

Information of asset.

scores

array

An array of data quality scores.

children

errors

array

Get a list of data quality scores for a given assets

GET /data_quality/v4/bulkScores

Get a list of data quality scores for a given assets.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

dataquality.scores.create

Request

Path Parameters

Query Parameters

asset.ids

Required *

string

Comma-separated list of data quality assets identifier

catalog_id

string

The ID of the catalog to use. A catalog_id or project_id is required.

project_id

string

The ID of the project to use. A catalog_id or project_id is required.

dimension.id

The data quality dimension identifier. If not provided, filtering on dimension is not applied.

include_children

boolean

If true include the children in the returned resource. If false, only return the resource without its eventual children.

score_older_by_days

integer

Score of asset or dimension that is older by given days.

Response

200 - Success.

List environments.

GET /v2/environments

Returns a list of environments filtered by type, language or spark version in a project or space.

If no filter is provided, it returns all environments in the project or space, which includes all default environments that are available in every project or space and custom environments created by users.

You need to specify either `project_id` or `space_id`.

Request

Path Parameters

Comma-separated list of Spark versions. If provided, Spark environments will be filtered by these versions. Defaults to list of all default environments with supported Spark versions and all custom environments.

Response

200 -

400 -

401 -

403 -

Create a new environment.

POST /v2/environments

Returns a new environment with the provided parameters.

You need to specify either `project_id` or `space_id`.

Required body parameters vary dependent on environment types:

notebook: `type`, `name`, `display_name`, `hardware_specification`, `software_specification`, `tools_specification`
datastage: `type`, `name`, `display_name`, `hardware_specification`
other types: `type`, `name`, `display_name`, `hardware_specification`, `software_specification`

Request

Request Body

Path Parameters

Query Parameters

project_id

string

The guid of the project.

space_id

string

The guid of the space.

Response

201 -

400 -

401 -

403 -

429 -

Retrieve an environment.

GET /v2/environments/{environment_guid}

Returns an environment of a given ID. You need to specify either `project_id` or `space_id`.

Request

Path Parameters

Query Parameters

project_id

string

The guid of the project.

space_id

string

The guid of the space.

response_format

string

Format the response. Defaults to none.

embed_package_content

boolean

Whether to include conda_yml file content of custom package extensions in the response. Defaults to false.

Response

200 -

400 -

401 -

403 -

Delete an environment.

DELETE /v2/environments/{environment_guid}

Deletes an environment of a given ID. You need to specify either `project_id` or `space_id`.

Request

Path Parameters

Query Parameters

project_id

string

The guid of the project.

space_id

string

The guid of the space.

Response

204 -

400 -

401 -

403 -

Update an environment.

PATCH /v2/environments/{environment_guid}

Updates an environment of a given ID with the provided parameters. Returns the environment with updated properties. Only custom environments can be updated.

Request

Request Body

Path Parameters

Query Parameters

project_id

Required *

string

The guid of the project.

Response

200 -

400 -

401 -

403 -

List hardware specifications.

GET /v2/hardware_specifications

Returns a list of hardware specifications.

If neither `project_id` nor `space_id` is given, it returns all global hardware specifications.
If `project_id` or `space_id` is given, it returns all global and scoped hardware specifications. In this case, you need to specify either `project_id` or `space_id`.

Request

Path Parameters

Query Parameters

project_id

string

The guid of the project.

403 -

409 -

Retrieve a hardware specification.

GET /v2/hardware_specifications/{hardware_specification_guid}

Returns a hardware specification of a given ID.

To retrieve a global hardware specification, `project_id` or `space_id` is not required.
To retrieve a scoped hardware specification that is scoped to a project or a space, you need to specify either `project_id` or `space_id`.

Request

Path Parameters

Query Parameters

project_id

string

The guid of the project.

space_id

string

The guid of the space.

Response

200 -

400 -

401 -

403 -

Delete a hardware specification.

DELETE /v2/hardware_specifications/{hardware_specification_guid}

Deletes a hardware specification of a given ID.

Only scoped hardware specifications can be deleted through the API.

You need to specify either `project_id` or `space_id`.

Request

Path Parameters

Query Parameters

project_id

string

The guid of the project.

space_id

string

The guid of the space.

Response

204 -

400 -

401 -

403 -

Update a hardware specification.

PATCH /v2/hardware_specifications/{hardware_specification_guid}

Updates a hardware specification of a given ID with the provided parameters.

Only scoped hardware specifications can be updated through the API.

Request

Request Body

Path Parameters

Query Parameters

project_id

Required *

string

The guid of the project.

Response

204 -

400 -

401 -

403 -

List software specifications.

GET /v2/software_specifications

Returns a list of software specifications.

If neither `project_id` nor `space_id` is given, it returns all base software specifications.
If `project_id` or `space_id` is given, it returns all base and derived software specifications. In this case, you need to specify either `project_id` or `space_id`.

Request

Path Parameters

Query Parameters

space_id

string

The guid of the space.

project_id

string

The guid of the project.

include_packages

string

String of comma-separated package names that refers to the packages that a software specification should contain. If specified, each of the software specification in the returned list will contain all of the packages specified in the query.

name

The guid of the project.

Response

204 -

400 -

401 -

403 -

Retrieve a software specification.

GET /v2/software_specifications/{software_specification_guid}

Returns a software specification of a given ID.

To retrieve a base software specification, `project_id` or `space_id` is not required.
To retrieve a derived software specification that is scoped to a project or a space, you need to specify either `project_id` or `space_id`. When a derived software specification is retrieved, the return value shows the software configuration inherited from the base software specification instead of the ID of the base software specification.

Request

Path Parameters

Query Parameters

space_id

string

The guid of the space.

project_id

string

The guid of the project.

Response

200 -

400 -

401 -

403 -

Delete a software specification.

DELETE /v2/software_specifications/{software_specification_guid}

Deletes a software specification of a given ID.

Only derived software specifications can be deleted through the API.

You need to specify either `project_id` or `space_id`.

Request

Path Parameters

Query Parameters

space_id

string

The guid of the space.

project_id

string

The guid of the project. The deleted software specification must be scoped to the specified project.

Response

204 -

400 -

401 -

403 -

Add a package extension to a software specification.

PUT /v2/software_specifications/{software_specification_guid}/package_extensions/{package_extension_guid}

When successful, the specified package extension is appended to the array `entity.software_specification.package_extensions`. It is then the last package extension in that array.

You need to specify either `project_id` or `space_id`.

The request is valid if and only if:
1. The software specification identified by `software_specification_guid` and the package extension identified by `package_extension_guid` exist in the same scope (either project or space).
2. A successful POST `/v2/package_extensions/{package_extension_guid}/upload_complete` has been called before this request is initiated. I.e., the upload of the referenced `pip_zip` or `conda_yml` file has been indicated to have been successful.
3. The user is authorized to update the software specification asset.

Request

Path Parameters

Query Parameters

space_id

string

The guid of the space.

project_id

string

The guid of the project.

Response

204 -

400 -

401 -

403 -

409 - Conflict. The software specification already references this package extension.

Remove a package extension from a software specification.

DELETE /v2/software_specifications/{software_specification_guid}/package_extensions/{package_extension_guid}

When successful, the specified package extension is removed from the array `entity.software_specification.package_extensions`.

You need to specify either `project_id` or `space_id`.

Request

Path Parameters

Query Parameters

space_id

string

The guid of the space.

project_id

string

The guid of the project.

Response

204 -

400 -

401 -

403 -

List package extensions.

GET /v2/package_extensions

Returns all package extensions within the given project or space. You need to specify either `project_id` or `space_id`.

Request

Path Parameters

Query Parameters

space_id

string

The guid of the space.

project_id

string

The guid of the project.

name

string

Returning only those package extensions that have a particular name.

type

string

Returning only those package extensions that have a particular type.

Response

200 -

400 -

401 -

403 -

Create a new package extension.

POST /v2/package_extensions

Returns the new package extension created in the given project or space. You need to specify either `project_id` or `space_id`.

For uploading the pip_zip or conda_yml, once you have created a package extension, the response also contains a pre-signed URL which allows you to upload its contents. When the upload is complete, you must call `POST /v2/package_extensions/{package_extension_guid}/upload_complete` to indicate to the API that the package extension is usable. If the `/upload_complete` returns successfully, the package extension is usable, i.e., can be assigned to a software specification.

Request

Request Body

Path Parameters

Query Parameters

space_id

string

The guid of the space.

project_id

string

The guid of the project in which to create the package extension.

Response

201 -

400 -

401 -

403 -

Mark file upload complete.

POST /v2/package_extensions/{package_extension_guid}/upload_complete

Indicates that the upload of the library file attached to the package extension is complete and this package extension is usable. You need to specify either `project_id` or `space_id`.

Request

Path Parameters

package_extension_guid

Required *

401 -

403 -

Update a package extension.

PATCH /v2/package_extensions/{package_extension_guid}

Updates a package extension of a given ID with the provided parameters.

Request

Request Body

Path Parameters

Query Parameters

project_id

Required *

string

The guid of the project.

Response

204 -

400 -

401 -

403 -

Retrieve a package extension.

GET /v2/package_extensions/{package_extension_guid}

Retrieves a package extension of a given ID. You need to specify either `project_id` or `space_id`.

Request

Path Parameters

Query Parameters

space_id

string

The guid of the space.

project_id

string

The guid of the project.

Response

200 -

400 -

401 -

403 -

Delete a package extension.

DELETE /v2/package_extensions/{package_extension_guid}

Deletes a package extension of a given ID. You need to specify either `project_id` or `space_id`.

Request

Path Parameters

Query Parameters

space_id

string

The guid of the space.

project_id

string

The guid of the project.

Response

204 -

400 -

401 -

403 -

A update operation allowing you to update artifacts based on a simple query.

POST /v3/search/update_by_query

Execute an operation to update artifacts using a simple query for one or more specified microservices (provider_ids).

Request

Request Body

GlobalSearchRelationshipUpdateBody

last_updated_at

integer

query

string

script

string

provider_type_id_list

array

Path Parameters

Query Parameters

Response

200 - OK

202 - Accepted

204 - No Content

206 - Partial Content

400 - Bad request

401 - Unauthorized

403 - Forbidden

500 - Internal error. Try again later.

503 - Service Unavailable

default - Success response content

Test if sss is up.

GET /v3/search/sss_heartbeat

Request

Response

200 - OK

400 - Bad Request

500 - Internal error. Try again later.

Execute a query based on the Lucene Syntax

GET /v3/search

Execute a query and pass in a selection of words to search for or pass in a Lucene query. Your Lucene query can be as simple or as sophisticated as you like. Beware, however. If you plan on passing in a query directly from user input, make sure to set the 'isSimple' parameter to 'true' (the default is 'false'). Otherwise, Global Search will use the underlying query_string function that enforces a strict Lucene query syntax, and your query may return an exception if the user input includes reserved Lucene tokens or symbols that are used incorrectly. When the 'isSimple' parameter is set to true, Global Search will the ElasticSearch simple_query_string function that uses a modified Lucene syntax as follows:<br> <br>  + = AND operation<br>  | = OR operation<br>  - = NOT <br>  " wraps a phrase<br>  * is a wildcard (you can't use it at the beginning of a word but you can use it alone to signify match all)<br>  ( and ) evaluates tokens inside brackets with higher precedence<br> <br> To use one of these characters literally, escape it with a preceding backslash. <br><br> Global Search allows users to search for assets and artifacts on the platform. The number of documents for all search results is limited to 10000. <br> <br> Please notice that the response shows all possible fields, which are not applicable for all types. For example "custom_attributes" are only applicable to assets currently, and even then only to certain custom attributes depending how they have been defined. Likewise, "categories" are only applicable to artifacts, etc. <br>

Request

Path Parameters

Query Parameters

query

Required *

200 - OK

size

integer

rows

array

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal error. Try again later.

Execute a query and pass in a structured query conforming to the Elasticsearch Domain Specific Language.

POST /v3/search

Execute a query and pass in a structured query based on the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html">Elasticsearch Domain Specific Language</a><br> For example:<br> {<br>     "query": {<br>         "match_all": {}<br>     }<br> }<br> <br> You can also use this API to execute the Global Search user search function as follows:<br> {<br>     "query": {<br>         "gs_user_query": {<br>             "search_string": "the quick red fox jumped over the lazy brown dog",<br>             "search_fields": ["metadata.name", "metadata.description"],<br>             "nlq_analyzer_enabled": true,<br>             "nested": false<br>         }<br>     }<br> }<br> <br> Global Search allows users to search for assets and artifacts on the platform. The number of documents for all search results is limited to 10000. <br> <br> When search fields are specified, the search will be restricted to the specified fields. If no search fields are specified, the search will run across all fields in the configuration. <br> When the natural language analyzer is enabled, words which are not relevant to the search will be ignored, and common phrases will be prioritized.<br> <br> When semantic search is enabled, search strings containing a business term name or abbreviation will also include results for synonym, child and related business terms. ,Knowledge graph installation is required for semantic search.<br>

<br> Please notice that the response shows all possible fields, which are not applicable for all types. For example "custom_attributes" are only applicable to assets currently, and even then only to certain custom attributes depending how they have been defined. Likewise, "categories" are only applicable to artifacts, etc. <br> <br> For more information regarding how to use this function, consult the Getting Started section of this guide.

Request

Request Body

A string representing a query. The query must conform to Elasticsearch Domain Specific Language. For more details, read the Search section in the getting started guide.

Path Parameters

Query Parameters

role

string

For governance artifacts limited by zone, limit with this role access.

auth_cache

boolean

Use cached authorization info for building ACL filters.

auth_scope

string

The ACL filters applied to the query.

Response

200 - OK

size

integer

rows

array

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal error. Try again later.

GET /v3/search/search_facet

This API will return all available pre search filters

Request

Path Parameters

Query Parameters

Response

200 - OK

size

integer

rows

array

400 - Bad Request

401 - Unauthorized

403 - Forbidden

500 - Internal error. Try again later.

Creates a category in the glossary

POST /v3/categories

This method can be used to create a new category in the glossary.

Request

Request Body

GlossaryV3NewCategoryEntity

classifications

array

Relationships to classifications.

custom_attributes

array

List of custom attributes with their values.

custom_relationships

array

Custom relationships to asset

long_description

string

The long description of an artifact.

name

Required *

string

The name of the artifact.

parent_category_id

string

Artifact ID of a parent category

reference_copy

boolean

Indicates that it is a reference copy of an artifact managed in an external metadata server.

reporting_authorized

boolean

Used by reporting service for authorization. Can be set only for root level categories.

response_custom_relationships

array

Custom relationships to asset

short_description

string

The short description of an artifact.

steward_group_ids

array

The steward groups assigned to an artifact.

steward_ids

array

The stewards assigned to an artifact.

Response

List of errors.

trace

string

The trace id.

Start category boostrap process

POST /v3/categories/collaborators/bootstrap

Assigns default owners and view permissions for root categories without any role assignments set

Request

Response

The trace id.

Get status of category bootstrap process

GET /v3/categories/collaborators/bootstrap/status

Get status of category bootstrap process

Request

Response

200 - Bootstrap status fetched successfully

completed_records

integer

Number of records already bootstrapped successfully

completion_message

string

Overall outcome of the bootstrap process. Set once bootstrapping is finished.

current_step

string

Current bootstrap activity

errors

The trace id.

Get history status of category bootstrap process

GET /v3/categories/collaborators/bootstrap/status/history

Get history status of category bootstrap process

Request

Response

200 - Bootstrap status history fetched successfully

bootstrap_status_history

array

Bootstrap status history list

401 - Unauthorized

errors

array

List of errors.

trace

string

The trace id.

500 - Internal Server Error

errors

array

List of errors.

trace

string

The trace id.

Retrieves category hierarchy paths for given artifact ids of categories

GET /v3/categories/hierarchy

This method can be used for retrieving hierarchy paths of categories

Request

Path Parameters

Query Parameters

category_id

array

The id of the category whose path is fetched

Response

List of errors.

trace

string

The trace id.

Retrieves category hierarchy paths for given artifact ids of categories

POST /v3/categories/hierarchy

This method can be used for retrieving hierarchy paths of categories

Request

Request Body

GlossaryV3GlossaryResourceList

resources

array

List of resources.

Path Parameters

Query Parameters

limit

integer

The maximum number of categories to return - must be at least 1 and cannot exceed 1000. The default value is 10.

offset

integer

The index of the first matching category to include in the result.

Response

200 - The hierarchy paths of categories have been retrieved successfully

category_hierarchy_paths

array

IDs and names of categories in category hierarchy path for each category id

401 - Unauthorized

errors

array

List of errors.

trace

string

The trace id.

500 - Internal Server Error

errors

array

List of errors.

trace

string

The trace id.

Retrieves the special [uncategorized] category

GET /v3/categories/uncategorized

This method can be used for retrieving details of the special [uncategorized] category, which is a default one for all artifacts.

Request

Response

200 - The category has been retrieved successfully.

entity

GlossaryV3CategoryEntity

Represents a category.

metadata

GlossaryV3GlossaryObjectMetadataV3

Metadata of the entity.

401 - Unauthorized

errors

array

List of errors.

trace

string

The trace id.

403 - Forbidden

errors

array

List of errors.

trace

string

The trace id.

500 - Internal Server Error

errors

array

List of errors.

trace

string

The trace id.

Deletes the category with a given guid

DELETE /v3/categories/{category_id}

This method can be used to delete a category.<br>Note! The category must be empty. It can contain neither child categories nor artifacts.

Request

Path Parameters

category_id

Required *

string

Artifact ID or global ID of the artifact

Query Parameters

Response

200 - The category has been deleted successfully.

archived_guids

The trace id.

Retrieves category with given guid

GET /v3/categories/{category_id}

This method can be used for retrieving details of a category.

Request

Path Parameters

category_id

Required *

string

Artifact ID or global ID of the artifact

Query Parameters

include_relationships

boolean

When set to true fetch category relationships user has access to. It returns at most 1000 relationships. If parameter is not set its default value is 'true'. This is deprecated and default will be change to 'false' in first major 2022 release.<br/>Deprecated, functionality will be replaced by new one introduced in the feature releases.

include_custom_attributes

boolean

string

The trace id.

Updates category with given id

PATCH /v3/categories/{category_id}

array

The steward groups assigned to an artifact.

steward_ids

array

The stewards assigned to an artifact.

Path Parameters

category_id

Required *

string

Artifact ID or global ID of the artifact

Query Parameters

The trace id.

Removes an artifact from its secondary category

DELETE /v3/categories/{category_id}/artifacts/{artifact_id}

It can be used to remove a secondary category assignment for an artifact. It does not allow to remove an artifact from a primary category as a primary category assignment is obligatory.

Request

Path Parameters

category_id

Required *

string

The artifact ID or the global ID of a category

artifact_id

Required *

string

The artifact ID or the global ID of an artifact to be removed from a (secondary) category

Query Parameters

Response

The trace id.

Adds an artifact to a category

PUT /v3/categories/{category_id}/artifacts/{artifact_id}

It can be used to set a primary category for an artifact (replacing an old primary category assignment if existed) as well as to add an artifact to a secondary category.

Request

Request Body

GlossaryV3NewCategoryAssignment

artifact_type

Required *

string

Type of the artifact to be added to a category

is_primary_category

GET /v3/categories/{category_id}/collaborators

Single collaborator is an users with assigned roles in context of given category. A role comes with rights to access the category, its sub-categories and artifacts and potential responsibilities.

Request

Path Parameters

category_id

Required *

string

The artifact ID or the global ID of a category

Query Parameters

include_inherited

boolean

If this parameter is true, the returned list contains collaborators not only for given category, but also for all parent categories, up to root category.

role

array

string

The trace id.

Creates single collaborator for given category

POST /v3/categories/{category_id}/collaborators

To create collaborator one needs to provide id of the collaborating user and the name of the role he will be permitted. Collaborator is effective for given category and whole tree of its subcategories.

Request

Type of the user. When not provided defaults to USER

Path Parameters

category_id

Required *

string

The artifact ID or the global ID of a category

Query Parameters

Response

201 - The collaborator has been created successfully.

category_artifact_id

string

Category Artifact Id

category_name

string

Category Name

create_time

string

Create Time

dps_rule_id

string

DPS Rule Id

id

string

principal_id

The trace id.

Deletes single collaborator

DELETE /v3/categories/{category_id}/collaborators/{collaborator_id}

Collaborator represents single user together with single role that gives him certain privileges in context of given category.

Request

Path Parameters

category_id

Required *

string

The artifact ID or the global ID of a category

collaborator_id

Required *

string

The id of the collaborator.

Query Parameters

Response

The trace id.

List the relationships of the given type for the specified category

GET /v3/categories/{category_id}/relationships

If the result set is larger than the <code>limit</code> parameter, it returns the first <code>limit</code> number of relationships. <br/>To retrieve the next set of relationships, call the method again by using the URI in the property <code>next</code> returned by this method.

Request

Path Parameters

category_id

Required *

Is custom relationship reversed?

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

include_target_parent_category_name

boolean

Retrieves target parent category name of the relationship entity.

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - Success

custom_relationships

array

List of custom relationships

empty

Request

Path Parameters

category_id

Required *

string

The artifact ID of the category to fetch.

relationship_id

Required *

string

The artifact ID of the relationship to be deleted.

Query Parameters

Response

The trace id.

Get role usage statistics

GET /v3/category_role_statistics

Get list of roles assigned in glossary, along with number of categories where specific role is used.

Request

Response

200 - Success

role_assignment_statistics

array

List of roles assigned in glossary, along with number of categories which have role assigned

401 - Unauthorized

errors

array

List of errors.

trace

string

The trace id.

500 - Internal Server Error

errors

array

List of errors.

trace

string

The trace id.

Returns list of categories which has specific role assigned, along with number of assignments for users and groups

GET /v3/category_statistics

Category statistics

Request

Path Parameters

Query Parameters

role

Required *

string

Role for which statistics are to be retrieved

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - Success

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Comma-separated list of relationship types.<br/><table><tbody><tr><td colspan="2">Available types:</td></tr><tr><td><code>is_a_type_of_classification</code></td><td></td></tr><tr><td><code>has_types_classifications</code></td><td></td></tr><tr><td><code>has_types_classifications_hierarchy</code></td><td></td></tr><tr><td><code>categories</code></td><td></td></tr><tr><td><code>parent_category</code></td><td></td></tr><tr><td><code>terms</code></td><td></td></tr><tr><td><code>data_classes</code></td><td></td></tr><tr><td><code>policies</code></td><td></td></tr><tr><td><code>rules</code></td><td></td></tr><tr><td><code>reference_data</code></td><td></td></tr><tr><td><code>related_categories</code></td><td></td></tr><tr><td><code>custom</code></td><td></td></tr><tr><td><code>all</code></td><td></td></tr></tbody></table>

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

include_custom_attributes

boolean

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - Success

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

DELETE /v3/classifications/{artifact_id}/versions/{version_id}

If the artifact state is <code>DRAFT</code>, then the draft version is deleted.<br/><br/> If the artifact state is <code> PUBLISHED</code>, a draft version with <code>marked_for_deletion</code> is created .<br/><br/> If the artifact state is <code> PUBLISHED</code> and workflow is skipped, then the published version is deleted.<br/><br/> If a draft artifact already exists for deletion for a published artifact, then the draft artifact is simply skipped.<br/><br/> Administrator role is required.

Request

Path Parameters

artifact_id

Required *

string

The guid of the classification to fetch.

version_id

Required *

string

The version id of the classification to delete.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

201 - A draft version has been successfully created for deleting the published artifact.

resources

array

string

The trace id.

Retrieves classification with given guid

GET /v3/classifications/{artifact_id}/versions/{version_id}

This method can be used for retrieving details of an ACTIVE or DRAFT classification.

Request

Path Parameters

artifact_id

Required *

string

The artifact id of the classification to fetch.

version_id

Required *

string

The version id of the classification to fetch.

Query Parameters

include_relationship

string

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

include_custom_attributes

boolean

limit

integer

string

The trace id.

Updates a draft or published artifact

PATCH /v3/classifications/{artifact_id}/versions/{version_id}

boolean

Indicates that it is a reference copy of an artifact managed in an external metadata server.

related_categories

array

Relationships to categories.

revision

Required *

array

Relationships to business terms.

Path Parameters

artifact_id

Required *

string

The artifact id of the classification to be updated.

version_id

Required *

string

The version id of the classification to be updated.

Query Parameters

skip_workflow_if_possible

boolean

string

The trace id.

List the associations of the given type for the specified classification

GET /v3/classifications/{artifact_id}/versions/{version_id}/relationships

Request

Path Parameters

artifact_id

Required *

string

The artifactId of the classification

version_id

Required *

string

The versionId of the classification

Query Parameters

type

Required *

string

ca_definition_id

string

Custom relationship definition Id.

is_reversed

boolean

Is custom relationship reversed?

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

include_target_parent_category_name

boolean

Retrieves target parent category name of the relationship entity.

limit

integer

The maximum number of associations to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - Success

custom_relationships

array

List of custom relationships

empty

The relationships to business terms.

Path Parameters

artifact_id

Required *

string

The artifact id of the classification to fetch.

version_id

Required *

string

The version id of the classification to fetch.

Query Parameters

skip_workflow_if_possible

boolean

If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Deletes relationships for an artifact in the glossary

DELETE /v3/classifications/{artifact_id}/versions/{version_id}/relationships/{relationship_id}

If it is a published version, it creates a draft from the published version and deletes the relationship from the draft version. And, it returns the details of the draft version.

Request

The artifact ID of the relationship to be deleted.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

200 - Success

archived_guids

The trace id.

Retrieves the data classes matching specified parameters.

GET /v3/data_classes

This method is used to retrieve the data classes that the user have permissions and they match specified parameters.

Request

Path Parameters

Query Parameters

status

string

Comma-separated list of dataclass statuses.<br/><table><tbody><tr><td colspan="2">Available statuses:</td></tr><tr><td><code>PUBLISHED</code></td><td>artifacts which are in published state (does not takes effective dates into account)</td></tr><tr><td><code>ACTIVE</code></td><td>artifacts which are published, and which effective date period includes current datetime</td></tr><tr><td><code>DELETED</code></td><td>artifacts which have been deleted</td></tr></tbody></table>

enabled

string

To filter data classes based on enabled property. The enabled query parameter accepts (Yes, No, Both) where Yes is the default value. This option is not applicable for format=xml.

include_xml_definitions

boolean

If this parameter is set to true, then Dataclass' xml definitions are returned. If parameter is not set its default value is 'true'

include_custom_attributes

boolean

If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'false'.

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

since

string

A filter to artifacts that have been created / updated / deleted since the given timestamp in this format: [yyyy-MM-ddTHH:mm:ss.SSSZ]

limit

integer

The maximum number of data_classes to return - must be at least 1 and cannot exceed 1000. The default value is 10.

offset

integer

The index of the first matching data_class to include in the result.

Response

200 - Success

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

string

The trace id.

Creates a draft data class in the glossary

POST /v3/data_classes

valid_values

array

To specify valid values; ( This property is applicable for data class type: ValidValues )

workflow_state

string

The workflow state of an artifact

Path Parameters

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Comma-separated list of relationship types.<br/><table><tbody><tr><td colspan="2">Available types:</td></tr><tr><td><code>is_a_type_of_data_class</code></td><td></td></tr><tr><td><code>has_types_data_classes</code></td><td></td></tr><tr><td><code>has_types_data_class_hierarchy</code></td><td></td></tr><tr><td><code>parent_category</code></td><td></td></tr><tr><td><code>categories</code></td><td></td></tr><tr><td><code>terms</code></td><td></td></tr><tr><td><code>classifications</code></td><td></td></tr><tr><td><code>policies</code></td><td></td></tr><tr><td><code>rules</code></td><td></td></tr><tr><td><code>reference_data</code></td><td></td></tr><tr><td><code>custom</code></td><td></td></tr><tr><td><code>all</code></td><td></td></tr></tbody></table><br/>Note: <code>all</code> does not return data class hierarchy.

include_custom_attributes

boolean

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - The data class has been retrieved successfully.

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

DELETE /v3/data_classes/{artifact_id}/versions/{version_id}

Request

Path Parameters

artifact_id

Required *

string

The artifact id of the dataclass to delete.

version_id

Required *

string

The version id of the dataclass to delete.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

201 - A draft version has been successfully created for deleting the published artifact.

resources

array

string

The trace id.

Retrieves data class with given guid

GET /v3/data_classes/{artifact_id}/versions/{version_id}

This method can be used for retrieving details of an ACTIVE or DRAFT data class.

Request

Path Parameters

artifact_id

Required *

string

The artifact ID of the data class to fetch.

version_id

Required *

string

The version ID of the data class to fetch.

Query Parameters

include_relationship

string

include_custom_attributes

boolean

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

limit

integer

Required *

string

To specify valid values; ( This property is applicable for data class type: ValidValues )

Path Parameters

artifact_id

Required *

string

The artifact id of the data class to be updated.

version_id

Required *

string

The version id of the data class to be updated.

Query Parameters

skip_workflow_if_possible

boolean

string

The trace id.

List the relationships of the given type for the specified data class

GET /v3/data_classes/{artifact_id}/versions/{version_id}/relationships

Request

Path Parameters

artifact_id

Required *

string

The artifact ID of the data class to fetch.

version_id

Required *

string

The version ID of the data class to fetch.

Query Parameters

type

Required *

string

ca_definition_id

string

Custom relationship definition Id.

is_reversed

boolean

Is custom relationship reversed?

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

include_target_parent_category_name

boolean

Retrieves target parent category name of the relationship entity.

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - Success

custom_relationships

array

List of custom relationships

empty

The relationships to business terms.

Path Parameters

artifact_id

Required *

string

The artifact ID of the data class to fetch.

version_id

Required *

string

The version ID of the data class to fetch.

Query Parameters

skip_workflow_if_possible

boolean

If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Deletes relationships for an artifact in the glossary

DELETE /v3/data_classes/{artifact_id}/versions/{version_id}/relationships/{relationship_id}

If it is a published version, it creates a draft from the published version and deletes the relationship from the draft version. And, it returns the details of the draft version.

Request

The artifact ID of the relationship to be deleted.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

200 - Success

archived_guids

The trace id.

Business Glossary Heartbeat

GET /v3/glossary_status/heartbeat

Returns the build details and health of the dependent services

Request

Response

The version of the build.

500 - Internal Server Error

errors

array

List of errors.

trace

string

The trace id.

Tenant init and status

POST /v3/glossary_status/tenant_init

Checks tenant init status (and initialize if necessary), blocks until init is done

Request

Response

204 - Success

503 - Requested data are not available, try again later.

errors

array

List of errors.

trace

string

The trace id.

Tenant init and status

GET /v3/glossary_status/tenant_init_status

Checks tenant init status, returns immediately (initialization if required is performed in background)

Request

Response

200 - Success

status

string

tenant status, one of READY, NOT READY

Creates draft terms in the glossary

POST /v3/glossary_terms

If the unique constraint on the name or display name of the term is violated, the method fails with <code>409 Conflict</code> response.

Request

Request Body

Terms to be created. The terms array must contain at least 1 term, and cannot exceed 100 terms.

Path Parameters

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Comma-separated list of relationship types.<br/><table><tbody><tr><td colspan="2">Available types:</td></tr><tr><td><code>is_a_type_of_terms</code></td><td></td></tr><tr><td><code>has_type_terms</code></td><td></td></tr><tr><td><code>has_types_term_hierarchy</code></td><td></td></tr><tr><td><code>synonym_terms</code></td><td></td></tr><tr><td><code>related_terms</code></td><td></td></tr><tr><td><code>data_classes</code></td><td></td></tr><tr><td><code>is_of_terms</code></td><td></td></tr><tr><td><code>has_terms</code></td><td></td></tr><tr><td><code>categories</code></td><td></td></tr><tr><td><code>parent_category</code></td><td></td></tr><tr><td><code>classifications</code></td><td></td></tr><tr><td><code>policies</code></td><td></td></tr><tr><td><code>rules</code></td><td></td></tr><tr><td><code>reference_data</code></td><td></td></tr><tr><td><code>reference_data_values</code></td><td></td></tr><tr><td><code>custom</code></td><td></td></tr><tr><td><code>all</code></td><td></td></tr></tbody></table>

include_custom_attributes

boolean

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - Success

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

DELETE /v3/glossary_terms/{artifact_id}/versions/{version_id}

Request

Path Parameters

artifact_id

Required *

string

The artifact id of the term to fetch.

version_id

Required *

string

The version id of the term to delete.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Gets the term in the glossary with a given version id

GET /v3/glossary_terms/{artifact_id}/versions/{version_id}

This method can be used for retrieving details of an ACTIVE or DRAFT term.

Request

Path Parameters

artifact_id

Required *

string

The artifact id of the term to fetch.

version_id

Required *

string

The version id of the term to fetch.

Query Parameters

include_relationship

string

include_custom_attributes

boolean

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

all_parents

boolean

Required *

artifact_id

Required *

string

The artifact id of the term to be updated.

version_id

Required *

string

The version id of the term to be updated.

Query Parameters

skip_workflow_if_possible

boolean

string

The trace id.

List the relationships for the specified term

GET /v3/glossary_terms/{artifact_id}/versions/{version_id}/relationships

Request

Path Parameters

artifact_id

Required *

string

The guid of the Term

version_id

Required *

string

The versionID of the Term

Query Parameters

type

Required *

string

ca_definition_id

string

Custom relationship definition Id.

is_reversed

boolean

Is custom relationship reversed?

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

include_target_parent_category_name

boolean

Retrieves target parent category name of the relationship entity.

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - Success

custom_relationships

array

List of custom relationships

empty

The list of synonym business terms.

Path Parameters

artifact_id

Required *

string

The artifact ID of the term to fetch.

version_id

Required *

string

The version ID of the term to fetch.

Query Parameters

skip_workflow_if_possible

boolean

If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Deletes relationships for an artifact in the glossary

DELETE /v3/glossary_terms/{artifact_id}/versions/{version_id}/relationships/{relationship_id}

If it is a published version, it creates a draft from the published version and deletes the relationship from the draft version. And, it returns the details of the draft version.

Request

The artifact ID of the relationship to be deleted.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Exports custom attribute definitions to a json file

POST /v3/governance_artifact_types/custom_attribute_definitions/export

This method can be used to export custom attribute definitions to a json file.

Request

Request Body

GlossaryV3GlossaryResourceList

The list of custom attribute definitions artifact ids to be exported.

resources

array

List of resources.

Path Parameters

Query Parameters

types

string

The comma-separated list of supported custom attribute types. Allowed values are text, date, number, enum, relationship, all, all_without_relationship.

artifact_types

string

The artifact type which a custom attribute definition applies to. Allowed values are category, glossary_term, data_class, policy, rule, classification, reference_data

related_artifact_types

string

The related artifact type which a custom attribute definition for relationship applies to. Allowed values are category, glossary_term, data_class, policy, rule, classification, reference_data

Response

The trace id.

Import values for custom attribute definitions from specified json file

POST /v3/governance_artifact_types/custom_attribute_definitions/import

This method can be used to import values custom attribute definitions from specified json file.

Request

Request Body

Path Parameters

Query Parameters

subtype

string

Determines if only custom properties or custom relationships or both types will be imported. Allowed values: ALL, PROPERTY, RELATIONSHIP.

async_mode

boolean

If async_mode is true, then the method starts an asynchronous process to execute the given action and returns with ACCEPTED 202 status code.

Response

Total steps

workflow_id

string

GET /v3/governance_artifact_types/export

This method can be used to export values of all supported types to a ZIP file.

Request

Path Parameters

Query Parameters

artifact_id_mode

string

This specifies if artifact ID numbers should be included in exported files, or not. Possible values: "always", artifact ID numbers are included for artifacts, and "never", not included at all.

artifact_types

string

The comma-separated list of supported artifact types. Allowed values are all, category, classification, data_class, glossary_term, policy, rule, reference_data and role_assignment.

category_ids

string

The comma-separated list of categories ID numbers, or "all_top_level", which means all top-level categories.

include_custom_attribute_definitions

boolean

If parameter "include_custom_attribute_definitions" is set to true, information about suitable custom attribute definitions will be included in zip

include_development_log

boolean

If parameter "include_development_log" is set to true, development log content will be included in zip

Response

The trace id.

Import values from specified ZIP file

POST /v3/governance_artifact_types/import

This method can be used to import values from specified ZIP file.

Request

Request Body

Path Parameters

Query Parameters

merge_option

string

Import merge option, valid values: <br/>all - imported values will replace existing values in catalog<br/>specified - imported values that are not empty replace existing values in catalog<br/>empty - imported values replace only empty values in catalog.

Response

Total steps

workflow_id

string

POST /v3/governance_artifact_types/import/cleanup/{process_id}

This method can be used to cleanup specified stalled ZIP import process that crashed or hanged. Note: This feature is experimental - the API and scope are subject to change. Should not be used on imports that are alive or pending as it can lead to unpredictable results.

Request

Path Parameters

process_id

Required *

string

Import process id

Query Parameters

Response

The trace id.

Import of assets status

GET /v3/governance_artifact_types/import/status/{process_id}

Import of assets status

Request

Path Parameters

process_id

Required *

string

Import process id

Query Parameters

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

GET /v3/governance_artifact_types/{artifact_type}/custom_attribute_definitions

This method can be used for retrieving details of custom attribute definitions.

Request

Path Parameters

artifact_type

Required *

string

The artifact type. Allowed values are all, category, glossary_term, classification, data_class, reference_data, policy, rule

Query Parameters

is_related_artifact_type

boolean

Is the artifact type defined as related artifact type or not, in case of "RELATIONSHIP" type only!

Response

200 - The custom attribute definitions have been retrieved successfully.

entity

GlossaryV3CustomAttributeDefinitionEntity

Custom Attribute Definition Entity

metadata

GlossaryV3GlossaryObjectMetadataV3

Metadata of the entity.

401 - Unauthorized

errors

array

List of errors.

trace

string

The trace id.

404 - The custom attribute definition with given {artifact_id} does not exist.

errors

array

List of errors.

trace

string

The trace id.

500 - Internal Server Error

errors

array

List of errors.

trace

string

The trace id.

Creates custom attribute definition in the glossary

POST /v3/governance_artifact_types/{artifact_type}/custom_attribute_definitions

boolean

Specifies whether the custom attribute can have more than one value

name

Required *

string

Name of custom attribute

read_only

boolean

Specifies whether custom attribute values should be read only

related_artifact_types

array

Set of related artifact types

related_category_artifact_ids

array

Set of restricted related category artifact ids

reverse_name

string

Reversed Custom Attribute relationship name which may be display on the related artifact

searchable

boolean

Specifies whether custom attribute definition should be global search

type

Required *

string

Type of custom attribute values

Path Parameters

artifact_type

Required *

string

The artifact type. Allowed values are all, category, glossary_term, classification, data_class, reference_data, policy, rule

Query Parameters

Response

List of errors.

trace

string

The trace id.

Deletes the custom attribute definition with a given artifact_id

DELETE /v3/governance_artifact_types/{artifact_type}/custom_attribute_definitions/{custom_attribute_definition_artifact_id}

This method is used to delete the custom attribute definition with a given artifact_id (guid).

Request

Path Parameters

artifact_type

Required *

string

The artifact type. Allowed values are all, category, glossary_term, classification, data_class, reference_data, policy, rule

custom_attribute_definition_artifact_id

Required *

string

The artifact_id of the custom attribute definition to be purged.

Query Parameters

Response

200 - The custom attribute definition has been deleted successfully.

archived_guids

The trace id.

Retrieves custom attribute definition with given artifact_id

GET /v3/governance_artifact_types/{artifact_type}/custom_attribute_definitions/{custom_attribute_definition_artifact_id}

This method can be used for retrieving details of a custom attribute definition.

Request

Path Parameters

artifact_type

Required *

string

The artifact type. Allowed values are all, category, glossary_term, classification, data_class, reference_data, policy, rule

custom_attribute_definition_artifact_id

Required *

string

The artifact_id of the custom attribute definition to fetch.

Query Parameters

Response

200 - The custom attribute definition has been retrieved successfully.

entity

GlossaryV3CustomAttributeDefinitionEntity

Custom Attribute Definition Entity

metadata

GlossaryV3GlossaryObjectMetadataV3

Metadata of the entity.

401 - Unauthorized

errors

array

List of errors.

trace

string

The trace id.

404 - The custom attribute definition with given {artifact_id} does not exist.

errors

array

List of errors.

trace

string

The trace id.

500 - Internal Server Error

errors

array

List of errors.

trace

string

The trace id.

Updates custom attribute definition with given artifact_id

PATCH /v3/governance_artifact_types/{artifact_type}/custom_attribute_definitions/{custom_attribute_definition_artifact_id}

array

Set of restricted related category artifact ids

reverse_name

string

Reversed Custom Attribute relationship name which may be display on the related artifact

searchable

boolean

Specifies whether custom attribute definition should be global search

Path Parameters

artifact_type

Required *

string

The artifact type. Allowed values are all, category, glossary_term, classification, data_class, reference_data, policy, rule

custom_attribute_definition_artifact_id

Required *

string

The artifact_id of the custom attribute definition to be updated.

Query Parameters

The trace id.

Delete a list of draft or published versions of given artifact_type

POST /v3/governance_artifact_types/{artifact_type}/delete

Request

Request Body

GlossaryV3GlossaryResourceIdentifierList

The list of artifacts to be deleted. All the artifacts must be either in published state or draft state, but mix of draft and published state is not allowed.

resources

array

List of resource identifiers.

Path Parameters

artifact_type

Required *

string

The artifact type. Allowed values are category, glossary_term, classification, data_class, reference_data, policy, rule

Query Parameters

async_mode

boolean

If async_mode is true, then the method starts an asynchronous process to execute the given action and returns with ACCEPTED 202 status code.

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

skip_if_draft_exists

boolean

If someone has already created a draft for deleting or updating an artifact, then the artifact will be ignored.

skip_if_not_exists

boolean

If specified asset does does not exist, it is skipped.

Response

201 - A draft version has been successfully created for deleting the published artifact.

202 - If async_mode is true, then the method starts an asynchronous process to execute the given action and returns with ACCEPTED 202 status code.

task_id

string

string

The trace id.

Exports values of a specified type to a csv file

GET /v3/governance_artifact_types/{artifact_type}/export

This method can be used to export values of a specified type to a csv file.

Request

Path Parameters

artifact_type

Required *

string

The artifact type. Allowed values are category, glossary_term, data_class, policy, rule, classification

Query Parameters

category_id

string

The artifactId of the parent category

include_category

boolean

Whether to include the parent category. This applies to category (as asset type) export only, and is ignored for other asset types. The special [uncategorized] category is not included.

include_subcategories

boolean

Whether to include assets from subcategories

Response

The trace id.

Import values from specified csv file

POST /v3/governance_artifact_types/{artifact_type}/import

This method can be used to import values from specified csv file.

Request

Request Body

Path Parameters

artifact_type

Required *

string

The artifact type. Allowed values are category, glossary_term, classification, data_class, reference_data, policy, rule

Query Parameters

merge_option

string

async_mode

boolean

If async_mode is true, then the method starts an asynchronous process to execute the given action and returns with ACCEPTED 202 status code.

Response

Total steps

workflow_id

string

POST /v3/governance_artifact_types/{artifact_type}/search

This method can be used for retrieving draft artifacts.

Request

Request Body

GlossaryV3GlossaryResourceList

The list of draft artifacts to be retrieved. If drafts exist, then they are returned.

resources

array

List of resources.

Path Parameters

artifact_type

Required *

string

The artifact type. Allowed values are category, glossary_term, classification, data_class, reference_data, policy, rule

Query Parameters

Response

The trace id.

Get the latest published version of the specified artifact

GET /v3/governance_artifact_types/{artifact_type}/{artifact_id}

This method can be used for getting the latest published version of the specified artifact.

Request

Path Parameters

artifact_type

Required *

string

The artifact type. Allowed values are category, glossary_term, classification, data_class, reference_data, policy, rule

artifact_id

Required *

string

Artifact ID or global ID of the artifact

Query Parameters

include_relationship

string

Comma-separated list of relationship types.<br/><table><thead><tr><th><code>Relationship Types</code></th><th colspan=7><code>Artifact Types</code></th></tr><tr><th></th><th><code>category</code></th><th><code>classification</code></th><th><code>data_class</code></th><th><code>glossary_term</code></th><th><code>policy</code></th><th><code>reference_data</code></th><th><code>rule</code></th></tr></thead><tbody><tr><td><code>all</code></td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td></tr><tr><td><code>categories</code></td><td>-</td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td></tr><tr><td><code>child</code></td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td></tr><tr><td><code>classifications</code></td><td>+</td><td>-</td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td></tr><tr><td><code>custom</code></td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td></tr><tr><td><code>data_classes</code></td><td>-</td><td>+</td><td>-</td><td>+</td><td>+</td><td>+</td><td>+</td></tr><tr><td><code>data_location_rules</code></td><td>-</td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td></tr><tr><td><code>data_protection_rules</code></td><td>-</td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td></tr><tr><td><code>grouped_assets</code></td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>has_terms</code></td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>has_type_terms</code></td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>has_types_category</code></td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>has_types_classifications</code></td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>has_types_classifications_hierarchy</code></td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>has_types_data_class_hierarchy</code></td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>has_types_data_classes</code></td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>has_types_term_hierarchy</code></td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>is_a_parent_category_for</code></td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>is_a_type_of_category</code></td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>is_a_type_of_classification</code></td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>is_a_type_of_data_class</code></td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>is_a_type_of_terms</code></td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>is_of_terms</code></td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>multi_value_mappings</code></td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td></tr><tr><td><code>owned_by</code></td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>parent</code></td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td></tr><tr><td><code>parent_category</code></td><td>-</td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td></tr><tr><td><code>parent_hierarchy</code></td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td></tr><tr><td><code>parent_policy</code></td><td>-</td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td></tr><tr><td><code>policies</code></td><td>-</td><td>+</td><td>+</td><td>+</td><td>-</td><td>-</td><td>+</td></tr><tr><td><code>reference_data</code></td><td>-</td><td>+</td><td>+</td><td>+</td><td>-</td><td>-</td><td>+</td></tr><tr><td><code>reference_data_values</code></td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>related_categories</code></td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>related_terms</code></td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>replaced_by_terms</code></td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>replaces_terms</code></td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>rules</code></td><td>-</td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td><td>+</td></tr><tr><td><code>single_value_mappings</code></td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td></tr><tr><td><code>sub_policies</code></td><td>-</td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td></tr><tr><td><code>synonym_terms</code></td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td><td>-</td><td>-</td></tr><tr><td><code>terms</code></td><td>-</td><td>+</td><td>+</td><td>-</td><td>+</td><td>+</td><td>+</td></tr><tr><td><code>value_mappings</code></td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>+</td><td>-</td></tr></tbody></table>

include_custom_attributes

boolean

If this parameter is set to true, then all artifact custom attributes are returned. If parameter is not set its default value is 'false'.

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.<br>This parameter is ignored when artifact type is category.

all_parents

boolean

string

The trace id.

Changes the parent category of a published artifact with given id

POST /v3/governance_artifact_types/{artifact_type}/{artifact_id}/move

This method can be used to change given artifact parent. Or make it root-level, in case of category.<br>Note: change of collaborators access may take longer to complete

Request

Request Body

GlossaryV3MoveTargetCategory

Target category (to become a parent of this artifact)

target_category_id

Required *

string

specifies id of category to become parent after move. One can specify either artifact ID or global ID. In case of category, one can specify string `ROOT` to move it to the top level

Path Parameters

artifact_type

Required *

string

The artifact type. Allowed values are category, glossary_term, classification, data_class, reference_data, policy, rule

artifact_id

Required *

string

Artifact ID or global ID of the artifact

Query Parameters

skip_workflow_if_possible

boolean

string

The trace id.

Get development logs & Comments for a draft artifact version

GET /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/aggregated_logs

Get development logs & Comments for a draft artifact version

Request

The version id.

Query Parameters

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

time_zone_offset

string

Time zone offset based on which the day wise grouping is to be performed. The offset will be of format [+-]hh:mm where hh stands for hour digit and mm for minute digit. <br/>e.g. +05:30 indicates IST. If [+-] is not provided by default + will be appended. e.g 05:30 indicates +05:30. <br/>If hour digit is single like +h:mm provided, then it will be considered as +0h:mm. e.g. +5:30 indicates +05:30. <br/>The range of offsets is restricted to -17:59 to +17:59 inclusive.

Response

200 - Development logs & Comments retrieved successfully

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

GET /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/aggregated_logs/{mod_id}

Get development logs & Comments for a draft artifact version with development log id

Request

The development log id.

Query Parameters

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - Development logs & Comments retrieved successfully

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

string

The trace id.

Add a comment for a draft artifact version

POST /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/comments

Add a comment for a draft artifact version

Request

Request Body

The trace id.

Delete a comment on a draft artifact version

DELETE /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/comments/{comment_id}

Delete a comment on a draft artifact version

Request

The comment id.

Query Parameters

Response

The trace id.

Update a comment on a draft artifact version

PATCH /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/comments/{comment_id}

Update a comment on a draft artifact version

Request

Request Body

string

The comment id.

Query Parameters

The trace id.

Get development logs & Comments for a draft artifact version

GET /v3/governance_artifact_types/{artifact_type}/{artifact_id}/versions/{version_id}/logs

Get development logs & Comments for a draft artifact version

Request

The version id.

Query Parameters

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - Development logs & Comments retrieved successfully

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

skip_workflow_if_possible

boolean

If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Comma-separated list of relationship types.<br/><table><tbody><tr><td colspan="2">Available types:</td></tr><tr><td><code>parent_policy</code></td><td></td></tr><tr><td><code>sub_policies</code></td><td></td></tr><tr><td><code>parent_category</code></td><td></td></tr><tr><td><code>categories</code></td><td></td></tr><tr><td><code>terms</code></td><td></td></tr><tr><td><code>classifications</code></td><td></td></tr><tr><td><code>rules</code></td><td></td></tr><tr><td><code>data_location_rules</code></td><td></td></tr><tr><td><code>data_protection_rules</code></td><td></td></tr><tr><td><code>custom</code></td><td></td></tr><tr><td><code>all</code></td><td></td></tr></tbody></table>

include_custom_attributes

boolean

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

Response

200 - Success

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

DELETE /v3/policies/{artifact_id}/versions/{version_id}

Request

Path Parameters

artifact_id

Required *

string

The artifact ID of the policy.

version_id

Required *

string

The version id of the policy to delete or to create mark-for-delete draft copy.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Retrieves versions of a policy for the given artifact_id and status

GET /v3/policies/{artifact_id}/versions/{version_id}

Retrieval of the versions of ACTIVE state is supported.

Request

Path Parameters

artifact_id

Required *

string

The artifact ID of the policy to fetch.

version_id

Required *

string

The version ID of the policy to fetch.

Query Parameters

include_relationship

string

include_custom_attributes

boolean

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

Response

200 - The policy has been retrieved successfully.

entity

GlossaryV3ResponsePolicyEntity

Policy entity for GET response.

metadata

GlossaryV3GlossaryObjectMetadataV3

Metadata of the entity.

401 - Unauthorized

errors

array

List of errors.

trace

string

The trace id.

404 - The policy with given {guid} does not exist in the glossary.

errors

array

List of errors.

trace

string

The trace id.

500 - Internal Server Error

errors

array

List of errors.

trace

string

The trace id.

Updates policy with given artifact id and version id

PATCH /v3/policies/{artifact_id}/versions/{version_id}

Required *

array

Relationships to business terms.

Path Parameters

artifact_id

Required *

string

The artifact id of the policy to be updated.

version_id

Required *

string

The version id of the policy to be updated.

Query Parameters

skip_workflow_if_possible

boolean

string

The trace id.

Updates DPR rule relationships of a published policy using its artifact id and version id

PATCH /v3/policies/{artifact_id}/versions/{version_id}/data_protection_rules

Updates DPR rule relationships of a published policy using its artifact id and version id<br/>Deprecated, functionality will be replaced by new one introduced in the feature releases.

Request

Request Body

Path Parameters

artifact_id

Required *

string

The artifact id of the policy to be updated.

version_id

Required *

string

The version id of the policy to be updated.

Query Parameters

The trace id.

List the relationships for the specified policy

GET /v3/policies/{artifact_id}/versions/{version_id}/relationships

Request

Path Parameters

artifact_id

Required *

string

The guid of the Policy

version_id

Required *

string

The versionID of the Policy

Query Parameters

type

Required *

string

ca_definition_id

string

Custom relationship definition Id.

is_reversed

boolean

Is custom relationship reversed?

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

include_target_parent_category_name

boolean

Retrieves target parent category name of the relationship entity.

Response

200 - Success

custom_relationships

array

List of custom relationships

array

List of errors.

trace

string

The trace id.

Create relationships for an artifact in the glossary

POST /v3/policies/{artifact_id}/versions/{version_id}/relationships

artifact_id

Required *

string

The artifact ID of the term to fetch.

version_id

Required *

string

The version ID of the term to fetch.

Query Parameters

skip_workflow_if_possible

boolean

If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Deletes a relationship from a draft policy

DELETE /v3/policies/{artifact_id}/versions/{version_id}/relationships/{relationship_id}

Deletes a relationship from a draft policy

Request

The artifact ID of the relationship to be deleted.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Retrieves relationships for a given artifact type, artifact_id and artifact version_id

GET /v3/relationships

For a given artifact type, a set of predefined relationship attributes with associated artifacts are included for every relationship.

Request

Path Parameters

since

string

A filter to artifacts that have been created / updated / deleted since the given timestamp in this format: [yyyy-MM-ddTHH:mm:ss.SSSZ]

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - Success

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

string

The trace id.

Creates a rule in the glossary

POST /v3/rules

Required *

string

The name of the artifact.

parent_category

GlossaryV3NewRelationship

The parent category of the artifact.

id

string

Artifact id of the related artifact.

policies

array

The relationships to governance policies.

reference_copy

boolean

Indicates that it is a reference copy of an artifact managed in an external metadata server.

reference_data

array

The relationships to reference data sets.

rule_type

Required *

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Comma-separated list of relationship types.<br/><table><tbody><tr><td colspan="2">Available types:</td></tr><tr><td><code>parent_category</code></td><td></td></tr><tr><td><code>categories</code></td><td></td></tr><tr><td><code>terms</code></td><td></td></tr><tr><td><code>rules</code></td><td></td></tr><tr><td><code>reference_data</code></td><td></td></tr><tr><td><code>policies</code></td><td></td></tr><tr><td><code>classifications</code></td><td></td></tr><tr><td><code>data_classes</code></td><td></td></tr><tr><td><code>custom</code></td><td></td></tr><tr><td><code>all</code></td><td></td></tr></tbody></table>

include_custom_attributes

boolean

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - The rule has been retrieved successfully.

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

DELETE /v3/rules/{artifact_id}/versions/{version_id}

Request

Path Parameters

artifact_id

Required *

string

The artifact id of the rule to delete.

version_id

Required *

string

The version id of the rule to delete.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

201 - A draft version has been successfully created for deleting the published artifact.

resources

array

string

The trace id.

Retrieves rule with given guid

GET /v3/rules/{artifact_id}/versions/{version_id}

This method can be used for retrieving details of an PUBLISHED or DRAFT rule.

Request

Path Parameters

artifact_id

Required *

string

The artifact ID of the rule to fetch.

version_id

Required *

string

The version ID of the rule to fetch.

Query Parameters

include_relationship

string

include_custom_attributes

boolean

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

Response

200 - The rule has been retrieved successfully.

entity

GlossaryV3ResponseRuleEntity

Represents a rule entity returned by REST GET methods that include the relationships as paginated lists

metadata

GlossaryV3GlossaryObjectMetadataV3

Metadata of the entity.

401 - Unauthorized

errors

array

List of errors.

trace

string

The trace id.

404 - The rule with given {guid} does not exist in the glossary.

errors

array

List of errors.

trace

string

The trace id.

500 - Internal Server Error

errors

array

List of errors.

trace

string

The trace id.

Updates rule with given id

PATCH /v3/rules/{artifact_id}/versions/{version_id}

array

The relationships to reference data sets.

revision

Required *

artifact_id

Required *

string

The artifact id of the rule to be updated.

version_id

Required *

string

The version id of the rule to be updated.

Query Parameters

skip_workflow_if_possible

boolean

string

The trace id.

List the relationships of the given type for the specified rule

GET /v3/rules/{artifact_id}/versions/{version_id}/relationships

Request

Path Parameters

artifact_id

Required *

string

The artifact ID of the rule to fetch.

version_id

Required *

string

The version ID of the rule to fetch.

Query Parameters

type

Required *

string

ca_definition_id

string

Custom relationship definition Id.

is_reversed

boolean

Is custom relationship reversed?

all_parents

boolean

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

include_target_parent_category_name

boolean

Retrieves target parent category name of the relationship entity.

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

Index of the beginning of the page. The offset value can be 0 (zero) or a multiple of limit value.

Response

200 - Success

custom_relationships

array

List of custom relationships

array

List of errors.

trace

string

The trace id.

Create relationships for an artifact in the glossary

POST /v3/rules/{artifact_id}/versions/{version_id}/relationships

array

The list of related business terms

Path Parameters

artifact_id

Required *

string

The artifact ID of the rule to fetch.

version_id

Required *

string

The version ID of the rule to fetch.

Query Parameters

skip_workflow_if_possible

boolean

If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

Deletes a relationship of a rule artifact

DELETE /v3/rules/{artifact_id}/versions/{version_id}/relationships/{relationship_id}

This method can be used for deleting a relationship of a rule artifact.

Request

The artifact ID of the relationship to be deleted.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

Type

Path Parameters

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.

Response

List of errors.

trace

string

The trace id.

If this parameter is set, then all ancestors in the hierarchy are returned. You can use this parameter to build complete ancestor path.

Response

200 - The reference data set has been retrieved successfully.

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

DELETE /v4/reference_data_sets/{artifact_id}/versions/{version_id}

Delete the reference data set with a given artifact_id and version_id. If the artifact is published then a workflow will be started with a draft created with label marked for deletion which on approval will result in a actual delete. If the artifact is a draft copy then the draft copy will be deleted from the system.

Request

Path Parameters

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

The version id of the reference data set or specify ACTIVE (it represents a current active published version) or PUBLISHED (it represents a published version that is active now or will be active in the future).

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

move_child_to

string

Specify new reference data parent artifact_id for children of reference data that is to be removed. If move_child_to is not set all reference data children become root objects.

Response

List of errors.

trace

string

The trace id.

Retrieve a reference data set with given artifact_id and version_id

GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}

This method will retrieve details of the specified reference data set.

Request

200 - The reference data set has been retrieved successfully.

entity

GlossaryV3ResponseReferenceDataSetEntityV4

Reference Data Set entity returned by V4 REST GET method that includes the relationships as paginated list.

metadata

GlossaryV3GlossaryObjectMetadataV3

Metadata of the entity.

401 - Unauthorized

errors

array

List of errors.

trace

string

The trace id.

404 - The reference data set with given {guid} does not exist.

errors

array

List of errors.

trace

string

The trace id.

500 - Internal Server Error

errors

array

List of errors.

trace

string

The trace id.

Update a reference data set with given artifact id and version id

PATCH /v4/reference_data_sets/{artifact_id}/versions/{version_id}

Required *

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

Query Parameters

skip_workflow_if_possible

boolean

string

The trace id.

Create Custom Column definitions

POST /v4/reference_data_sets/{artifact_id}/versions/{version_id}/custom_columns

Create Custom Column definitions<br> <ul> <li>Allowed Custom Column definitions types: <code>NUMBER, TEXT, DATE</code>.</li> <li>If a column is a composite key, it must be mandatory.</li> <li> For <code>NUMBER</code> and <code>TEXT</code> types the default values for <code>max_characters_count</code>: <ul> <li>for a composite key column: 200,</li> <li>for a normal column: 2000.</li> </ul> <li><code>validator_rds_id</code> must be an artifact id of a published RDS.</li> </ul>

Request

Request Body

GlossaryV3RDSCustomColumnsCreateRequest

columns

array

List of custom column Definitions.

Path Parameters

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

Query Parameters

Response

List of errors.

trace

string

The trace id.

Delete a Custom Column definition by column_id

DELETE /v4/reference_data_sets/{artifact_id}/versions/{version_id}/custom_columns/{column_id}

Delete a Custom Column definition by column_id

Request

Query Parameters

Response

The trace id.

Retrieve a Custom Column definition with given column_id

GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/custom_columns/{column_id}

Retrieve a Custom Column definition with given column_id

Request

Query Parameters

Response

200 - Custom Column definition with given column_id has been retrieved successfully.

entity

GlossaryV3RDSCustomColumnResponse

List of composite key members

metadata

GlossaryV3RDSCustomColumnsGetMetaData

metadata of cust columns.

401 - Unauthorized

errors

array

List of errors.

trace

string

The trace id.

404 - The Custom Column definition with given {column_id} does not exist.

errors

array

List of errors.

trace

string

The trace id.

500 - Internal Server Error

errors

array

List of errors.

trace

string

The trace id.

Update Custom Column properties with given column_id

PATCH /v4/reference_data_sets/{artifact_id}/versions/{version_id}/custom_columns/{column_id}

Update Custom Column properties with given column_id<br>To remove RDS validator please specify: <code>"validator_rds_id": null</code>. <br>To remove description please specify: <code>"description": null</code>.

Request

Request Body

GlossaryV3RDSCustomColumnUpdatableEntity

Custom Column properties to be updated.<br/>Properties <code>mandatory</code>, <code>max_character_count</code> and <code>validator_rds_id</code> can be changed only when owner (reference data) has no values assigned yet.

description

string

description

mandatory

boolean

Determinate if it is mandatory

max_character_count

integer

Allowed maximum character count

name

Required *

string

name

revision

Required *

string

The revision of the artifact. It is used for optimistic locking.

type

string

Type

Response

The trace id.

List the relationships of the given type for the specified reference data set

GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/relationships

Request

Response

200 - Success

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

string

The trace id.

Associate Reference data set identified by artifact_id and version_id with other governance artifacts

POST /v4/reference_data_sets/{artifact_id}/versions/{version_id}/relationships

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

Query Parameters

skip_workflow_if_possible

boolean

If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.

Response

The trace id.

Delete the relationship associated to reference data set with specified artifact_id and version_id

DELETE /v4/reference_data_sets/{artifact_id}/versions/{version_id}/relationships/{relationship_id}

Delete the relationship associated to reference data set with specified artifact_id and version_id

Request

Path Parameters

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

relationship_id

Required *

string

The artifact ID of the relationship to be deleted.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

The trace id.

Import reference data values from csv file to the reference data set with specified artifact_id and version_id

POST /v4/reference_data_sets/{artifact_id}/versions/{version_id}/value_imports

Import reference data values from csv file to the reference data set with specified artifact_id and version_id<br>To check the current status of the import please use the endpoint <code>GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/value_imports/{import_id}</code>.

Request

Request Body

Input data for reference data value import: import file and parameters.

Path Parameters

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

Query Parameters

Response

Request

Query Parameters

Response

The trace id.

Get current state of reference data values import process with specified import_id

GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/value_imports/{import_id}

Get current state of reference data values import process with specified import_id

Request

Query Parameters

Response

Request

Request Body

GlossaryV3ReferenceDataValuesRelationshipsRequestV4

value_relationships

array

Reference Data Values Relationships

Path Parameters

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.

Response

The trace id.

Retrieve a reference data value relationships with given reference data set artifact_id and version_id and reference data value artifact_id

GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/value_relationships/{rdv_artifact_id}

Retrieve a reference data value relationships with given reference data set artifact_id and version_id and reference data value artifact_id

Request

Path Parameters

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

rdv_artifact_id

Required *

string

The artifact id of reference data value.

Query Parameters

type

Required *

string

Only one relationship type can be selected.<br/><table><tbody><tr><td colspan="2">Available types:</td></tr><tr><td><code>terms</code></td><td></td></tr><tr><td><code>parent_hierarchy</code></td><td></td></tr><tr><td><code>child</code></td><td></td></tr><tr><td><code>single_value_mappings</code></td><td></td></tr><tr><td><code>multi_value_mappings</code></td><td></td></tr><tr><td><code>value_mappings</code></td><td></td></tr></tbody></table>

limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

The index of the first matching relationship to include in the result.

Response

Reference data value search filter value

include_custom_column_values

boolean

Fetch custom column values for reference data set values.

include_parent_value_details

boolean

Fetch parent reference data details for reference data set values.

include_relationship

string

Comma-separated list of relationship types for reference data value.<br/>

limit

integer

The maximum number of values to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

The index of the first matching value to include in the result.

relationship_limit

integer

The maximum number of relationships to return - must be at least 1 and cannot exceed 200. The default value is 10.

Response

200 - The reference data value(s) details have been retrieved successfully.

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

string

The trace id.

Retrieve reference data value(s) details with given RDS artifact_id and version_id and for specific reference data value artifact_ids

GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values

Retrieve reference data value(s) details with given RDS artifact_id and version_id and for specific reference data value artifact_ids

Request

include_relationship

string

Comma-separated list of relationship types for reference data value.<br/><table><tbody><tr><td colspan="2">Available types:</td></tr><tr><td><code>terms</code></td><td></td></tr><tr><td><code>parent_hierarchy</code></td><td></td></tr><tr><td><code>child</code></td><td></td></tr><tr><td><code>single_value_mappings</code></td><td></td></tr><tr><td><code>multi_value_mappings</code></td><td></td></tr><tr><td><code>value_mappings</code></td><td></td></tr></tbody></table>

include_parent_value_details

boolean

Fetch parent reference data details for reference data set values.

include_custom_column_values

boolean

Fetch custom column values for reference data set values.

roots_only

boolean

Fetch root values (values with no parent assigned) for reference data set.

limit

integer

The maximum number of hierarchy children to return - must be at least 1 and cannot exceed 200. The default value is 10.

offset

integer

The index of the first matching hierarchy children to include in the result.

relationship_limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

sort

string

Value on which results need to be sorted, currently only CODE is supported.Prefix hyphen (-) for descending order, applicable only for reference data values search.

Response

200 - The reference data value(s) details have been retrieved successfully.

count

integer

The total number of items that matches the given criteria.

first

GlossaryV3GlossaryResourceLinkV3

Represents an html link.

last

GlossaryV3GlossaryResourceLinkV3

string

The trace id.

Remove or update reference data values for the specified reference data set

PATCH /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values

Remove or update reference data values for the specified reference data set

Request

Request Body

Valid Json-patch body with either delete or replace operations.<br>Note: Precision will be lost if long value has more than 15-16 digits as JSON parser will map to double type regardless of whether it is used for integer, long or floating-point numbers. To Preserve all digits pass the value as a string.

Path Parameters

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

Query Parameters

Response

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

Query Parameters

skip_workflow_if_possible

boolean

If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.

Response

The trace id.

Add or update reference data values for the specified reference data set

PUT /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values

Add or update reference data values for the specified reference data set

Request

Request Body

GlossaryV3CreateUpdateReferenceDataValuesListV4

values

array

Reference data values

Path Parameters

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

Query Parameters

skip_workflow_if_possible

boolean

If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.

Response

The version ID of the artifact

workflow_id

string

The trace id.

Exports values of a specified reference data set with specified artifact_id and version_id to a csv file

GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values/export

Exports values of a specified reference data set with specified artifact_id and version_id to a csv file<br>Only Code, Value and Composite Key columns will be exported by default, use parameters to export additional properties.

Request

Path Parameters

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

Query Parameters

composite_key_only

boolean

Export reference data values code and composite key only. Note: If composite key is not defined, only code will be exported.

include_description

boolean

Export reference data value description.

include_custom_column_def_artifact_ids

string

Comma-separated list of custom column definition artifact ids. Use <code>all</code> to export all custom column definition values.

include_parent_value

boolean

Export reference data value parent.

include_relationship

string

include_physical_key

boolean

Export additional column representing reference data physical key (code + composite key values), columns are delimited with '|'.

Response

The trace id.

Delete the reference data value identified by its artifact id in the Reference Data Set with specified artifact_id and version_id

DELETE /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values/{rdv_artifact_id}

Delete the reference data value identified by its artifact id in the Reference Data Set with specified artifact_id and version_id. If the reference data set is published then a workflow will be started with a draft created from which the value will be deleted. If the artifact is a draft copy then the value from the draft copy will be removed.

Request

target_value_artifact_id

string

Target reference data value (to become parent for children of deleted one) artifact id (note: it has to "belong" to same reference data set as deleted value

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

The trace id.

Retrieve reference data value(s) details with given RDS artifact_id and version_id and for specific reference data value artifact_ids

GET /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values/{rdv_artifact_id}

Retrieve reference data value(s) details with given RDS artifact_id and version_id and for specific reference data value artifact_ids

Request

Path Parameters

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

rdv_artifact_id

Required *

string

The artifact id of reference data value.

Query Parameters

include_custom_column_values

boolean

Fetch custom column values for reference data set values.

include_relationship

string

include_parent_value_details

boolean

Fetch parent reference data details for reference data set values.

relationship_limit

integer

The maximum number of relationship to return - must be at least 1 and cannot exceed 200. The default value is 10.

Response

string

The artifact id of the reference data set.

version_id

Required *

string

rdv_artifact_id

Required *

string

The artifact id of reference data value.

Query Parameters

skip_workflow_if_possible

boolean

If configuration permits, the published artifact will be updated by skipping the workflow. For details refer to documentation.

Response

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

rdv_artifact_id

Required *

string

The artifact id of reference data value.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the artifact will be created in the published state by skipping the workflow. For details refer to documentation.

Response

The trace id.

Delete the relationship associated to reference data value identified by its artifact id in the Reference Data Set with specified artifact_id and version_id

DELETE /v4/reference_data_sets/{artifact_id}/versions/{version_id}/values/{rdv_artifact_id}/value_relationships/{relationship_id}

Delete the relationship associated to reference data value identified by its artifact id in the Reference Data Set with specified artifact_id and version_id

Request

Path Parameters

artifact_id

Required *

string

The artifact id of the reference data set.

version_id

Required *

string

rdv_artifact_id

Required *

string

The artifact id of reference data value.

relationship_id

Required *

string

The artifact ID of the relationship to be deleted.

Query Parameters

skip_workflow_if_possible

boolean

If workflow template configuration permits, the published artifact will be deleted by skipping the workflow. For details refer to documentation.

Response

The trace id.

Get list of jobs under a project or a space.

GET /v2/jobs

Lists the jobs in the specified project or space (either project_id or space_id must be set).

Request

Path Parameters

The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.

string

The optional 'next' field from the response in string format, can be used to get the next batch. The response can contain up to 200 results in a batch, if there are more results, a 'next' field is returned in the response which can be used to get the next batch.

Response

200 - Success.

JobsAssetSearchNext

total_rows

integer

results

more_info

string

default - An error occurred. See response for more information.

Create a new job.

POST /v2/jobs

Creates a new job in the specified project or space (either project_id or space_id must be set).

Request

Request Body

JobsJobPostBody

The job to be created. Note: either asset_ref or asset_ref_type must be provided, not both.

job

object

asset_ref

string

ID of associated asset to run (provide either asset_ref or asset_ref_type).

asset_ref_type

string

The type of asset to run (provide either asset_ref or asset_ref_type).

name

Required *

string

The name of the job

description

string

space_id

string

The ID of the space to use. project_id or space_id is required.

Response

200 - Success.

metadata

JobsAssetMetadata

AssetMetadata Model

entity

more_info

string

default - An error occurred. See response for more information.

Delete a specific job.

DELETE /v2/jobs/{job_id}

Deletes a specific job in a project or space (either project_id or space_id must be set). If the deletion of the job and its runs will take some time to finish, then a 202 response will be returned and the deletion will continue asynchronously. All the jobs runs associated with the job will also be deleted. If the job is still running, it will not be deleted.

Request

Path Parameters

job_id

Required *

Update information of a job.

PATCH /v2/jobs/{job_id}

Updates specific attributes of a job in the specified project or space (either project_id or space_id must be set). You must specify the updates by using the JSON patch format, described in RFC 6902.

Request

Request Body

JobsJSONJobPatchModel

Updates to make to the job run.

Path Parameters

job_id

Required *

string

The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.

Query Parameters

project_id

string

The ID of the project to use. project_id or space_id is required.

space_id

string

The ID of the space to use. project_id or space_id is required.

Response

200 - Success.

metadata

JobsAssetMetadata

AssetMetadata Model

entity

more_info

string

default - An error occurred. See response for more information.

Get the availability of a given serving_name

GET /v2/jobs/serving_name/{serving_name}

Gets the availability of a given serving_name, as serving_name must be globally unique. serving_name must be a combination of alphanumeric and underscore characters, and must be between 1 and 36 characters.

Request

Path Parameters

serving_name

Required *

string

The serving_name value of the job to be used in place of the job ID.

Query Parameters

Response

200 - Success.

results

array

400 - Bad request. See the error message for details.

code

string

target

ErrorTargetModel

message

string

more_info

string

401 - You are not authorized to access the service. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

default - An error occurred. See response for more information.

Get list of runs of a job.

GET /v2/jobs/{job_id}/runs

Lists the job runs for a specific job in the specified project or space (either project_id or space_id must be set). Only the metadata and certain elements of the entity component of each run are returned.

Request

Path Parameters

job_id

Required *

The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.

states

array

A list of comma-separated job run states. Availble values: Completed, Failed, Canceled, Starting, Running, Queued, Canceling, Paused, Resuming, CompletedWithWarnings, CompletedWithErrors

Response

200 - Success.

JobsAssetSearchNext

total_rows

integer

results

array

Array of all jobs.

401 - You are not authorized to access the service. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

403 - You are not permitted to perform this action. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

default - An error occurred. See response for more information.

Start a run for a job.

POST /v2/jobs/{job_id}/runs

Starts the specified job contained in a project or space (either project_id or space_id must be set).

Request

Request Body

JobsJobRunPostBody

The configuration of the job run to use. If not provided, use the configuration of the associated job.

job_run

Required *

object

name

string

The name of the job run

description

string

The description of the job run

configuration

object

job_parameters

array

Array of job parameters.

parameter_sets

array

Array of parameter sets.

Path Parameters

job_id

Required *

string

The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.

Query Parameters

project_id

string

The ID of the project to use. project_id or space_id is required.

space_id

string

The ID of the space to use. project_id or space_id is required.

Response

201 - The requested operation completed successfully.

metadata

JobsAssetJobRunMetadata

AssetJobRunMetadata Model

entity

JobsJobRunEntity

401 - You are not authorized to access the service. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

403 - You are not permitted to perform this action. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

Query Parameters

project_id

string

The ID of the project to use. project_id or space_id is required.

space_id

string

The ID of the space to use. project_id or space_id is required.

Response

200 - Success.

metadata

JobsAssetJobRunMetadata

AssetJobRunMetadata Model

entity

JobsJobRunEntity

401 - You are not authorized to access the service. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

403 - You are not permitted to perform this action. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

Query Parameters

project_id

string

The ID of the project to use. project_id or space_id is required.

space_id

string

The ID of the space to use. project_id or space_id is required.

limit

integer

The limit of the number of lines to return, for example limit=50. If not specified, all log will be returned.

Response

200 - Success.

results

array

Array of log string split by line

total_count

integer

Total number of lines available

401 - You are not authorized to access the service. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

403 - You are not permitted to perform this action. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

default - An error occurred. See response for more information.

Cancel a run.

POST /v2/jobs/{job_id}/runs/{run_id}/cancel

Cancels a job run that is in the running state.

Request

Request Body

An empty body.

Path Parameters

job_id

Required *

string

The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.

run_id

Required *

string

The ID of the job run.

Query Parameters

project_id

string

The ID of the project to use. project_id or space_id is required.

space_id

string

The ID of the space to use. project_id or space_id is required.

Response

204 - The requested operation completed successfully.

401 - You are not authorized to access the service. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

403 - You are not permitted to perform this action. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

default - An error occurred. See response for more information.

Pause a run.

POST /v2/jobs/{job_id}/runs/{run_id}/pause

Pauses a job run that is in the running state.

Request

Request Body

An empty body.

Path Parameters

job_id

Required *

string

The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.

run_id

Required *

string

The ID of the job run.

Query Parameters

project_id

string

The ID of the project to use. project_id or space_id is required.

space_id

string

The ID of the space to use. project_id or space_id is required.

Response

204 - The requested operation completed successfully.

401 - You are not authorized to access the service. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

403 - You are not permitted to perform this action. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

default - An error occurred. See response for more information.

Resume a run.

POST /v2/jobs/{job_id}/runs/{run_id}/resume

Resumes a job run that is in the paused state.

Request

Request Body

An empty body.

Path Parameters

job_id

Required *

string

The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.

run_id

Required *

string

The ID of the job run.

Query Parameters

project_id

string

The ID of the project to use. project_id or space_id is required.

space_id

string

The ID of the space to use. project_id or space_id is required.

Response

204 - The requested operation completed successfully.

401 - You are not authorized to access the service. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

403 - You are not permitted to perform this action. See response for more information.

code

string

target

ErrorTargetModel

message

string

more_info

string

default - An error occurred. See response for more information.

Copy Knowledge Accelerator items into project

POST /v1/knowledge_accelerators/{ka_id}/copy_items

Copy the specified Knowledge Accelerator items into specified IKC project.

Request

Path Parameters

ka_id

Required *

200 - Success

message

string

A summary message of the copy status

knowledge_accelerator

string

The Knowledge Accelerator URI of the items to be copied

items

errors

array

Get a specific Knowledge Accelerator

GET /v1/knowledge_accelerators/{id}

Supply a Knowledge Accelerator id, in order to get detailed information, including contained items that can be imported, statistics and dependencies

Request

Path Parameters

id

Required *

string

The Knowledge Accelerator id

Query Parameters

Response

If an item depends on one or more items within the same knowledge accelerator, this holds those item ids

derived_from

array

If an item is derived from one or more items within the same knowledge accelerator, this holds those item ids

401 - Unauthorized

trace

string

errors

array

404 - Not found

trace

string

errors

array

Import specified Knowledge Accelerator items into the glossary

POST /v1/knowledge_accelerators/{ka_id}/import_items

Import the specified Knowledge Accelerator items into glossary. By default this will import all dependent items

Request

Path Parameters

ka_id

Required *

A URI for checking the status of the import process

import_evaluation

errors

array

Get what Knowledge Accelerator items are currently imported into glossary

GET /v1/knowledge_accelerators/import_items

Information on what Knowledge Accelerator items are imported into glossary if any; this will include information as to whether imported version is current

Request

Response

200 - Success

message

string

A summary message of the import status

import_evaluation

array

An import evaluation for a specific Knowledge Accelerator.

401 - Unauthorized

trace

string

errors

array

Get all Knowledge Accelerators

GET /v1/knowledge_accelerators

Detailed information on each Knowledge Accelerator, including contained items that can be imported, statistics and dependencies

Request

Response

200 - Success

count

integer

A count of the Knowledge Accelerators that are available

knowledge_accelerators

array

A listing of the Knowledge Accelerators and their contained items that are available for importing into the IKC glossary

401 - Unauthorized

trace

string

errors

array

Get asset lineage

GET /asset_lineages/{asset_id}

Returns lineage of the asset identified by asset_id. The lineage includes a list of events associated with the asset. A different list of events are returned based on the value of lineage_type query parameter.

lineage_type = default | partial - The event generating the asset, the events happening on the asset and the events using the asset to generate other assets.
lineage_type = forward - The event generating the asset and the events using the asset directly or indirectly to generate other assets.
lineage_type = forward_hop - The event generating the asset and the events using the asset directly or indirectly to generate other assets. The number of events returned is controlled by hop_count and event_count parameters.
lineage_type = backward - All the direct and indirect events responsible for generating the asset.

Request

Path Parameters

asset_id

Required *

string

string

If the asset is a model, specify the ID of the associated WML service instance. If the seed asset ID is supplied, then the value supplied should be the WML service instance ID of the seed asset.

asset_type

Required *

string

The type of the asset. The value can be one of dataset, model. If the seed asset ID is supplied, then the value supplied should be the type of the seed asset.

event_time

string

The time after which the events have to be fetched. The format should be yyyy-MM-dd'T'HH:mm:ss.SSSX. The default value is 1970-01-01T00:00:00.000Z.

hop_count

integer

Used to control the number of events returned when lineage_type is forward_hop. The events returned will belong to a maximum of N other assets directly or indirectly generated using the asset where N is equal to hop_count. The default value is 4.

event_count

integer

Used to control the number of events returned when lineage_type is forward_hop. The maxiumum number of events of each other asset generated directly or indirectly using the asset. The default value is 10.

seed_asset_id

string

The seed asset ID. The request will not be authorized if the lineage of the asset is not part of the lineage of the seed asset.

Response

200 - OK

limit

integer

offset

integer

first

LineagePaginatedResponseLink

resources

If the asset is a project-asset, specify the ID of the project.

space_id

string

If the asset is a space-asset, specify the ID of the space.

wml_instance_id

string

If the asset is a model, specify the ID of the associated WML service instance.

asset_type

Required *

string

The type of the asset. The value can be one of dataset, model.

Response

200 - OK

metadata

LineageLineageSummaryMetadata

The metadata of the lineage summary.

entity

errors

array

Returns the event identified by event_id.

GET /lineage_events/{event_id}

Get lineage event

Request

Path Parameters

event_id

Required *

string

Event ID

Query Parameters

Response

Publishes lineage event.

POST /lineage_events

Publish lineage event

Request

If the asset is a project-asset, specify the ID of the project.

space_id

string

If the asset is a space-asset, specify the ID of the space

request_type

Required *

string

The type of the request. The value can be one of edits, downloads, publish_to_catalog or clone_to_project.

Response

200 - OK

count

integer

Gives the statistics i.e number of requests (edits, downloads, etc

request

errors

array

Create a new notebook.

POST /v2/notebooks

Create a new notebook

either from scratch
or by copying another notebook.

To create a notebook from scratch, you need to first upload the notebook content(`ipynb` format) to the project Cloud Object Storage (COS) and then reference it with the attribute `file_reference`. The other required attributes are `name`, `project` and `runtime`. The attribute `runtime` is used to specify the environment on which the notebook runs.

To copy a notebook, you only need to provide `name` and `source_guid` in the request body.

Request

Request Body

Specification of the notebook to be created.

Response

201 -

400 -

401 -

403 -

429 -

Retrieve the details of a large number of notebooks inside a project.

POST /v2/notebooks/list

Retrieve the details of a large number of notebooks inside a project.

Request

Request Body

NotebooksNotebookListBody

notebooks

array

The list of notebooks whose details will be retrieved.

Path Parameters

Query Parameters

project_id

Required *

string

The guid of the project.

include

Required *

string

Additional info that will be included into the notebook details. Possible values are:

runtime

Response

200 -

400 -

401 -

403 -

Delete a particular notebook, including the notebook asset.

DELETE /v2/notebooks/{notebook_guid}

Delete a particular notebook, including the notebook asset.

Request

Path Parameters

notebook_guid

Required *

string

The guid of the notebook.

Query Parameters

Response

204 - Successful request. Notebook is deleted.

400 -

401 -

403 -

Revert the main notebook to a version.

PUT /v2/notebooks/{notebook_guid}

Revert the main notebook to a version.

Request

Request Body

NotebooksNotebookRevertBody

source

Required *

string

The guid of the notebook version.

Path Parameters

notebook_guid

Required *

string

The guid of the main notebook.

Query Parameters

Response

200 -

400 -

401 -

403 -

array

Path Parameters

governance_type_name

Required *

string

the name of the governance type

Query Parameters

Response

200 - OK

metadata

PoliciesV3PolicyResourceNonpersistentMetadata

metadata object for policy API responses that have no metadata

entity

PoliciesV3PolicyGovernanceTypeResponseEntity

Response

200 - OK

resources

array

Request Body

PoliciesV3LHSTermRequest

LHS RuleTerm JSON

name

Required *

string

Name of the custom LHS.

display_name

Required *

string

Display name of the custom LHS.

description

string

Description of the custom LHS.

property_name

Required *

string

Property name of the LHS references. For Asset properties, use the path of the property in asset json. For user property, use the name of the mapped User SCIM attribute. (Custom user predicates are not supported in CPDaaS).

source

Required *

string

Source for the LHS reference. For custom asset predicate, use 'ASSET'. For custom user predicate use 'CONTEXTUAL' (Custom user predicates are not supported in CPDaaS).

Response

200 - OK

metadata

PoliciesV3PolicyResourceMetadata

metadata object used in responses returned from policy management related APIs

entity

PoliciesV3UDPTermResponseEntity

Path Parameters

lhsTermId

Required *

string

ID of the LHS term to get

Query Parameters

Response

200 - OK

metadata

PoliciesV3PolicyResourceMetadata

metadata object used in responses returned from policy management related APIs

entity

PoliciesV3UDPTermResponseEntity

Path Parameters

lhsTermId

Required *

string

ID of the custom LHS to delete

Query Parameters

Response

204 - No Content (OK)

GET /v3/enforcement/policy_metrics/analysis/3d

This API retrieves policy enforcement metrics based on query parameters, which include metric type, date range, policy, user, rule, governanceType, outcome, host type, cached, context operation, context location, asset type and asset location. It then sums these metrics according to a specified aggregation type.

Request

Path Parameters

sort

string

The order to sort the metrics. The following values are allowed:

aggregate, -aggregate -- ascending or descending order by the aggregate
count, -count -- ascending or descending order by enforcement count

Response

200 - OK

metadata

PoliciesV3PolicyResourceNonpersistentMetadata

metadata object for policy API responses that have no metadata

entity

errors

array

GET /v3/enforcement/policy_metrics

Request

Path Parameters

sort

string

The order to sort the metrics. The following values are allowed:

aggregate, -aggregate -- ascending or descending order by the aggregate
count, -count -- ascending or descending order by enforcement count

Response

200 - OK

metadata

PoliciesV3PolicyResourceNonpersistentMetadata

metadata object for policy API responses that have no metadata

entity

errors

array

list all roles in policy engine.

GET /v3/enforcement/roles

Lists all roles of the policy engine.

Request

Response

200 - OK

resources

array

Request Body

PoliciesV3PolicyRolePermissionRequest

Role Permission Request json

name

Required *

string

the displayed name for the role

description

string

a more detailed description of the role

permissions

array

An array of permissions that this role includes

Response

201 - Created

entity

PoliciesV3PolicyRoleResponseEntity

Path Parameters

role_id

Required *

string

role ID

Query Parameters

Response

200 - OK

entity

errors

array

update a custom category role

PUT /v3/enforcement/roles/{role_id}

Updates a custom category role. This API is also used to add and remove permissions from the custom category role. The permissions should be passed as an array of string that has permissions ids.Maximum length allowed for 'name' parameter: 80 characters, maximum length allowed for 'description' parameter: 1000 characters. If the parameter 'name' is modified, allowed characters for the 'name' parameter: letters from any language, numbers in any script, space, dot, underscore, hyphen. Strings with characters other than these are rejected (only for the name parameter).

Request

Request Body

PoliciesV3PolicyRolePermissionRequest

role json

name

Required *

string

the displayed name for the role

description

string

a more detailed description of the role

permissions

array

An array of permissions that this role includes

Path Parameters

role_id

Required *

string

role ID

Query Parameters

Response

200 - OK

entity

errors

array

delete a custom category role

DELETE /v3/enforcement/roles/{role_id}

Deletes a cusotm category role.

Request

Path Parameters

role_id

Required *

string

role ID

Query Parameters

Response

204 - No Content (OK)

list all permissions in policy engine.

GET /v3/enforcement/roles/permissions

Lists all permissions of the policy engine.

Request

Response

200 - OK

resources

array

Path Parameters

rule_id

Required *

string

Rule ID

Query Parameters

Response

200 - OK

metadata

PoliciesV3PolicyResourceMetadata

metadata object used in responses returned from policy management related APIs

entity

errors

array

retrieve a rule

GET /v3/enforcement/rules/{rule_id}

Retrieves detailed information on a rule given the rule's identifier.

Request

Path Parameters

rule_id

Required *

string

Rule ID

Query Parameters

Response

200 - OK

metadata

PoliciesV3PolicyResourceMetadata

metadata object used in responses returned from policy management related APIs

entity

errors

PoliciesV3Expression

nested arrays representing an expression that is evaluated to determine if the action on the rule should be performed or enforced. See the description on the POST /v3/enforcement/rules for more details.

conditions

array

action

Required *

PoliciesV3Action

the action to perform or enforce when the rule triggers

name

string

parameters

array

subaction

object

the action to perform or enforce when the rule triggers

roLTransform

boolean

state

string

the state of the rule. Only the rules of policies in active are enforced.

Path Parameters

rule_id

Required *

string

Rule ID

Query Parameters

Response

200 - OK

metadata

PoliciesV3PolicyResourceMetadata

metadata object used in responses returned from policy management related APIs

entity

errors

array

delete a rule

DELETE /v3/enforcement/rules/{rule_id}

Deletes a rule. A rule can only be deleted if it is not currently associated with any policy (in any state).

Request

Path Parameters

rule_id

Required *

string

Rule ID

Query Parameters

Response

204 - No Content (OK)

list all rules

GET /v3/enforcement/rules

Lists all defined rules. This includes all rules associated with policies and rules not associated with any policy. When more than one filter criteria is specified, the resulting collection satisfies all the criteria.

Request

Path Parameters

If speficied, only rules with the matching governance type/types will be returned.

sort

string

The order to sort the rules. The following values are allowed:

name, -name -- ascending or descending order by the name
modified_date, -modified_date -- ascending or descending order by modified date

limit

string

The maximum number of Rules to return. The default value is 50.

offset

string

The index of the first matching Rule to include in the result. The default value is 0.

Response

200 - OK

array

create a rule

POST /v3/enforcement/rules

Creates a rule. A rule has two key properties:

a trigger defining when the rule should be enforced, and
an action describing what operations to perform or outcome to enforce.

<b>Trigger</b>

A trigger is a boolean expression represented using nested arrays. The following describes the syntax:

 Expression: 
 [ -conditions- ] 
 
 Conditions: 
 -predicate- 
 &quot;NOT&quot;, -predicate- 
 -predicate-, &quot;AND&quot;|&quot;OR&quot;, -conditions- 
 &quot;NOT&quot;, -predicate-, &quot;AND&quot;|&quot;OR&quot;, -conditions- 
 
 Predicate: 
 [ &quot;$-term-&quot;, &quot;EXISTS&quot; ] 
 [ &quot;$-term-&quot;, &quot;EQUALS&quot;|&quot;LESS_THAN&quot;|&quot;GREATER_THAN&quot;|&quot;CONTAINS&quot;, &quot;#-literal-&quot;|&quot;$-term-&quot; ] 
 -expression-

where:

-term- is a technical term defined in the term glossary.
-literal- is a literal. For numerics a string representation of the number should be specified. For times, milliseconds are used (from Unix epoch). For boolean, #true and #false are used.

The definition of the operators in a predicate:

EXISTS -- means that the term has a value of some kind.
EQUALS -- evaluates to true if the left and right sides are equal.
LESS_THAN -- evaluates to true if the left is less in numeric value than the right.
GREATER_THAN -- evaluates to true if the left is greater in numeric value than the right.
CONTAINS -- is meant to test an array term (such as Asset.Tags) with a single value. It evaluates to true if the value on the right side equals one of the values on the array on the left side.
However it will also supports a single value on the left, in which case it behaves just like EQUALS -- regular expressions or wildcards are not supported.

For all of the operators (except EXISTS), if the right hand side evaluates to an array, each value of the array is compared to the left side, according to the operator definition, and if any comparison is true then the result of the evaluation is true.

Examples:

 [[&quot;$Asset.Type&quot;, &quot;EQUALS&quot;, &quot;#Project&quot;]] 
 [&quot;NOT&quot;, [&quot;$Asset.Tags&quot;, &quot;CONTAINS&quot;, &quot;#sensitive&quot;], &quot;AND&quot;, [&quot;NOT&quot;, &quot;$Asset.Tags&quot;, &quot;CONTAINS&quot;, &quot;#confidential&quot;]] 
 [[&quot;$User.Name&quot;, &quot;EQUALS&quot;, &quot;$Asset.Owner&quot;]]

<b>Action</b>

The action is an name with optional parameters or subaction describing an operation to perform. For simple actions like Deny, only the action name will be provided. For actions such as Transform, a subaction with parameters describing the type of transform is also provided. The allowed actions depends on the governance type.

Examples:

 {&quot;name&quot;: &quot;Deny&quot;} 
 {&quot;name&quot;: &quot;Transform&quot;, &quot;subaction&quot;: {&quot;name&quot;: &quot;anonymizeColumns&quot;, &quot;parameters&quot;: [{&quot;name&quot;: &quot;column_name&quot;, &quot;value&quot;: &quot;CCN&quot;}]}}

action

Required *

PoliciesV3Action

the action to perform or enforce when the rule triggers

name

string

parameters

array

subaction

object

the action to perform or enforce when the rule triggers

roLTransform

boolean

state

string

the state of the rule. Only the rules of policies in active are enforced.

Response

200 - Merged with an existing 'ResourceControl' rule.

metadata

PoliciesV3PolicyResourceMetadata

metadata object used in responses returned from policy management related APIs

entity

PoliciesV3PolicyRuleResponseEntity

entity within the response for the /v3/enforcement/rules/{ruleId} API

201 - Created

metadata

PoliciesV3PolicyResourceMetadata

metadata object used in responses returned from policy management related APIs

entity

PoliciesV3PolicyRuleResponseEntity

Path Parameters

Query Parameters

limit

string

The maximum number of Rules to return. The default value is 50.

offset

string

The index of the first matching Rule to include in the result. The default value is 0.

external_export

boolean

For export between two different systems. If specified as true, the ids in rules will be converted to names and added as export_components in the exported file

Response

200 - OK

retrieve terms used in a rule

GET /v3/enforcement/rules/{rule_id}/terms

Retrieves the names of all terms used in a rule.

Request

Path Parameters

rule_id

Required *

string

Rule ID

Query Parameters

Response

200 - OK

resources

errors

array

import rules

POST /v3/enforcement/rules/import

Imports rules using content recieved as application/octet-stream media type. Assumes content to be in UTF-8 charset. Expects "rules" JSON array contained in a JSON objects. Ignores other fields. Rule GUID is prerserved. Retruns JSON array containing GUIDs of newly imported rules.

Request

Request Body

The input stream for reading imported terms

Path Parameters

Query Parameters

external_import

boolean

For import between two different systems. If specified as true, the names in export_components of the import file will be matched and converted to the target system's ids.

commit

boolean

For external imports, if specified as true, the whole import will fail if there are any rules that fail to match ids in the target system. If specified as false, an analysis report will be returned.

Response

200 - OK

imported

array

List containing details of rules that are successfully imported.

failed

array

List containing details of rules that are failed to import.

matched

errors

array

retrieve tenant settings

GET /v3/enforcement/settings

Retrieves governance information and settings about a particular tenant given the tenant identifier.

Request

Response

200 - OK

metadata

PoliciesV3PolicyResourceMetadata

metadata object used in responses returned from policy management related APIs

entity

errors

array

update tenant settings

PUT /v3/enforcement/settings

boolean

Enable/disable audit log for evaluation

Response

200 - OK

metadata

PoliciesV3PolicyResourceMetadata

metadata object used in responses returned from policy management related APIs

entity

errors

array

List projects

GET /v2/projects

Returns a list of projects filtered by the specified query parameters. By default, only projects that the authenticated user is a member of are returned. In IBM Cloud Pak for Data (CPD), all projects in the cluster are returned (regardless of project membership) if the authenticated user is assigned either the "Manage projects" or "Monitor project workloads" CPD permission. In IBM Cloud Pak for Data (CPDaaS), all projects associated with an IBM Cloud Account are returned (regardless of project membership) if the authenticated user is added to the IBM Cloud Account and assigned the IAM "Manager" role.

Request

Path Parameters

Query Parameters

bss_account_id

The BSS Account ID.

type

The project type.

member

A project member to use to filter the query results.

roles

array

A list of comma-separated project roles to use to filter the query results. Must be used in conjunction with the "member" query parameter.

tag_names

string

A list of comma-separated tags to use to filter the query results. If multiple tags are specified, the query results will be filtered to show projects matching any of the tags. (e.g. tag1 OR tag2 OR... tagN).

name

A full or partial project name to use to filter the query results. This query parameter must be used in conjunction with the 'bss_account_id' query parameter. Use the 'match' query parameter to control they type of text matching performed. Project names are not unique and should not be used in place of project IDs.

match

string

The type of text matching to perform. This query parameter must be used in conjunction with the 'name' query parameter. The 'exact' value will match projects if the specified text matches the exact project name. The 'keyword' value will match projects if the specified text matches any keyword parsed from the project name.

project_ids

string

A list of comma-separated project IDs to use to filter the query results. This query parameter only works in conjunction with the 'member' query parameter.

include

array

A list of comma-separated project metadata sections to include in the query results.

limit

integer

The limit used to specify the maximum number of projects returned in the query results. Used for pagination in conjunction with the "bookmark" query parameter.

bookmark

The bookmark is an opaque key returned in the query results set that serves as a reference to the next page of query results. Specify the bookmark on subsquent query requests to retrieve the next page of query results. Used for pagination in conjunction with the "limit" query parameter.

skip

integer

Deprecated. Use of this query parameter exhibits poor performance characteristics. Use the more efficient "bookmark" query parameter instead. The offset to use to define the starting index of projects to return in the query results. Used for pagination in conjunction with the "limit" query parameter.

Response

200 -

401 -

403 -

429 -

Get project total

GET /v2/projects/total

Returns the total number of projects associated with the authenticated user in a BSS account. In IBM Cloud Pak for Data (CPDaaS), specifying the BSS account ID is required. In IBM Cloud Pak for Data (CPD), specifying the BSS account ID is optional. Default is "999". The maximum total number of projects returned will be capped at 2,000 projects (for database performance reasons).

Request

Path Parameters

Query Parameters

bss_account_id

The BSS Account ID.

type

The project type.

member

A project member to use to filter the query results.

tag_names

string

Response

200 -

400 -

401 -

403 -

429 -

Get project

GET /v2/projects/{project_id}

Returns the metadata for a target project specified by ID.

Request

Path Parameters

project_id

Required *

The project ID.

Query Parameters

include

array

A list of comma-separated project metadata sections to include in the query results.

Response

200 -

204 -

400 -

401 -

403 -

404 -

429 -

Update project

PATCH /v2/projects/{project_id}

Partially updates the project with only a subset of properties.

Request

Request Body

Path Parameters

project_id

Required *

The project ID.

Query Parameters

Response

200 -

400 -

401 -

403 -

404 -

429 -

List members

GET /v2/projects/{project_id}/members

Returns the list of project members.

Request

Path Parameters

project_id

Required *

The project ID.

Query Parameters

roles

array

A list of comma-separated project roles to use to filter the query results.

user_names

array

A list of comma-separated usernames corresponding to project members that are used to filter the query results.

Response

200 -

400 -

401 -

403 -

404 -

429 -

Create members

POST /v2/projects/{project_id}/members

Adds new project members with the provided roles. A project must always have at least one admin.

Request

Request Body

Path Parameters

project_id

Required *

The project ID.

Query Parameters

Response

200 -

400 -

401 -

403 -

404 -

429 -

Delete members

DELETE /v2/projects/{project_id}/members

Deletes members from the project that match the provided usernames.

Request

Path Parameters

project_id

Required *

The project ID.

Query Parameters

user_names

Required *

array

A list of comma-separated usernames corresponding to project members to remove from the project.

Response

204 -

400 -

401 -

403 -

404 -

429 -

Update members

PATCH /v2/projects/{project_id}/members

Change project member roles in a batch.

Request

Request Body

Path Parameters

project_id

Required *

The project ID.

Query Parameters

Response

200 -

400 -

401 -

403 -

404 -

429 -

Get member

GET /v2/projects/{project_id}/members/{user_name}

Returns the project member with the specified 'user_name' if any.

Request

Path Parameters

project_id

Required *

The project ID.

user_name

Required *

The username of the project member.

Query Parameters

resolve_groups

boolean

A flag indicating whether to return a derived project member based on resolving user groups.

Response

200 -

400 -

401 -

403 -

404 -

429 -

Delete member

DELETE /v2/projects/{project_id}/members/{user_name}

Deletes a member with a given user name from a project with the given username.

Request

Path Parameters

project_id

Required *

The project ID.

user_name

Required *

The username of the project member.

Query Parameters

Response

204 -

400 -

401 -

403 -

404 -

429 -

GET /v2/projects/{project_id}/tags

Returns the list of project tags.

Request

Path Parameters

project_id

Required *

The project ID.

Query Parameters

Response

200 -

400 -

401 -

403 -

404 -

429 -

Create tags

POST /v2/projects/{project_id}/tags

Adds new tags to a project.

Request

Request Body

Path Parameters

project_id

Required *

The project ID.

Query Parameters

Response

201 -

400 -

401 -

403 -

404 -

422 -

429 -

Delete tags

DELETE /v2/projects/{project_id}/tags

Delete existing tags in a project. If no 'tag_names' are specified, then delete all existing tags in a project.

Request

Path Parameters

project_id

Required *

The project ID.

Query Parameters

tag_names

string

Response

204 -

400 -

401 -

403 -

404 -

429 -

Update tags

PATCH /v2/projects/{project_id}/tags

Adds new tags and removes existing tags from a project via a single bulk update operation.

Request

Request Body

Path Parameters

project_id

Required *

The project ID.

Query Parameters

Response

200 -

400 -

401 -

403 -

404 -

422 -

429 -

Create tag

POST /v2/projects/{project_id}/tags/{tag_name}

Add a new tag to a project.

Request

Request Body

Path Parameters

project_id

Required *

The project ID.

tag_name

Required *

The tag name.

Query Parameters

Response

201 -

400 -

401 -

403 -

404 -

422 -

429 -

Delete tag

DELETE /v2/projects/{project_id}/tags/{tag_name}

Delete an existing tag in a project.

Request

Path Parameters

project_id

Required *

The project ID.

tag_name

Required *

The tag name.

Query Parameters

Response

204 -

400 -

401 -

403 -

404 -

429 -

Get folders settings

GET /v2/projects/{project_id}/settings/folders

Get folders settings.

Request

Path Parameters

project_id

Required *

The project ID.

Query Parameters

Response

200 -

400 -

401 -

403 -

404 -

429 -

Update folders settings

PUT /v2/projects/{project_id}/settings/folders

Update folders settings.

Request

Request Body

Path Parameters

project_id

Required *

The project ID.

Query Parameters

Response

200 -

400 -

401 -

403 -

404 -

429 -

Create a new space

POST /v2/spaces

Creates a new space to scope other assets. Authorized user must have the following roles (see https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-iams)

Platform management role: Administrator
Service access role: Manager

Set to true of the COS instance is delegated by the account admin

compute

array

This flag is not supported on CPD.

tags

array

User-defined tags associated with a space.

generator

string

A consistent label used to identify a client that created a space. A generator must be comprised of the following characters - alphanumeric, dash, underscore, space.

stage

Spacesstage_request

Space production and stage name.

production

boolean

A boolean flag which specifies if a space is production or not. It cannot be modified.

name

string

Stage name. E.g. development, test, pre-production, production.

type

string

Space type.

Response

202 - Accepted

metadata

Spacesresource_meta

Common metadata for a resource.

entity

Spacesspace_entity

400 -

401 -

403 -

404 -

500 -

Retrieve the spaces

GET /v2/spaces

Retrieves the space list.

Request

Path Parameters

A list of comma-separated space sections to include in the query results. Example: '?include=members'.

Available fields:

members (returns up to 100 members)
nothing (does not return space entity and metadata)

member

string

Filters the result list to only include spaces where the user with a matching user id is a member.

roles

string

Must be used in conjunction with the member query parameter. Filters the result set to include only spaces where the specified member has one of the roles specified.

Values:

* admin
* editor
* viewer

bss_account_id

string

Filtering by bss_account_id is allowed only for accredited services.

name

string

Filters the result list to only include space with specified name.

sub_name

string

Filters the result list to only include spaces which name contains specified case-insensitive substring

compute.crn

string

Filters the result list to only include spaces with specified compute.crn.

type

string

Filters the result list to only include space with specified type

Response

200 - OK.

total_count

integer

Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

object

The reference to the first item in the current page.

object

A reference to the first item of the next page, if any.

resources

array

400 -

401 -

403 -

404 -

500 -

Retrieve the space

GET /v2/spaces/{space_id}

Retrieves the space with the specified identifier.

Request

Path Parameters

Query Parameters

include

string

A list of comma-separated space sections to include in the query results. Example: '?include=members'.

Available fields:

members (returns up to 100 members)
nothing (does not return space entity and metadata)

Response

200 - OK.

metadata

Spacesresource_meta

Common metadata for a resource.

entity

Spacesspace_entity

400 -

401 -

403 -

404 -

500 -

Delete the space

DELETE /v2/spaces/{space_id}

Deletes the space with the specified identifier.

Request

Response

202 - Accepted.

400 -

401 -

403 -

404 -

500 -

Update the space

PATCH /v2/spaces/{space_id}

Partially update this space. Allowed paths are: - /name - /description - /compute - /stage/name - /type

Request

Request Body

Input payload for the space.

Response

200 - OK.

metadata

Spacesresource_meta

Common metadata for a resource.

entity

Spacesspace_entity

400 -

401 -

403 -

404 -

500 -

Retrieve the space members

GET /v2/spaces/{space_id}/members

Retrieves the member list for the specified space.

Request

Path Parameters

Find the member by 'state'.

Response

200 - OK.

total_count

integer

Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

object

The reference to the first item in the current page.

object

A reference to the first item of the next page, if any.

resources

array

400 -

401 -

403 -

404 -

500 -

Add a member to space

POST /v2/spaces/{space_id}/members

Adds a member to the specified space.

Request

Request Body

Spacesmembers_request

Member information.

members

Required *

array

Response

200 - OK.

resources

array

400 -

401 -

403 -

404 -

500 -

Retrieve the space member information

GET /v2/spaces/{space_id}/members/{member_id}

Retrieves the member information for the member and space with the specified identifiers.

Request

Response

200 - OK.

id

string

The IAM ID of the space member. This field is required for space members with the 'active' state.

role

string

The role of the space member.

state

string

The state of the space member. This field is only supported for members of type 'user'.

type

string

The space member type.

400 -

401 -

403 -

404 -

500 -

Remove the space member

DELETE /v2/spaces/{space_id}/members/{member_id}

Removes the specified member from the space.

Request

Response

204 - Deleted.

400 -

401 -

403 -

404 -

500 -

Update the space member

PATCH /v2/spaces/{space_id}/members/{member_id}

Partially update the member selected with the specified identifier. Allowed paths are: - /role - /state

Request

Request Body

The json patch.

Response

200 - Partially updated a member.

id

string

The IAM ID of the space member. This field is required for space members with the 'active' state.

role

string

The role of the space member.

state

string

The state of the space member. This field is only supported for members of type 'user'.

type

string

The space member type.

400 -

401 -

403 -

404 -

500 -

Retrieve the asset exports

GET /v2/asset_exports

Retrieves the asset export list for the specified space, project, or catalog.

Request

Path Parameters

Query Parameters

start

string

Token representing first resource.

limit

number

The number of resources returned. Default value is 100. Max value is 200.

Response

200 - OK.

total_count

integer

Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

object

The reference to the first item in the current page.

object

A reference to the first item of the next page, if any.

resources

array

400 -

401 -

403 -

404 -

500 -

Start the asset export process

POST /v2/asset_exports

Starts the asset export process for the specified space, project, or catalog. On CPD 3.0.1 assets export is supported only in the context of a space.

Request

Request Body

Spacesexport_entity_request

Export information.

name

Required *

string

description

string

assets

Required *

Spacesexport_assets

all_assets

boolean

asset_types

array

asset_ids

array

encryption_key

string

Encryption key used to encrypt the sensitive data during export.

format

string

Export format type.

module_keys

array

Response

202 - OK.

metadata

Spacesimport_export_meta

Common metadata for a import/export.

entity

Spacesexport_entity

400 -

401 -

403 -

404 -

500 -

Cancel the asset export process

DELETE /v2/asset_exports/{export_id}

Cancels the asset export process with the specified identifier.

Request

Path Parameters

Query Parameters

hard_delete

boolean

Default is false.

Response

204 - OK.

400 -

401 -

403 -

404 -

500 -

Retrieve the asset export

GET /v2/asset_exports/{export_id}

Retrieves the asset export with the specified identifier.

Request

Response

200 - OK.

metadata

Spacesimport_export_meta

Common metadata for a import/export.

entity

Spacesexport_entity

400 -

401 -

403 -

404 -

500 -

Download the asset export content

GET /v2/asset_exports/{export_id}/content

Downloads the content for the asset export process with the specified identifier.

Request

Response

200 - OK.

400 -

401 -

403 -

404 -

500 -

Retrieve the asset imports

GET /v2/asset_imports

Retrieves the asset import list for the specified space, project, or catalog.

Request

Path Parameters

Query Parameters

start

string

Token representing first resource.

limit

number

The number of resources returned. Default value is 100. Max value is 200.

Response

200 - OK.

total_count

integer

Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.

limit

integer

The number of items to return in each page.

first

object

The reference to the first item in the current page.

object

A reference to the first item of the next page, if any.

resources

array

400 -

401 -

403 -

404 -

500 -

Start the asset import process

POST /v2/asset_imports

Starts the asset import process for the specified space, project, or catalog. On CPD 3.0.1 assets import is supported only in the context of a space.

Request

Request Body

Response

202 - OK.

metadata

Spacesimport_export_meta

Common metadata for a import/export.

entity

Spacesimport_entity

400 -

401 -

403 -

404 -

500 -

Cancel the asset import process

DELETE /v2/asset_imports/{import_id}

Cancels the asset import process with the specified identifier.

Request

Path Parameters

Query Parameters

hard_delete

boolean

Default is false.

Response

204 - OK.

400 -

401 -

403 -

404 -

500 -

Retrieve the asset import

GET /v2/asset_imports/{import_id}

Retrieves the asset import with the specified identifier.

Request

Response

200 - OK.

metadata

Spacesimport_export_meta

Common metadata for a import/export.

entity

Spacesimport_entity

400 -

401 -

403 -

404 -

500 -

Create project as a transaction

POST /transactional/v2/projects

Creates a new project with the provided parameters, including all the storage and credentials in a single transaction. This endpoint will create a new COS bucket using generated unique name, all credentials, asset container and call all the required atomic APIs to fully configure a new project. Attempts to use the duplicate project names will result in an error. <b>NOTE</b>: when creating projects programmatically, always use this endpoint, not /v2/projects. <br/><br/><br/> This endpoint can also be used to create a project from an exported Watson Studio .zip file. In this case, a new transaction is initiated to create assets under the project. A Transaction ID along with a URL is returned as a response of this API. As this transaction can take time, you can view the current status of the transaction using the returned URL.<br><b>NOTE</b>: This feature is only available in the private cloud.

Request

Request Body

TransactionalProjectsTransactionalProjectCreate

name

Required *

string

The name of the new project. The name must be a non-empty String. This does not need to be unique.

description

string

A description for the new project.

type

string

The project type. The "cpd" project type is used to classify IBM Cloud Pak for Data (CPD) projects. The "wx" project type is used to classify IBM watsonx projects. The "wca" project type is used to classify IBM watsonx Code Assistant projects. The "dpx" project type is used to classify IBM Data Product Exchange projects. The "wxbi" project type is used to classify IBM watsonx BI Assistant projects.

generator

Required *

string

A tag to indicate where this project was generated. This is only intended for use in metrics. It does not need to be unique and all consumers of this API should use a consistent string for their 'generator' field. The value is stored in the project metadata for future consumption in metrics.

public

boolean

A value of `true` makes the project public.

tags

array

List of user defined tags that are attached to the project.

enforce_members

boolean

Set to true of project members should be scoped to the account and/or SAML of the creator

storage

Required *

TransactionalProjectsTransactionalProjectStorageObject

Object storage properties to be associated with the project.

type

Required *

string

The type of the associated project storage.

guid

string

Unique guid of the associated project storage object.

plan_id

string

The unique ID of the plan associated with the COS instance. The value is 1e4e33e4-cfa6-4f12-9016-be594a6d5f87 for the One Rate plan.

resource_crn

string

A cloud resource name of the Cloud Object Storage instance in WSC (not required in CP4D or in AWS).

delegated

boolean

Set to true of the COS instance is delegated by the account admin

properties

object

compute

array

List of computes to be associated with the project.

tools

array

List of tools to be associated with the project.

Path Parameters

Query Parameters

verify_unique_name

boolean

If enabled, the transaction fails if the project name is not unique.

Response

201 -

202 -

400 -

401 -

403 -

404 -

500 -

Delete project as a transaction

DELETE /transactional/v2/projects/{project_id}

Deletes a project with a given ID, deletes COS bucket and all the files in it, all credentials and asset container in the order reverse from the project creation transaction. When deleting projects programmatically, always use this endpoint, not /v2/projects/{project_id}.

Request

Path Parameters

project_id

Required *

The ID of the project to be deleted.

Query Parameters

Response

204 - No Content

400 -

401 -

403 -

404 -

500 -

Get status of import transaction

GET /transactional/v2/projects/{project_id}/transactions/{transaction_id}

Status of import transaction created using create project as a transaction API

Request

Path Parameters

project_id

Required *

The ID of the project on which transaction was created.

transaction_id

Required *

The transaction ID provided by create project as a transaction endpoint.

Query Parameters

Response

Description of the last know transaction status

history

array

Description of all last know import status.