Introduction to common core functionality APIs for Data and AI SaaS products
You can use the common core functionality REST APIs for Data and AI SaaS products to work with assets and their workspaces: projects, deployment spaces, and catalogs. Common core functionality is shared among multiple products, such as watsonx as a Service, Cloud Pak for Data as a Service, and others.
For more information, see these resources:
Authentication
Before you can call a common core API you must first create an IAM bearer token. Each token is valid only for one hour, and after a token expires you must create a new one if you want to continue using the API. The recommended method to retrieve a token programmatically is to create an API key for your IBM Cloud identity and then use the IAM token API to exchange that key for a token.
You can create a token in IBM Cloud or by using the IBM Cloud command line interface (CLI).
To create a token in the IBM Cloud:
- Log in to IBM Cloud and select Manage > Access (IAM) > API keys.
- Create an API key for your own personal identity, copy the key value, and save it in a secure place. After you leave the page, you will no longer be able to access this value.
- With your API key, set up a REST API tool and run the following command to the right
You can read more about managing API keys at Understanding API keys documentation page.
- Use the value of the
access_tokenproperty for your API calls. Set theaccess_tokenvalue as the authorization header parameter for requests to the APIs. The format isAuthorization: Bearer <access_token_value_here>. For example:Authorization: Bearer eyJhbGciOiJIUz......sgrKIi8hdFs
To create a token by using the IBM Cloud CLI:
- Follow the steps to install the CLI, log in to IBM Cloud, and get the token
described here.
Remove
Bearerfrom the returned IAM token value in your API calls.
Curl command with API key to retrieve token
curl -X POST 'https://iam.cloud.ibm.com/identity/token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=MY_APIKEY'
Response
{
"access_token": "eyJhbGciOiJIUz......sgrKIi8hdFs",
"refresh_token": "SPrXw5tBE3......KBQ+luWQVY=",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1473188353
}
Error handling
Responses with 400-series or 500-series status codes are returned when a request cannot be completed. The body of these responses follows the error model, which contains a code field to identify the problem and a message field to explain how to solve the problem. Each individual endpoint has specific error messages. All responses with 500 or 503 status codes are logged and treated as a critical failure requiring an emergency fix.
Rate Limiting
The following rate limiting headers are supported by some of the common core service APIs:
- X-RateLimit-Limit: If rate limiting is active, this header indicates the number of requests permitted per hour;
- X-RateLimit-Remaining: If rate limiting is active, this header indicates the number of requests remaining in the current rate limit window;
- X-RateLimit-Reset: If rate limiting is active, this header indicates the time at which the current rate limit window resets, as a UNIX timestamp.
Methods
List defined 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.
GET /v2/connections
Request
Custom Headers
Boolean indicator if cluster username and access token should be injected into connection properties. It has to be ensured that access token is not revealed unintentionally together with connection properties.
Default:
false
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseThe field to sort the results on, including whether to sort ascending (+) or descending (-), for example, sort=-metadata.create_time
The page token indicating where to start paging from.
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100The creator of the connection.
The name of the connection.
The data source type of the connection. To specify multiple data source types, use a comma-separated string, such as entity.datasource_type=<asset_id>,<asset_id>.
The context of the connection. Can be one of "source", "target", or "source,target".
The properties of the connection that must match for the connection to be included in the list.
A comma separated list of flags that must be present for the connection to be included in the list. If not provided, only connections with no flags will be returned.
Whether to return information about source and target interaction properties.
Whether to return decrypted secrets for unrestricted connections.
Default:
trueWhether to return information about connection and interaction properties.
Default:
true
Response
A page from a collection of connections.
List of connections
The number of assets skipped before this page.
The total number of assets available.
Status Code
Connections with metadata.
You are not authorized to list the defined connections.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The defined connections cannot be listed.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Define connection
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.
POST /v2/connections
Request
Custom Headers
The indicator whether shared credentials disablement and vault credentials enforcement guards should be disabled for creation and updates
Default:
false
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseWhether 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.
Default:
trueWhether 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.
Default:
true
The definition of the connection.
The id or the name of the data source type to connect to. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7" or "db2".
The name of the connection.
The id of the data source definition asset related to connection. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7".
The name of the data source definition asset related to connection. For example "Data privacy profile for DB2".
The concatenation of values of conection properties identified as data source definition asset identity properties. For example "host1.fyre.ibm.com|12212|BLUEDB".
Properties that are not stored and obtained from CAMS, but calculated/derived on-the-fly by reading operation
The description of the connection.
Folder that the connection asset lives in.
The ID of the catalog that this connection refers to for properties values.
The ID of the connection in reference catalog that this connection refers to for properties values.
The id of the secure gateway to use with the connection. A Secure Gateway is needed when connecting to an on-premises data source. This is the id of the Secure Gateway created with the SecureGateway Service. Your Secure Gateway Client running on-premises must be connected to the gateway with this Id. For example, "E9oXGRIhv1e_prod_ng".
Specifies how a connection is to be treated internally.
Allowable values: [
restricted,internal_use_only,personal_credentials,parameterized]Country which data originated from. - ISO 3166 Country Codes.
Owner or creator of connection. Provided when a service ID token is used to create connection.
Rules of visibility for connections.
Connection properties.
- properties
- any property
Interaction properties allowed for a connection.
Custom data to be associated with a given object
- source_system
The asset category
Allowable values: [
user,system]Indicates the location used by this connection.
Response
A connection.
System metadata about an asset
The connection definition.
Status Code
The connection was created.
The connection test failed. See the error message for details.
You are not authorized to define a connection.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. A connection was not created.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Get connection
Gets details of a specific connection definition.
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.
GET /v2/connections/{connection_id}Request
Custom Headers
Boolean indicator if cluster username and access token should be injected into connection properties. It has to be ensured that access token is not revealed unintentionally together with connection properties.
Default:
false
Path Parameters
The ID of the connection.
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseSpecify 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.
Whether to return information about source and target interaction properties.
Whether to return decrypted secrets for unrestricted connections.
Default:
true
Response
A connection.
System metadata about an asset
The connection definition.
Status Code
The connection object.
You are not authorized to get details about the connection.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The connection definition details cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Delete connection
Deletes a connection definition. This call does not check whether the connection is used by activities, data sets or other assets. The caller must check this before deleting a connection.
DELETE /v2/connections/{connection_id}Request
Path Parameters
The ID of the connection.
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
false
Response
Status Code
The connection was deleted.
You are not authorized to delete a connection.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The connection was not deleted.
No Sample Response
Request
Custom Headers
The indicator whether shared credentials disablement and vault credentials enforcement guards should be disabled for creation and updates
Default:
false
Path Parameters
The ID of the connection.
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseWhether 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.
Default:
trueWhether 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.
Default:
true
Fields to update within the connection.
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
The connection definition.
The id or the name of the data source type to connect to. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7" or "db2".
The name of the connection.
The id of the data source definition asset related to connection. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7".
The name of the data source definition asset related to connection. For example "Data privacy profile for DB2".
The concatenation of values of conection properties identified as data source definition asset identity properties. For example "host1.fyre.ibm.com|12212|BLUEDB".
Properties that are not stored and obtained from CAMS, but calculated/derived on-the-fly by reading operation
The description of the connection.
Folder that the connection asset lives in.
The ID of the catalog that this connection refers to for properties values.
The ID of the connection in reference catalog that this connection refers to for properties values.
The id of the secure gateway to use with the connection. A Secure Gateway is needed when connecting to an on-premises data source. This is the id of the Secure Gateway created with the SecureGateway Service. Your Secure Gateway Client running on-premises must be connected to the gateway with this Id. For example, "E9oXGRIhv1e_prod_ng".
Specifies how a connection is to be treated internally.
Possible values: [
restricted,internal_use_only,personal_credentials,parameterized]Country which data originated from. - ISO 3166 Country Codes.
Owner or creator of connection. Provided when a service ID token is used to create connection.
Rules of visibility for connections.
Connection properties.
- properties
- any property
Interaction properties allowed for a connection.
Custom data to be associated with a given object
- source_system
The asset category
Possible values: [
user,system]Indicates the location used by this connection.
Status Code
The updated connection definition object.
The connection test failed. See the error message for details.
You are not authorized to update the connection definition.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The connection definition was not updated.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Discover assets
Discovers assets from the data source accessed via a connection description.
POST /v2/connections/assets
Request
Custom Headers
Specify whether to return the asset's data in parsed form (application/json) or as raw bytes. This only applies to sources that produce data as a file, document or stream of bytes. To return bytes specify application/octet-stream.
Query Parameters
Path of the asset.
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.
Possible values: value ≥ 0
Default:
0Specify whether to return the asset's metadata, the asset's data, interaction properties, connection properties, or data source type. If not specified, metadata is used by default. This parameter only applies when requesting details about a data set. To specify multiple fetch values, use a comma-separated string, such as fetch=data,metadata,interaction,connection,datasource_type.
Specify whether to return additional asset-specific details. If not specified, these details are not returned.
Specify whether assets are discovered for the purpose of reading (source) or writing (target). If not specified, source is used by default.
Allowable values: [
source,target]A JSON object containing a set of properties to configure aspects of the asset browsing.
A JSON object containing a set of properties to define filtering of the assets to be returned.
The connection definition.
The id or the name of the data source type to connect to. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7" or "db2".
The name of the connection.
The id of the data source definition asset related to connection. For example "cfdcb449-1204-44ba-baa6-9a8a878e6aa7".
The name of the data source definition asset related to connection. For example "Data privacy profile for DB2".
The concatenation of values of conection properties identified as data source definition asset identity properties. For example "host1.fyre.ibm.com|12212|BLUEDB".
Properties that are not stored and obtained from CAMS, but calculated/derived on-the-fly by reading operation
The description of the connection.
Folder that the connection asset lives in.
The ID of the catalog that this connection refers to for properties values.
The ID of the connection in reference catalog that this connection refers to for properties values.
The id of the secure gateway to use with the connection. A Secure Gateway is needed when connecting to an on-premises data source. This is the id of the Secure Gateway created with the SecureGateway Service. Your Secure Gateway Client running on-premises must be connected to the gateway with this Id. For example, "E9oXGRIhv1e_prod_ng".
Specifies how a connection is to be treated internally.
Allowable values: [
restricted,internal_use_only,personal_credentials,parameterized]Country which data originated from. - ISO 3166 Country Codes.
Owner or creator of connection. Provided when a service ID token is used to create connection.
Rules of visibility for connections.
Connection properties.
- properties
- any property
Interaction properties allowed for a connection.
Custom data to be associated with a given object
- source_system
The asset category
Allowable values: [
user,system]Indicates the location used by this connection.
Response
A page from a collection of discovered assets.
A page from a collection of discovered assets.
The path of the asset.
An ID for the asset.
Properties defining the returned assets.
- properties
- any property
Discovered types
Discovered assets
Discovered fields
The definition of a data source type.
Connection properties.
- connection_properties
- any property
The interaction properties needed to find the asset.
- interaction_properties
- any property
Extended metadata properties
The data returned when the fetch parameter contains the value "data".
- data
Details about a discovered asset.
- details
- any property
The number of assets skipped before this page.
The total number of assets available.
Log events created during the discovery of the assets.
Status Code
The discovered assets.
You are not authorized to discover assets.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No assets were found.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Discover assets
Discovers assets from the data source accessed via the connection.
GET /v2/connections/{connection_id}/assetsRequest
Custom Headers
Specify whether to return the asset's data in parsed form (application/json) or as raw bytes. This only applies to sources that produce data as a file, document or stream of bytes. To return bytes specify application/octet-stream.
Path Parameters
The ID of the connection.
Query Parameters
Path of the asset.
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseThe ID of the data asset.
The ID of the catalog that contains the data asset.
The ID of the project that contains the data asset.
The ID of the space that contains the data asset.
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.
Possible values: value ≥ 0
Default:
0Specify whether to return the asset's metadata, the asset's data, interaction properties, connection properties, or data source type. If not specified, metadata is used by default. This parameter only applies when requesting details about a data set. To specify multiple fetch values, use a comma-separated string, such as fetch=data,metadata,interaction,connection,datasource_type.
Specify whether to return additional asset-specific details. If not specified, these details are not returned.
Specify whether assets are discovered for the purpose of reading (source) or writing (target). If not specified, source is used by default.
Allowable values: [
source,target]A JSON object containing a set of properties to configure aspects of the asset browsing.
A JSON object containing a set of properties to define filtering of the assets to be returned.
Response
A page from a collection of discovered assets.
A page from a collection of discovered assets.
The path of the asset.
An ID for the asset.
Properties defining the returned assets.
- properties
- any property
Discovered types
Discovered assets
Discovered fields
The definition of a data source type.
Connection properties.
- connection_properties
- any property
The interaction properties needed to find the asset.
- interaction_properties
- any property
Extended metadata properties
The data returned when the fetch parameter contains the value "data".
- data
Details about a discovered asset.
- details
- any property
The number of assets skipped before this page.
The total number of assets available.
Log events created during the discovery of the assets.
Status Code
The discovered assets.
You are not authorized to discover assets in the data source accessed through the connection.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No assets were discovered in the data source.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Request
Custom Headers
Specify whether to return the asset's data in parsed form (application/json) or as raw bytes. This only applies to sources that produce data as a file, document or stream of bytes. To return bytes specify application/octet-stream.
Path Parameters
The ID of the data asset.
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
falseThe limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.
Possible values: value ≥ 0
Default:
0Specify whether to return the asset's metadata, the asset's data, interaction properties, connection properties, or data source type. If not specified, metadata is used by default. This parameter only applies when requesting details about a data set. To specify multiple fetch values, use a comma-separated string, such as fetch=data,metadata,interaction,connection,datasource_type.
Specify whether to return additional asset-specific details. If not specified, these details are not returned.
Specify whether assets are discovered for the purpose of reading (source) or writing (target). If not specified, source is used by default.
Allowable values: [
source,target]A JSON object containing a set of properties to configure aspects of the asset browsing.
A JSON object containing a set of properties to define filtering of the assets to be returned.
Path of the asset.
Response
A page from a collection of discovered assets.
A page from a collection of discovered assets.
The path of the asset.
An ID for the asset.
Properties defining the returned assets.
- properties
- any property
Discovered types
Discovered assets
Discovered fields
The definition of a data source type.
Connection properties.
- connection_properties
- any property
The interaction properties needed to find the asset.
- interaction_properties
- any property
Extended metadata properties
The data returned when the fetch parameter contains the value "data".
- data
Details about a discovered asset.
- details
- any property
The number of assets skipped before this page.
The total number of assets available.
Log events created during the discovery of the assets.
Status Code
The discovered asset.
You are not authorized to discover the asset.
You are not permitted to perform this action.
The asset cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No assets were discovered in the data source.
A timeout occurred when processing your request. Please retry later.
No Sample Response
List actions
Lists all supported actions for the connection.
GET /v2/connections/{connection_id}/actionsRequest
Custom Headers
The user's preferred locale identifier.
Default:
en-US
Path Parameters
The ID of the connection.
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
false
Response
Connection actions.
The actions supported for the data source.
Status Code
The actions supported for the connection.
You are not authorized to list the actions for the connection.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The actions for the connection cannot be listed.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Perform action
Performs an action on the data source accessed using the connection.
PUT /v2/connections/{connection_id}/actions/{action_name}Request
Path Parameters
The ID of the connection.
The name of the action to be performed. This list is expanded over time. The current actions are:
| action | description | | --------------------- | ------------------------------------------------------------------------ | | get_dsd_details | to obtain Data Source Definition Asset details from a connector. | | get_oauth2_tokens | to get refresh and authorization tokens for sources that support OAuth2. | | get_record_count | to get the number of records available for the specified asset. | | get_signed_url | to get a signed URL for accessing a data source. | | test | to check if a connection can be established to the data source. | | validate | to validate the connection properties without establishing a connection. |
Allowable values: [
get_dsd_details,get_oauth2_tokens,get_record_count,get_signed_url,test,validate]
Query Parameters
The ID of the catalog to use. catalog_id, project_id, or space_id is required.
The ID of the project to use. catalog_id, project_id, or space_id is required.
The ID of the space to use. catalog_id, project_id, or space_id is required.
true for a project needs assets managed by the /userfs API, i.e. if it has git integration
Default:
false
The perform action request configuration.
- any property
Response
Results of a connection perform action request.
- any property
Status Code
Any output produced by the action.
The perform action request is invalid.
You are not authorized to perform an action on a data source accessed through the connection.
You are not permitted to perform this action.
The connection cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No action was performed on the data source.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Response
Status Code
The file object.
You are not authorized to get content of the file.
You are not permitted to perform this action.
The file cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The driver jar cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Upload a file
Upload a file and get back a signed handle in 'Location' header with a hash
POST /v2/connections/files/{file_name}Response
Status Code
The file object.
You are not authorized to get content of the file.
You are not permitted to perform this action.
The file cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The driver jar cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Response
Status Code
The file was deleted.
You are not authorized to get content of the file.
You are not permitted to perform this action.
The file cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The driver jar cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Request
Query Parameters
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.
Possible values: value ≥ 0
Default:
0
Response
A page from a collection of uploaded files.
List of uploaded files
The number of assets skipped before this page.
The total number of assets available.
Status Code
List of available files
You are not authorized to get the list of files.
You are not permitted to perform this action.
The file cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The driver jar cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Request
Query Parameters
Indicator, if only list files to be migrated.
Indicator, if migrate connections from catalogs.
Indicator, if migrate connections from projects.
Indicator, if migrate connections from spaces.
Response
A page from a collection of migrated connections.
List of migrated connections
The number of assets available.
The name of the log with migration process logging.
List of exceptions encountered durring the migration process.
Status Code
List of newly uploaded files
You are not authorized to migrate files.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The driver jar cannot be retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
List defined types of data sources
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. |
GET /v2/datasource_types
Request
Custom Headers
The user's preferred locale identifier.
Default:
en-US
Query Parameters
The field to sort the results on, including whether to sort ascending (+) or descending (-), for example, sort=-metadata.create_time
The 0-based index of the first result to return, for example, offset=200. If not specified, the default offset of 0 is used.
Possible values: value ≥ 0
Default:
0The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Possible values: value ≥ 1
Default:
100Whether to return information about connection properties.
Whether to return information about source and target interaction properties.
Whether to return information about discovery capabilities.
Whether to return information about supported actions.
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.
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.
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.
Allowable values: [
global,context]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.
Default:
falseWhether 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).
Default:
false
Response
A page from a collection of data source types.
List of data source types
The number of assets skipped before this page.
The total number of assets available.
Status Code
Collection of data source types.
You are not authorized to list the defined types of data sources.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No data source types were retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Request
The definition of the data source type.
Information needed to connect to a custom Arrow Flight service.
The UUID of the base datasource type for this custom datasource type
A unique name, such as "dashdb".
A localized, displayable label such as, "IBM dashDB".
A localized, displayable description of the data source.
Whether the data source can be accessed as a source of data. That is, data can be read from the data source.
Whether the data source can be accessed as a target. That is, data can be written to the data source.
The definition of the discovery features of the data source type.
Custom data to be associated with a given object
- properties
Definition of a data source property for a custom datasource type.
The status of the data source.
Allowable values: [
active,deprecated,inactive,internal,pending,system]Country which data originated from. - ISO 3166 Country Codes.
Owner or creator of connection. Provided when a service ID token is used to create connection.
Rules of visibility for connections.
Custom data to be associated with a given object
- source_system
Tags associated with a data source type.
The actions supported for the data source.
Response
A collection of custom data source types.
List of data source types
Status Code
The data source type was created.
The data source type definition is not valid. See the error message for details.
You are not authorized to define a data source type.
You are not permitted to perform this action.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. A data source type was not created.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Get details for type of data source
Get details for type of data source.
GET /v2/datasource_types/{datasource_type}Request
Custom Headers
The user's preferred locale identifier.
Default:
en-US
Path Parameters
The data source type.
Query Parameters
Whether to return information about connection properties.
Whether to return information about source and target interaction properties.
Whether to return information about discovery capabilities.
Whether to return information about supported actions.
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.
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.
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.
Allowable values: [
global,context]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.
Default:
false
Response
The definition of a data source type.
System metadata about an asset
The definition of a data source type.
Status Code
A data source type definition.
You are not authorized to retrieve the type details of the data source.
You are not permitted to perform this action.
The data source type details cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. No data source type details were retrieved.
A timeout occurred when processing your request. Please retry later.
No Sample Response
Delete data source 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.
DELETE /v2/datasource_types/{datasource_type}Response
Status Code
The data source type was deleted.
You are not authorized to delete a data source type.
You are not permitted to perform this action.
The data source type cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The connection was not deleted.
No Sample Response
Update datasource type
Updates the definition of a datasource type.
PATCH /v2/datasource_types/{datasource_type}Request
Path Parameters
The data source type.
Fields to update within the data source type.
The operation to be performed
Allowable values: [
add,remove,replace,move,copy,test]A JSON pointer to the field to update
A string containing a JSON pointer value
- value
Response
The definition of a custom data source type.
Information needed to connect to a custom Arrow Flight service.
The UUID of the base datasource type for this custom datasource type
A unique name, such as "dashdb".
A localized, displayable label such as, "IBM dashDB".
A localized, displayable description of the data source.
Whether the data source can be accessed as a source of data. That is, data can be read from the data source.
Whether the data source can be accessed as a target. That is, data can be written to the data source.
The definition of the discovery features of the data source type.
Custom data to be associated with a given object
- properties
Definition of a data source property for a custom datasource type.
The status of the data source.
Possible values: [
active,deprecated,inactive,internal,pending,system]Country which data originated from. - ISO 3166 Country Codes.
Owner or creator of connection. Provided when a service ID token is used to create connection.
Rules of visibility for connections.
Custom data to be associated with a given object
- source_system
Tags associated with a data source type.
The actions supported for the data source.
Status Code
The updated data source type definition object.
The data source type patch request is not valid. See the error message for details.
You are not authorized to update the data source type definition.
You are not permitted to perform this action.
The data source type cannot be found.
The service is currently receiving more requests than it can process in a timely fashion. Please retry submitting your request later.
An error occurred. The data source type definition was not updated.
A timeout occurred when processing your request. Please retry later.
No Sample Response
List 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.
GET /v2/projects
Request
Custom Headers
A CPDaaS specific flag indicating whether to fetch IAM permissions for the authenticated user as part of the request. Used to determine superuser access via the "manage_project" permission.
Default:
false
Query Parameters
The BSS Account ID.
Possible values: Value must match regular expression
^[0-9a-f]{32}$Example:
0821fa9f9ebcc7b7c9a0d6e9bfa72aa4The project type.
Allowable values: [
cpd,wx,wca,dpx,wxbi]A project member to use to filter the query results.
Possible values: 1 ≤ length ≤ 100
Example:
zapp.brannigan@ibm.comA list of comma-separated project roles to use to filter the query results. Must be used in conjunction with the "member" query parameter.
Allowable values: [
admin,editor,viewer]Default:
[]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).
Example:
development,test,productionA 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.
Possible values: 1 ≤ length ≤ 100
Example:
Sentiment AnalysisThe 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.
Allowable values: [
exact,keyword]Default:
exactA 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.
Example:
d122ffba-de9e-4c67-89c4-0091f1610076,deb5b1d8-5fd4-486c-92ef-12e90959dbf1A list of comma-separated project metadata sections to include in the query results.
Allowable values: [
name,fields,members,tags,settings,everything,nothing]Default:
["fields"]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.
Possible values: 0 ≤ value ≤ 100
Default:
10The 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.
Possible values: Value must match regular expression
^[0-9A-Za-z_-]{1,1000}$Example:
g1AAAAE6eJzLYWBgYMlgTmHQTElKzi9KdUhJMtdLytVNTtYtLdYtzi8tydA1MNVLzskvTUnMK9HLSy3JAWphSnIAkkn-____z8pgcrP_afo-ASiQyIhqlAlRRoF0JuXDjPrBf0cBZBQzGa7KYwGSDAeAFNC082DjvnclHgAZx4RqnAXxxl2AGHcfxaNMWQBvIGVgDeprecated. 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.
Possible values: value ≥ 0
Default:
0
Response
A list of projects.
The total number of project returned in the query results.
Possible values: value ≥ 0
Example:
1The bookmark is an opaque key returned in the query results set that serves as a reference to the next page of query results.
Possible values: Value must match regular expression
^[0-9A-Za-z_-]{1,1000}$Example:
g1AAAAE6eJzLYWBgYMlgTmHQTElKzi9KdUhJMtdLytVNTtYtLdYtzi8tydA1MNVLzskvTUnMK9HLSy3JAWphSnIAkkn-____z8pgcrP_afo-ASiQyIhqlAlRRoF0JuXDjPrBf0cBZBQzGa7KYwGSDAeAFNC082DjvnclHgAZx4RqnAXxxl2AGHcfxaNMWQBvIGVgA list of projects returned in the query results.
Status Code
OK
Unauthorized
Forbidden
Too Many Requests
{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 61. Limit: 60. Category: query. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Get project 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).
GET /v2/projects/total
Request
Custom Headers
A CPDaaS specific flag indicating whether to fetch IAM permissions for the authenticated user as part of the request. Used to determine superuser access via the "manage_project" permission.
Default:
false
Query Parameters
The BSS Account ID.
Possible values: Value must match regular expression
^[0-9a-f]{32}$Example:
0821fa9f9ebcc7b7c9a0d6e9bfa72aa4The project type.
Allowable values: [
cpd,wx,wca,dpx,wxbi]A project member to use to filter the query results.
Possible values: 1 ≤ length ≤ 100
Example:
zapp.brannigan@ibm.comA 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).
Example:
development,test,production
Response
The project total.
The project total.
Possible values: value ≥ 0
Example:
10
Status Code
OK
Bad Request
Unauthorized
Forbidden
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Query Parameters
A list of comma-separated project metadata sections to include in the query results.
Allowable values: [
name,fields,members,tags,settings,integrations,storage,credentials,everything,nothing]Default:
["fields"]
Response
A project object.
The metadata containing information about the project.
- metadata
The project ID represented as a version 4 UUID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The project URL.
Example:
/v2/projects/46a19524-bfbf-4810-a1f0-b131f12bc773The date and time the project was created in UTC (ISO 8601)
Example:
2019-03-05T23:15:36.175ZThe date and time the project was last updated in UTC (ISO 8601)
Example:
2019-10-02T19:26:49.684Z
The entity payload representing the core project attributes.
- entity
The name of the project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote ("), percentage sign (%)
Possible values: 1 ≤ length ≤ 100
Example:
Project NameA description for the new project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote (")
Possible values: 0 ≤ length ≤ 1000
Example:
A project description.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.
Possible values: [
cpd,wx,wca,dpx,wxbi]A value of "true" makes the project public.
The username of the user that created the project.
Example:
zapp.brannigan@ibm.comThe IAM ID of the user that created the project.
Example:
IBMid-55000353XFThe project scope definition.
A list of tags associated with the project.
Possible values: 1 ≤ length ≤ 30, Value must match regular expression
^[^,]+$The storage associated with the project.
A catalog associated with the project.
A list of computes associated with the project.
The GitHub repository associated with the project.
The project settings.
The members associated with the project.
The tools associated with the project.
Possible values: [
jupyter_notebooks,watson_visual_recognition,dashboards,streams_designer,spss_modeler,experiments,data_refinery]
Status Code
OK
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Update project
Partially updates the project with only a subset of properties.
PATCH /v2/projects/{project_id}Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
The request body for updating an existing project.
The name of the project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote ("), percentage sign (%)
Possible values: 1 ≤ length ≤ 100
Example:
Project NameA description for the new project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote (")
Possible values: 0 ≤ length ≤ 1000
Example:
A project description.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.
Allowable values: [
cpd,wx,wca,dpx,wxbi]A value of "true" makes the project public.
Default:
falseA catalog associated with the project.
A list of computes associated with the project.
The tools associated with the project.
Allowable values: [
jupyter_notebooks,watson_visual_recognition,dashboards,streams_designer,spss_modeler,experiments,data_refinery]The GitHub repository associated with the project.
Response
A project object.
The metadata containing information about the project.
- metadata
The project ID represented as a version 4 UUID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The project URL.
Example:
/v2/projects/46a19524-bfbf-4810-a1f0-b131f12bc773The date and time the project was created in UTC (ISO 8601)
Example:
2019-03-05T23:15:36.175ZThe date and time the project was last updated in UTC (ISO 8601)
Example:
2019-10-02T19:26:49.684Z
The entity payload representing the core project attributes.
- entity
The name of the project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote ("), percentage sign (%)
Possible values: 1 ≤ length ≤ 100
Example:
Project NameA description for the new project. The name cannot contain any of the following characters - left angle bracket (<), right angle bracket (>), backslash (\), double quote (")
Possible values: 0 ≤ length ≤ 1000
Example:
A project description.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.
Possible values: [
cpd,wx,wca,dpx,wxbi]A value of "true" makes the project public.
The username of the user that created the project.
Example:
zapp.brannigan@ibm.comThe IAM ID of the user that created the project.
Example:
IBMid-55000353XFThe project scope definition.
A list of tags associated with the project.
Possible values: 1 ≤ length ≤ 30, Value must match regular expression
^[^,]+$The storage associated with the project.
A catalog associated with the project.
A list of computes associated with the project.
The GitHub repository associated with the project.
The project settings.
The members associated with the project.
The tools associated with the project.
Possible values: [
jupyter_notebooks,watson_visual_recognition,dashboards,streams_designer,spss_modeler,experiments,data_refinery]
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Query Parameters
A list of comma-separated project roles to use to filter the query results.
Allowable values: [
admin,editor,viewer]Default:
[]A list of comma-separated usernames corresponding to project members that are used to filter the query results.
Possible values: 1 ≤ length ≤ 100
Response
A list of project members.
A list of project members.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Create members
Adds new project members with the provided roles. A project must always have at least one admin.
POST /v2/projects/{project_id}/membersRequest
Custom Headers
A CPDaaS specific flag indicating whether to fetch IAM permissions for the authenticated user as part of the request. Used to determine superuser access via the "manage_project" permission.
Default:
false
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
A list of project members.
A list of project members.
Response
A list of project members.
A list of project members.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Delete members
Deletes members from the project that match the provided usernames.
DELETE /v2/projects/{project_id}/membersRequest
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Query Parameters
A list of comma-separated usernames corresponding to project members to remove from the project.
Possible values: 1 ≤ length ≤ 100
Response
Status Code
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Custom Headers
A CPDaaS specific flag indicating whether to fetch IAM permissions for the authenticated user as part of the request. Used to determine superuser access via the "manage_project" permission.
Default:
false
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
The request body for updating project members.
A list of project members to update.
Response
A list of project members.
A list of project members.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Get member
Returns the project member with the specified 'user_name' if any.
GET /v2/projects/{project_id}/members/{user_name}Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The username of the project member.
Possible values: 1 ≤ length ≤ 100
Example:
zapp.brannigan@ibm.com
Query Parameters
A flag indicating whether to return a derived project member based on resolving user groups.
Default:
true
Response
A project member.
The username of the project member. If the member type is "service" or "group", then the "user_name" and "id" fields must match.
Possible values: 1 ≤ length ≤ 100
Example:
zapp.brannigan@ibm.comThe IAM ID of the project member. This field is required for project members with the "ACTIVE" state.
Possible values: 1 ≤ length ≤ 100, Value must match regular expression
^[0-9a-zA-Z-]$Example:
IBMid-55000353XFThe role of the project member.
Possible values: [
admin,editor,viewer]Example:
adminThe state of the project member. This field is only supported for members of type "user".
Possible values: [
ACTIVE,PENDING]The project member type.
Possible values: [
user,group,service]A flag indicating whether the project member is derived from a resolved user group.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Delete member
Deletes a member with a given user name from a project with the given username.
DELETE /v2/projects/{project_id}/members/{user_name}Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The username of the project member.
Possible values: 1 ≤ length ≤ 100
Example:
zapp.brannigan@ibm.com
Response
Status Code
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Response
A list of tags associated with the project.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
A tag associated with the project. The tag cannot contain a comma (,). The tag cannot contain any of the following characters unless escaped by character entities - left angle bracket (<)(<), right angle bracket (>)(>), single-quote (')('), double quote (")("), ampersand (&)(&).
Response
A list of tags associated with the project.
Status Code
Created
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "422", "error": "Unprocessable Entity", "reason": "The number of projects created by the authenticated user exceeds the designated limit. Projects created by user (101) > Projects per user limit (100).", "message": "The request was well-formed but was unable to be followed due to semantic errors.", "id": "WSCPA0001E" }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Delete tags
Delete existing tags in a project. If no 'tag_names' are specified, then delete all existing tags in a project.
DELETE /v2/projects/{project_id}/tagsRequest
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Query Parameters
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).
Example:
development,test,production
Response
Status Code
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Update tags
Adds new tags and removes existing tags from a project via a single bulk update operation.
PATCH /v2/projects/{project_id}/tagsRequest
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
An operation to add or remove project tags.
[
{
"op": "add",
"tags": [
"development",
"test"
]
},
{
"op": "remove",
"tags": [
"production"
]
}
]The tag operation.
Allowable values: [
add,remove]Example:
addA list of tags associated with the project.
Possible values: 1 ≤ length ≤ 30, Value must match regular expression
^[^,]+$
Response
A list of tags associated with the project.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "422", "error": "Unprocessable Entity", "reason": "The number of projects created by the authenticated user exceeds the designated limit. Projects created by user (101) > Projects per user limit (100).", "message": "The request was well-formed but was unable to be followed due to semantic errors.", "id": "WSCPA0001E" }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The tag name.
Possible values: 1 ≤ length ≤ 30, Value must match regular expression
^[^,]+$Example:
development
Response
A list of tags associated with the project.
Status Code
Created
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "422", "error": "Unprocessable Entity", "reason": "The number of projects created by the authenticated user exceeds the designated limit. Projects created by user (101) > Projects per user limit (100).", "message": "The request was well-formed but was unable to be followed due to semantic errors.", "id": "WSCPA0001E" }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773The tag name.
Possible values: 1 ≤ length ≤ 30, Value must match regular expression
^[^,]+$Example:
development
Response
Status Code
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
Response
The folders settings group.
The enablement flag for the folders feature.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 601. Limit: 600. Category: read. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Request
Path Parameters
The project ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
46a19524-bfbf-4810-a1f0-b131f12bc773
The folders settings group.
The enablement flag for the folders feature.
Response
The folders settings group.
The enablement flag for the folders feature.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "code": "400", "error": "Bad Request", "reason": "Entity body.name contains invalid characters.", "message": "The server cannot or will not process the request due to an apparent client error." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Permission Denied: Authenticated user is not a member of the project: zapp.brannigan@ibm.com.", "message": "The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Failed to retrieve project: 47f11f98-1fc2-4478-ba38-d037094e761f.", "message": "The requested resource could not be found." }{ "code": "429", "error": "Too Many Requests", "reason": "The number of requests has exceeded the rate limit. Requests: 451. Limit: 450. Category: write. Subject: zapp.brannigan@ibm.com (IBMid-55000353XF).", "message": "The client has sent too many requests in a given amount of time." }
Create project as a transaction
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. NOTE: when creating projects programmatically, always use this endpoint, not /v2/projects.
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.
NOTE: This feature is only available in the private cloud.
POST /transactional/v2/projects
Request
Custom Headers
Allowable values: [
application/json,multipart/form-data]
Query Parameters
If enabled, the transaction fails if the project name is not unique.
Default:
true
Project metadata required to create a project.
The name of the new project. The name must be a non-empty String. This does not need to be unique.
Example:
Project NameA 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.
Example:
DAP-ProjectsObject storage properties to be associated with the project.
A description for the new project.
Example:
A project description.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.
Allowable values: [
cpd,wx,wca,dpx,wxbi]Default:
cpdA value of
truemakes the project public.Default:
falseList of user defined tags that are attached to the project.
Set to true of project members should be scoped to the account and/or SAML of the creator
Default:
falseList of computes to be associated with the project.
List of tools to be associated with the project.
Allowable values: [
watson_visual_recognition,jupyter_notebooks,dashboards,streams_designer,spss_modeler,experiments,data_refinery]
Response
Description of create transactional project API response body.
API to access the newly created project.
Status Code
Created
Accepted
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "location": "/v2/projects/b2549f22-7565-4193-9434-9b77e15757cc" }{ "location": "/v2/projects/b2549f22-7565-4193-9434-9b77e15757cc", "transaction_detail": { "id": "dcff12a9-3f9e-4d10-b4c4-f121f681d81b", "links": { "self": "/transactional/v2/projects/b2549f22-7565-4193-9434-9b77e15757cc/transactions/dcff12a9-3f9e-4d10-b4c4-f121f681d81b" } } }{ "code": "400", "error": "Bad Request", "reason": "Error fetching projects. Status code: 400", "message": "The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax).", "description": "[400] Bad Request: Error fetching projects. Status code: 400. The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax)." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed.", "description": "[401] Unauthorized: Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Invalid bearer token: Access token is invalid.", "message": "The target operation is strictly forbidden due to schema constraints.", "description": "[403] Forbidden: Invalid bearer token: Access token is invalid. The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "Resource requested by the client was not found.", "description": "[404] Not Found: Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76. Resource requested by the client was not found." }{ "code": "500", "error": "Internal Server Error", "reason": "Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "The API encountered an unexpected condition which prevented it from fulfilling the request.", "description": "[500] Internal Server Error: Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76." }
Delete project as a transaction
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}.
DELETE /transactional/v2/projects/{project_id}Request
Path Parameters
The ID of the project to be deleted.
Example:
6ee2c24f-d0a9-4e30-b0fc-5ae36a66c1a8
Response
Status Code
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "code": "400", "error": "Bad Request", "reason": "Error fetching projects. Status code: 400", "message": "The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax).", "description": "[400] Bad Request: Error fetching projects. Status code: 400. The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax)." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed.", "description": "[401] Unauthorized: Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Invalid bearer token: Access token is invalid.", "message": "The target operation is strictly forbidden due to schema constraints.", "description": "[403] Forbidden: Invalid bearer token: Access token is invalid. The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "Resource requested by the client was not found.", "description": "[404] Not Found: Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76. Resource requested by the client was not found." }{ "code": "500", "error": "Internal Server Error", "reason": "Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "The API encountered an unexpected condition which prevented it from fulfilling the request.", "description": "[500] Internal Server Error: Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76." }
Get status of import transaction
Status of import transaction created using create project as a transaction API
GET /transactional/v2/projects/{project_id}/transactions/{transaction_id}Request
Path Parameters
The ID of the project on which transaction was created.
Example:
6ee2c24f-d0a9-4e30-b0fc-5ae36a66c1a8The transaction ID provided by create project as a transaction endpoint.
Example:
dcff12a9-3f9e-4d10-b4c4-f121f681d81b
Response
Description of import transactional status API response.
Project GUID.
Name of the project.
The date and time the status was created in UTC (ISO 8601)
The date and time the status was last updated in UTC (ISO 8601)
Last known status of the transaction
Description of the last know transaction status
Description of all last know import status.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "code": "400", "error": "Bad Request", "reason": "Error fetching projects. Status code: 400", "message": "The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax).", "description": "[400] Bad Request: Error fetching projects. Status code: 400. The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax)." }{ "code": "401", "error": "Unauthorized", "reason": "Unable to verify token via IAM Auth server.", "message": "Authentication failed.", "description": "[401] Unauthorized: Authentication failed." }{ "code": "403", "error": "Forbidden", "reason": "Invalid bearer token: Access token is invalid.", "message": "The target operation is strictly forbidden due to schema constraints.", "description": "[403] Forbidden: Invalid bearer token: Access token is invalid. The target operation is strictly forbidden due to schema constraints." }{ "code": "404", "error": "Not Found", "reason": "Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "Resource requested by the client was not found.", "description": "[404] Not Found: Transaction 09f5e19b-5a30-428d-95f4-ff93590f3c071 is not associated with project 522d3ffe-0787-4bee-a616-dc12a19c9a76. Resource requested by the client was not found." }{ "code": "500", "error": "Internal Server Error", "reason": "Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76", "message": "The API encountered an unexpected condition which prevented it from fulfilling the request.", "description": "[500] Internal Server Error: Error creating project: 522d3ffe-0787-4bee-a616-dc12a19c9a76." }
Create a new space
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
On Public Cloud user is required to provide Cloud Object Storage instance details in the 'storage' property. On private CPD installations the default storage is used instead.
POST /v2/spaces
Request
Input payload for the space.
Name of space.
Description of space.
Cloud Object Storage instance is required for spaces created on Public Cloud. On private CPD installations default storage is used instead. This flag is not supported on CPD.
This flag is not supported on CPD.
User-defined tags associated with a space.
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.
Possible values: 8 ≤ length ≤ 50
Example:
Spaces-API_Swagger-DocsSpace production and stage name.
Space type.
Allowable values: [
cpd,wx,wca]Default:
cpd
Request
Query Parameters
Token representing first resource.
The number of resources returned. Default value is 100. Max value is 200.
Include details about total number of resources. This flag is not supported on CPD 3.0.1.
Comma-separated list of ids to be returned. This flag is not supported on CPD 3.0.1.
A list of comma-separated, user-defined tags to use to filter the query results.
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)
Filters the result list to only include spaces where the user with a matching user id is a member.
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
Filtering by bss_account_id is allowed only for accredited services.
Filters the result list to only include space with specified name.
Example:
name=QAFilters the result list to only include spaces which name contains specified case-insensitive substring
Example:
sub_name=substringFilters the result list to only include spaces with specified compute.crn.
Example:
compute.crn=crn:v1:staging:public:pm-20-devops:us-south:a/eb484b0080c04ee0b0889afd679273bd:a8f87602-b71a-4085-95d2-3027873352b3::Filters the result list to only include space with specified type
Example:
type=cpd
Response
Information for paging when queerying resources.
Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
- first
The uri of the first resource returned.
A reference to the first item of the next page, if any.
- next
The uri of the next set of resources.
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
No Sample Response
Update the space
Partially update this space. Allowed paths are:
- /name
- /description
- /compute
- /stage/name
- /type
PATCH /v2/spaces/{space_id}Request
Path Parameters
The space identification.
Input payload for the space.
The patch operation.
Allowable values: [
add,remove,replace,move,copy,test]A path relative to the entity object.
The value to be used within the operations (string, number, boolean, array or object).
A string containing a JSON Pointer value.
Retrieve the space members
Retrieves the member list for the specified space.
GET /v2/spaces/{space_id}/membersRequest
Path Parameters
The space identification.
Query Parameters
Token representing first resource.
The number of resources returned. Default value is 100. Max value is 200.
Include details about total number of resources. This flag is not supported on CPD 3.0.1.
Find the member by 'type'.
Find the member by 'role'.
Find the member by 'state'.
Response
Information for paging when queerying resources.
Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
- first
The uri of the first resource returned.
A reference to the first item of the next page, if any.
- next
The uri of the next set of resources.
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
No Sample Response
Retrieve the space member information
Retrieves the member information for the member and space with the specified identifiers.
GET /v2/spaces/{space_id}/members/{member_id}Response
The role of the space member.
Possible values: [
viewer,editor,admin]The IAM ID of the space member. This field is required for space members with the 'active' state.
The state of the space member. This field is only supported for members of type 'user'.
Possible values: [
active,pending]The space member type.
Possible values: [
user,service,group]
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
No Sample Response
Update the space member
Partially update the member selected with the specified identifier. Allowed paths are:
- /role
- /state
PATCH /v2/spaces/{space_id}/members/{member_id}Request
Path Parameters
The space identification.
The member identification.
The json patch.
The patch operation.
Allowable values: [
add,remove,replace,move,copy,test]A path relative to the entity object.
The value to be used within the operations (string, number, boolean, array or object).
A string containing a JSON Pointer value.
Response
The role of the space member.
Possible values: [
viewer,editor,admin]The IAM ID of the space member. This field is required for space members with the 'active' state.
The state of the space member. This field is only supported for members of type 'user'.
Possible values: [
active,pending]The space member type.
Possible values: [
user,service,group]
Status Code
Partially updated a member.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
No Sample Response
Retrieve the asset exports
Retrieves the asset export list for the specified space, project, or catalog.
GET /v2/asset_exports
Request
Query Parameters
Return resources pertaining to this space. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fReturn resources pertaining to this project. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84This parameter is only supported on CPD 3.5. Return resources pertaining to this catalog. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84Token representing first resource.
The number of resources returned. Default value is 100. Max value is 200.
Response
Information for paging when queerying resources.
Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
- first
The uri of the first resource returned.
A reference to the first item of the next page, if any.
- next
The uri of the next set of resources.
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
No Sample Response
Start the asset export process
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.
POST /v2/asset_exports
Request
Query Parameters
Return resources pertaining to this space. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fReturn resources pertaining to this project. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84This parameter is only supported on CPD 3.5. Return resources pertaining to this catalog. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84
Export information.
- Examples:
{ "all_assets": false, "asset_ids": [ "13a53931-a8c0-4c2f-8319-c793155e7517", "13a53931-a8c0-4c2f-8319-c793155e7518", "13a53931-a8c0-4c2f-8319-c793155e7518" ] } Encryption key used to encrypt the sensitive data during export.
Export format type.
Allowable values: [
json,csv]Default:
json
Cancel the asset export process
Cancels the asset export process with the specified identifier.
DELETE /v2/asset_exports/{export_id}Request
Path Parameters
The export identification.
Query Parameters
Return resources pertaining to this space. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fReturn resources pertaining to this project. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84This parameter is only supported on CPD 3.5. Return resources pertaining to this catalog. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84Default is false.
Default:
false
Retrieve the asset export
Retrieves the asset export with the specified identifier.
GET /v2/asset_exports/{export_id}Request
Path Parameters
The export identification.
Query Parameters
Return resources pertaining to this space. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fReturn resources pertaining to this project. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84This parameter is only supported on CPD 3.5. Return resources pertaining to this catalog. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84
Download the asset export content
Downloads the content for the asset export process with the specified identifier.
GET /v2/asset_exports/{export_id}/contentRequest
Path Parameters
The export identification.
Query Parameters
Return resources pertaining to this space. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fReturn resources pertaining to this project. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84This parameter is only supported on CPD 3.5. Return resources pertaining to this catalog. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84
Retrieve the asset imports
Retrieves the asset import list for the specified space, project, or catalog.
GET /v2/asset_imports
Request
Query Parameters
Return resources pertaining to this space. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fReturn resources pertaining to this project. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84This parameter is only supported on CPD 3.5. Return resources pertaining to this catalog. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84Token representing first resource.
The number of resources returned. Default value is 100. Max value is 200.
Response
Information for paging when queerying resources.
Computed explicitly only when 'total_count=true' query parameter is present. This is in order to avoid performance penalties.
The number of items to return in each page.
Possible values: 1 ≤ value ≤ 200
Example:
10The reference to the first item in the current page.
- first
The uri of the first resource returned.
A reference to the first item of the next page, if any.
- next
The uri of the next set of resources.
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
No Sample Response
Start the asset import process
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.
POST /v2/asset_imports
Request
Custom Headers
Allowable values: [
multipart/form-data,application/zip]
Query Parameters
Return resources pertaining to this space. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fReturn resources pertaining to this project. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84This parameter is only supported on CPD 3.5. Return resources pertaining to this catalog. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84
Form Parameters
Archive with assets to be imported.
Encryption key used to decrypt the sensitive data during import.
Import format type.
Allowable values: [
json,csv]Default:
json
Cancel the asset import process
Cancels the asset import process with the specified identifier.
DELETE /v2/asset_imports/{import_id}Request
Path Parameters
The import identification.
Query Parameters
Return resources pertaining to this space. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fReturn resources pertaining to this project. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84This parameter is only supported on CPD 3.5. Return resources pertaining to this catalog. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84Default is false.
Default:
false
Retrieve the asset import
Retrieves the asset import with the specified identifier.
GET /v2/asset_imports/{import_id}Request
Path Parameters
The import identification.
Query Parameters
Return resources pertaining to this space. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
63dc4cf1-252f-424b-b52d-5cdd9814987fReturn resources pertaining to this project. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84This parameter is only supported on CPD 3.5. Return resources pertaining to this catalog. Either 'space_id', 'project_id', 'catalog_id' query parameter has to be given and is mandatory.
Example:
1dd2aaec-781a-4712-a7ff-ae1862cf7a84
Get list of jobs under a project or a space.
Lists the jobs in the specified project or space (either project_id or space_id must be set).
GET /v2/jobs
Request
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Optionally get all jobs associated with a particular asset.
Optionally get all jobs associated with the particular asset ref type.
The ID of the job run. Can be used to search parent job of a job run
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Default:
100The 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
Example:
204Array of all jobs.
Status Code
Success.
Bad request. See the error message for details.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
The resources you specified cannot be found.
An error occurred. See response for more information.
No Sample Response
Create a new job.
Creates a new job in the specified project or space (either project_id or space_id must be set).
POST /v2/jobs
Request
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
The job to be created. Note: either asset_ref or asset_ref_type must be provided, not both.
- job
The name of the job
Example:
NameID of associated asset to run (provide either asset_ref or asset_ref_type).
Example:
ff1ab70b-0553-409a-93f9-ccc31471c218The type of asset to run (provide either asset_ref or asset_ref_type).
Example:
notebookThe description of the job.
Example:
Description.A cron string defining when the job should be run. If an empty string is provided it means the job is not scheduled to run.
Example:
0 0 1 * *- schedule_info
Indicate a repeated job
Example:
trueA timestamp in epoch time, the scheduled job will be triggered after this timestamp.
Example:
1547578689512A timestamp in epoch time, the scheduled job will be triggered before this timestamp.
Example:
1547578689512
A globally unique attribute to be used in place of the job id when sending calls. Must be a combination of lowercase alphanumeric and underscore characters, and must be between 1 and 36 characters.
Example:
my_job_1_2_3- retention_policy
Array of job parameters.
Array of parameter sets.
Response
AssetMetadata Model
The underlying job definition.
Status Code
Created.
Bad request. See the error message for details.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
Get the information of job identified by the ID.
Gets the info for a single job associated from the specified project or space (either project_id or space_id must be set).
GET /v2/jobs/{job_id}Request
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Response
AssetMetadata Model
The underlying job definition.
Status Code
Success.
Bad request. See the error message for details.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
The resources you specified cannot be found.
An error occurred. See response for more information.
No Sample Response
Delete a specific job.
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.
DELETE /v2/jobs/{job_id}Request
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Response
Status Code
The requested operation completed successfully.
Bad request. See the error message for details.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
The resources you specified cannot be found.
An error occurred. See response for more information.
No Sample Response
Update information of a job.
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.
PATCH /v2/jobs/{job_id}Request
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Updates to make to the job run.
The operation to be performed. Allowable values: [add, replace].
Example:
replaceA JSON pointer to the field to update. Allowable field paths to be updated. Ex /metadata/name or /entity/job/configuration
Example:
/metadata/name (or /entity/job/configuration)
Response
AssetMetadata Model
The underlying job definition.
Status Code
Success.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
The resources you specified cannot be found.
An error occurred. See response for more information.
No Sample Response
Get the availability of a given 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.
GET /v2/jobs/serving_name/{serving_name}Get list of runs of a job.
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.
GET /v2/jobs/{job_id}/runsRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
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.
The limit of the number of items to return, for example limit=50. If not specified a default of 100 will be used.
Default:
100A list of comma-separated job run states. Availble values: Completed, Failed, Canceled, Starting, Running, Queued, Canceling, Paused, Resuming, CompletedWithWarnings, CompletedWithErrors
Allowable values: [
Queued,Starting,Running,Paused,Resuming,Canceling,Canceled,Failed,Completed,CompletedWithErrors,CompletedWithWarnings]
Start a run for a job.
Starts the specified job contained in a project or space (either project_id or space_id must be set).
POST /v2/jobs/{job_id}/runsRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
The configuration of the job run to use. If not provided, use the configuration of the associated job.
- job_run
The name of the job run
Example:
NameThe description of the job run
Example:
Description- configuration
The environment variables, only for Notebook and Script jobs.
Examples:[ "key1=value1", "key2=value2" ]
Array of job parameters.
Array of parameter sets.
Response
AssetJobRunMetadata Model
Status Code
The requested operation completed successfully.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
Get a specific run of a job.
Gets the info for a single job run from the specified project or space (either project_id or space_id must be set).
GET /v2/jobs/{job_id}/runs/{run_id}Request
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Delete a run.
Delete the specified job run in a project or space (either project_id or space_id must be set).
DELETE /v2/jobs/{job_id}/runs/{run_id}Request
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
Response
Status Code
The requested operation is in progress.
The requested operation completed successfully.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
The resources you specified cannot be found.
An error occurred. See response for more information.
No Sample Response
Retrieve runtime log of a run.
Gets the logs for a job run in the specified project or space (either project_id or space_id must be set)
GET /v2/jobs/{job_id}/runs/{run_id}/logsRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
The limit of the number of lines to return, for example limit=50. If not specified, all log will be returned.
Response
Response of get job run log
Array of log string split by line
Examples:[ "Size: 28 Blocks: 0 IO Block: 4096 directory", "Device: 3000eeh/3145966d Inode: 453833649 Links: 3", "Access: (0755/drwxr-xr-x) Uid: ( 0/ root) Gid: ( 0/ root)", "Access: 2019-04-08 19:12:21.930122905 +0000", "Modify: 2019-04-08 19:12:21.932122894 +0000", "Change: 2019-04-08 19:12:21.932122894 +0000", "DONE" ]Total number of lines available
Example:
100
Status Code
Success.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
Cancel a run.
Cancels a job run that is in the running state.
POST /v2/jobs/{job_id}/runs/{run_id}/cancelRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
An empty body.
Example: {}
Response
Status Code
The requested operation completed successfully.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
Pause a run.
Pauses a job run that is in the running state.
POST /v2/jobs/{job_id}/runs/{run_id}/pauseRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
An empty body.
Example: {}
Response
Status Code
The requested operation completed successfully.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
Resume a run.
Resumes a job run that is in the paused state.
POST /v2/jobs/{job_id}/runs/{run_id}/resumeRequest
Path Parameters
The ID of the job to use. Each job has a unique ID. Alternatively, the serving_name value can be used.
The ID of the job run.
Query Parameters
Set to true for calls in git-based projects.
Default:
falseThe ID of the project to use. project_id or space_id is required.
The ID of the space to use. project_id or space_id is required.
An empty body.
Example: {}
Response
Status Code
The requested operation completed successfully.
You are not authorized to access the service. See response for more information.
You are not permitted to perform this action. See response for more information.
An error occurred. See response for more information.
No Sample Response
List 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.
GET /v2/environments
Request
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4Comma-separated list of environment types. Defaults to list of all types.
Example:
notebook,wml_flowComma-separated list of environment types. Takes precedence over types. Defaults to empty list.
Example:
notebook,wml_flowComma-separated list of kernel languages. Defaults to empty list.
Example:
python2,python3Comma-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.
Example:
2.3,2.4
Response
A list of environments.
Size of the list.
Example:
1An array of environments.
Status Code
Success. Returned a list of environments. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "total_results": 1, "resources": [ { "metadata": { "name": "my notebook environment", "description": "this is my notebook environment", "asset_type": "environment", "asset_id": "656ca7c3-d971-42c3-918b-a15023cd6b8e", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-10-12T09:18:34Z", "href": "/v2/environments/656ca7c3-d971-42c3-918b-a15023cd6b8e" }, "entity": { "environment": { "sub_type": "notebook", "display_name": "My Notebook Environment", "hardware_specification": { "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } }, "worker_pool": { "id": 12345678990, "provider": "ibm" } } } } }, "software_specification": { "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } }, "tools_specification": { "supported_kernels": [ { "name": "python3", "language": "python", "version": 3.9, "display_name": "Python 3.9" } ] }, "spec_type": "referenced" } } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Create a new environment.
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
POST /v2/environments
Request
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4
Specification of the environment to be created.
Create an environment
{
"type": "notebook",
"name": "my notebook environment",
"description": "this is my notebook environment",
"display_name": "My Notebook Environment",
"hardware_specification": {
"guid": "2d5191ba-ff9b-4b48-a852-948d49dd9210"
},
"software_specification": {
"guid": "555bd074-cc5b-4396-a7f8-5f03d336a8e5"
},
"tools_specification": {
"supported_kernels": [
{
"name": "python3",
"language": "python",
"version": 3.9,
"display_name": "Python 3.9"
}
]
}
}Type of the environment.
Allowable values: [
notebook,wml_flow,rstudio,default_spark,remote_spark,jupyterlab,remote_yarn,datastage,profiling,modeler,data_privacy,pipelines]Example:
notebookName of the environment.
Example:
my notebook environmentDisplay name of the environment.
Example:
My Notebook EnvironmentA pointer to a hardware specification that was defined elsewhere.
A pointer to a software specification that was defined elsewhere.
Description of the environment.
Example:
this is my notebook environmentEnvironment variables for the environment.
Examples:{ "key1": "value1", "key2": "value2" }Configuration variables for the environment.
Examples:{ "key1": "value1", "key2": "value2" }Tools specification of the environment.
Response
Environment with references to external hardware and software specifications.
Environment metadata.
Environment entity.
Status Code
Success. Created and returned a new environment asset. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
The number of requests has exceeded the rate limit.
{ "metadata": { "name": "my notebook environment", "description": "this is my notebook environment", "asset_type": "environment", "asset_id": "656ca7c3-d971-42c3-918b-a15023cd6b8e", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-10-12T09:18:34Z", "href": "/v2/environments/656ca7c3-d971-42c3-918b-a15023cd6b8e" }, "entity": { "environment": { "sub_type": "notebook", "display_name": "My Notebook Environment", "hardware_specification": { "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } }, "worker_pool": { "id": 12345678990, "provider": "ibm" } } } } }, "software_specification": { "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } }, "tools_specification": { "supported_kernels": [ { "name": "python3", "language": "python", "version": 3.9, "display_name": "Python 3.9" } ] }, "spec_type": "referenced" } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "rate_limit", "message": "The requests from IBMid-310000A00A exceeds rate limit. Please try again later." } ] }
Retrieve an environment.
Returns an environment of a given ID. You need to specify either project_id or space_id.
GET /v2/environments/{environment_guid}Request
Path Parameters
The guid of the environment.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4Format the response. Defaults to none.
Example:
default_sparkWhether to include conda_yml file content of custom package extensions in the response. Defaults to false.
Response
Environment with references to external hardware and software specifications.
Environment metadata.
Environment entity.
Status Code
Success. Returned the environment. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my notebook environment", "description": "this is my notebook environment", "asset_type": "environment", "asset_id": "656ca7c3-d971-42c3-918b-a15023cd6b8e", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-10-12T09:18:34Z", "href": "/v2/environments/656ca7c3-d971-42c3-918b-a15023cd6b8e" }, "entity": { "environment": { "sub_type": "notebook", "display_name": "My Notebook Environment", "hardware_specification": { "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } }, "worker_pool": { "id": 12345678990, "provider": "ibm" } } } } }, "software_specification": { "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } }, "tools_specification": { "supported_kernels": [ { "name": "python3", "language": "python", "version": 3.9, "display_name": "Python 3.9" } ] }, "spec_type": "referenced" } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Delete an environment.
Deletes an environment of a given ID. You need to specify either project_id or space_id.
DELETE /v2/environments/{environment_guid}Request
Path Parameters
The guid of the environment.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4
Response
Status Code
Success. The environment is deleted.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Update an environment.
Updates an environment of a given ID with the provided parameters. Returns the environment with updated properties. Only custom environments can be updated.
PATCH /v2/environments/{environment_guid}Request
Path Parameters
The guid of the environment.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4
Specification of changes.
Update an environment
{
"/metadata/name": "my updated notebook environment",
"/metadata/description": "this is my updated notebook environment",
"/entity/environment/display_name": "My Updated Notebook Environment",
"/entity/environment/hardware_specification": {
"guid": "2d5191ba-ff9b-4b48-a852-948d49dd9210"
},
"/entity/environment/software_specification": {
"guid": "555bd074-cc5b-4396-a7f8-5f03d336a8e5"
},
"/entity/environment/environment_variables": {
"key1": "value1",
"key2": "value2"
},
"/entity/environment/config_variables": {
"key3": "value3",
"key4": "value4"
},
"/entity/environment/tools_specification": {
"supported_kernels": [
{
"name": "python3",
"language": "python",
"version": 3.9,
"display_name": "Python 3.9"
}
]
}
}Name of the environment.
Example:
my updated notebook environmentDescription of the environment.
Example:
this is my updated notebook environmentDisplay name of the environment.
Example:
My Updated Notebook EnvironmentA pointer to a hardware specification that was defined elsewhere.
A pointer to a software specification that was defined elsewhere.
Environment variables for the environment.
Examples:{ "key1": "value1", "key2": "value2" }Config variables for the environment.
Examples:{ "key3": "value3", "key4": "value4" }Tools specification of the environment.
Response
Status Code
Success. Updated the environment.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
List hardware specifications.
Returns a list of hardware specifications.
- If neither
project_idnorspace_idis given, it returns all global hardware specifications. - If
project_idorspace_idis given, it returns all global and scoped hardware specifications. In this case, you need to specify eitherproject_idorspace_id.
GET /v2/hardware_specifications
Request
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The name of the hardware specification. If specified, each of the hardware specification in the returned list will have the specified name.
Response
A list of hardware specifications.
Number of items in the list.
Example:
1An array of hardware specifications.
Status Code
Success. Returned a list of hardware specifications. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "total_results": 1, "resources": [ { "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } }, "worker_pool": { "id": 12345678990, "provider": "ibm" } } } } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Create a new hardware specification.
Returns a hardware specification created with provided parameters.
You need to specify either project_id or space_id.
You can only provide exactly one of nodes, spark or datastage in the request body.
POST /v2/hardware_specifications
Request
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4
Specification of the hardware specification to be created.
Create a hardware specification for nodes
{
"name": "my hardware specification",
"description": "this is my hardware specification",
"nodes": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
},
"gpu": {
"num_gpu": 2,
"name": "v100",
"gpu_profile": "generic",
"mig_profile": "N/A"
},
"num_nodes": 1,
"num_drivers": 1,
"drivers": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
}
},
"worker_pool": {
"id": 12345678990,
"provider": "ibm"
}
}
}Create a hardware specification for Spark
{
"name": "my hardware specification",
"description": "this is my hardware specification",
"spark": {
"num_drivers": 1,
"num_executors": 2,
"driver": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
}
},
"executor": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
}
}
}
}Create a hardware specification for DataStage
{
"name": "my hardware specification",
"description": "this is my hardware specification",
"datastage": {
"num_conductors": 1,
"num_computes": 2,
"conductor": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
}
},
"compute": {
"cpu": {
"units": "100m",
"model": "string"
},
"mem": {
"size": "8Gi"
}
},
"instance": "instance-1"
}
}Name of hardware specification.
Example:
my hardware specificationDescription of hardware specification.
Example:
this is my hardware specificationHardware specification nodes main entity.
- One of
Response
A hardware specification.
Hardware specification metadata.
Hardware specification main entity.
Status Code
Success. Created and returned a new hardware specification asset. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
Conflict. Specification already exists with given name. Restriction applicable only for global specifications.
{ "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } }, "worker_pool": { "id": 12345678990, "provider": "ibm" } } } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "conflict", "message": "Document already exists." } ] }
Retrieve a hardware specification.
Returns a hardware specification of a given ID.
- To retrieve a global hardware specification,
project_idorspace_idis not required. - To retrieve a scoped hardware specification that is scoped to a project or a space, you need to specify either
project_idorspace_id.
GET /v2/hardware_specifications/{hardware_specification_guid}Request
Path Parameters
The guid of the hardware specification.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4
Response
A hardware specification.
Hardware specification metadata.
Hardware specification main entity.
Status Code
Success. Returned the hardware specification. Format follows v2/assets.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } }, "worker_pool": { "id": 12345678990, "provider": "ibm" } } } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Delete a hardware specification.
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.
DELETE /v2/hardware_specifications/{hardware_specification_guid}Request
Path Parameters
The guid of the hardware specification.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4
Response
Status Code
Success. The hardware specification is deleted.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Update a hardware specification.
Updates a hardware specification of a given ID with the provided parameters.
Only scoped hardware specifications can be updated through the API.
PATCH /v2/hardware_specifications/{hardware_specification_guid}Request
Path Parameters
The guid of the hardware specification.
Example:
a1da1d73-5eb5-4dfb-808e-174eb153c20e
Query Parameters
The guid of the project.
Example:
92ae0e27-9b11-4de9-a646-d46ca3c183d4
Specification of changes.
Update a hardware specification for nodes
{
"/metadata/name": "my hardware specification",
"/metadata/description": "this is my hardware specification",
"/entity/hardware_specification/nodes/cpu/units": "100m",
"/entity/hardware_specification/nodes/cpu/model": "string",
"/entity/hardware_specification/nodes/mem/size": "8Gi",
"/entity/hardware_specification/nodes/gpu/num_gpu": 2,
"/entity/hardware_specification/nodes/gpu/name": "v100",
"/entity/hardware_specification/nodes/num_nodes": 1,
"/entity/hardware_specification/nodes/worker_pool/id": 12345678990,
"/entity/hardware_specification/nodes/worker_pool/provider": "ibm"
}Update a hardware specification for Spark
{
"/metadata/name": "my hardware specification",
"/metadata/description": "this is my hardware specification",
"/entity/hardware_specification/spark/num_drivers": 1,
"/entity/hardware_specification/spark/num_executors": 2,
"/entity/hardware_specification/spark/driver/cpu/units": "100m",
"/entity/hardware_specification/spark/driver/cpu/model": "string",
"/entity/hardware_specification/spark/driver/mem/size": "8Gi",
"/entity/hardware_specification/spark/executor/cpu/units": "100m",
"/entity/hardware_specification/spark/executor/cpu/model": "string",
"/entity/hardware_specification/spark/executor/mem/size": "8Gi"
}Update a hardware specification for DataStage
{
"/metadata/name": "my hardware specification",
"/metadata/description": "this is my hardware specification",
"/entity/hardware_specification/datastage/num_conductors": 1,
"/entity/hardware_specification/datastage/num_computes": 2,
"/entity/hardware_specification/datastage/conductor/cpu/units": "100m",
"/entity/hardware_specification/datastage/conductor/cpu/model": "string",
"/entity/hardware_specification/datastage/conductor/mem/size": "8Gi",
"/entity/hardware_specification/datastage/compute/cpu/units": "100m",
"/entity/hardware_specification/datastage/compute/cpu/model": "string",
"/entity/hardware_specification/datastage/compute/mem/size": "8Gi",
"/entity/hardware_specification/datastage/instance": "instance-1"
}Name of the hardware specification.
Example:
my hardware specificationDescription of the hardware specification.
Example:
this is my hardware specificationBody parameters to update a nodes hardware specification.
- One of
Response
A hardware specification.
Hardware specification metadata.
Hardware specification main entity.
Status Code
Success. Updated the hardware specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my hardware specification", "description": "this is my hardware specification", "asset_type": "hardware_specification", "asset_id": "2d5191ba-ff9b-4b48-a852-948d49dd9210", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/hardware_specifications/2d5191ba-ff9b-4b48-a852-948d49dd9210" }, "entity": { "hardware_specification": { "nodes": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" }, "gpu": { "num_gpu": 2, "name": "v100", "gpu_profile": "generic", "mig_profile": "N/A" }, "num_nodes": 1, "num_drivers": 1, "drivers": { "cpu": { "units": "100m", "model": "string" }, "mem": { "size": "8Gi" } }, "worker_pool": { "id": 12345678990, "provider": "ibm" } } } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
List software specifications.
Returns a list of software specifications.
- If neither
project_idnorspace_idis given, it returns all base software specifications. - If
project_idorspace_idis given, it returns all base and derived software specifications. In this case, you need to specify eitherproject_idorspace_id.
GET /v2/software_specifications
Request
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519eString 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.
Example:
pytorch,scikit-learnThe name of the software specification. If specified, each of the software specification in the returned list will have the specified name.
Response
A list of software specifications.
Number of results.
Example:
1An array of software specifications.
Status Code
Success. Returned a list of software specifications.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "total_results": 1, "resources": [ { "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Create a new software specification.
Returns a software specification created with provided parameters.
You need to specify either project_id or space_id.
The parameters name and base_software_specification are required in the request body.
You can customize the software specification by adding any number of package extensions.
POST /v2/software_specifications
Request
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project in which to create the software specification.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Specification of the software specification to be created.
Create a derived software specification
{
"name": "my software specification",
"description": "this is my software specification",
"package_extensions": [
{
"guid": "b82b95df-fc3e-4273-98f7-473d62a03c2b"
}
],
"base_software_specification": {
"guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194"
}
}Name of the software specification.
Example:
my software specificationDescription of the software specification.
Example:
this is my software specificationPackage extensions of the software specification.
Payload for creating a new derived software specification.
- One of
Response
A software specification.
The software specification metadata.
Software specification entity.
Status Code
Success. Created and returned a new software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
Conflict. Specification already exists with given name. Restriction applicable only for global specifications.
{ "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "conflict", "message": "Document already exists." } ] }
Update a software specification.
Updates a software specification of a given ID with the provided parameters.
Only derived software specifications can be updated through the API.
Updatable fields are name, description, display_name and package_extensions.
You need to specify either project_id or space_id.
PATCH /v2/software_specifications/{software_specification_guid}Request
Path Parameters
A UUID v4 identifying the software specification.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Specification of the updates for a software specification.
Update a software specification
{
"/metadata/name": "my updated software specification",
"/metadata/description": "this is my updated software specification.",
"/entity/software_specification/display_name": "My Updated Software Specification.",
"/entity/software_specification/package_extensions": [
{
"guid": "b82b95df-fc3e-4273-98f7-473d62a03c2b"
}
]
}Name of the software specification.
Example:
my updated software specificationDescription of the software specification.
Example:
this is my updated software specification.Display name of the software specification.
Example:
My Updated Software Specification.Package extension of the software specification.
Response
Status Code
Success. Updated the software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Retrieve a software specification.
Returns a software specification of a given ID.
- To retrieve a base software specification,
project_idorspace_idis not required. - To retrieve a derived software specification that is scoped to a project or a space, you need to specify either
project_idorspace_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.
GET /v2/software_specifications/{software_specification_guid}Request
Path Parameters
A UUID v4 identifying the software specification.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
A software specification.
The software specification metadata.
Software specification entity.
Status Code
Success. Returned the given software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my software specification", "description": "this is my software specification", "asset_type": "software_specification", "asset_id": "555bd074-cc5b-4396-a7f8-5f03d336a8e5", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z", "href": "/v2/software_specifications/555bd074-cc5b-4396-a7f8-5f03d336a8e5" }, "entity": { "software_specification": { "type": "derived", "display_name": "My Software Specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" }, "package_extensions": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ], "software_configuration": { "included_packages": [ { "name": "ipython", "version": "7.22.0" } ], "platform": { "name": "spark", "version": 3.2 }, "language": { "name": "python", "version": 3.9 } } } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Delete a software specification.
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.
DELETE /v2/software_specifications/{software_specification_guid}Request
Path Parameters
A UUID v4 identifying the software specification.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project. The deleted software specification must be scoped to the specified project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
Status Code
Success. Deleted the software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Add a package extension to a software specification.
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:
- The software specification identified by
software_specification_guidand the package extension identified bypackage_extension_guidexist in the same scope (either project or space). - A successful POST
/v2/package_extensions/{package_extension_guid}/upload_completehas been called before this request is initiated. I.e., the upload of the referencedpip_ziporconda_ymlfile has been indicated to have been successful. - The user is authorized to update the software specification asset.
PUT /v2/software_specifications/{software_specification_guid}/package_extensions/{package_extension_guid}Request
Path Parameters
A UUID v4 identifying the software specification.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2bA UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
Status Code
Success. Added the package extension to the software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
Conflict. The software specification already references this package extension.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Remove a package extension from a software specification.
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.
DELETE /v2/software_specifications/{software_specification_guid}/package_extensions/{package_extension_guid}Request
Path Parameters
A UUID v4 identifying the software specification.
Example:
c82b95df-fc3e-4273-98f7-473d62a03c2bA UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
Status Code
Success. Removed the package extension from the software specification.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
List package extensions.
Returns all package extensions within the given project or space. You need to specify either project_id or space_id.
GET /v2/package_extensions
Request
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519eReturning only those package extensions that have a particular name.
Example:
my Package ExtensionReturning only those package extensions that have a particular type.
Allowable values: [
conda_yml,pip_zip]Example:
conda_yml or pip_zip
Response
A list of package extensions.
The number of results.
Example:
1An array of package extensions.
Status Code
Success. Returned a list of Package Extensions.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "total_results": 1, "resources": [ { "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml" } } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Create a new package extension.
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.
POST /v2/package_extensions
Request
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project in which to create the package extension.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Specification of the package extension to be created.
Create a package extension
{
"name": "my package extension",
"description": "this is my package extension",
"type": "conda_yml",
"interpreter": "mamba"
}The name of the package extension. Should be unique.
Example:
my package extensionThe type of the package extension.
Allowable values: [
pip_zip,conda_yml]Example:
conda_ymlThe description of the package extension. Can be any string.
Example:
this is my package extensionThe interpreter of the package extension.
Allowable values: [
conda,mamba]Example:
mamba
Response
A package extension with signed URL.
The package extension metadata.
Package extension entity with signed URL.
Status Code
Success. Created and returned a new package extension.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "href": "/package_extension/Package_Extension_9GShiX8H0.yml" } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Mark file 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.
POST /v2/package_extensions/{package_extension_guid}/upload_completeRequest
Path Parameters
A UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
Status Code
Success. Marked the upload complete, the package extension is now usable.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Update a package extension.
Updates a package extension of a given ID with the provided parameters.
PATCH /v2/package_extensions/{package_extension_guid}Request
Path Parameters
A UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Specification of the updates for a package extension.
Update a package extension
{
"/metadata/name": "my updated package extension",
"/metadata/description": "this is my updated package extension",
"/entity/package_extension/type": "pip_zip"
}The name of the package extension.
Example:
my updated package extensionA description of the package extension.
Example:
this is my updated package extensionThe type of the package extension. One would not normally want to change it.
Allowable values: [
conda_yml,pip_zip]Example:
pip_zip
Response
Status Code
Success. Updated the pacakge extension.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Retrieve a package extension.
Retrieves a package extension of a given ID. You need to specify either project_id or space_id.
GET /v2/package_extensions/{package_extension_guid}Request
Path Parameters
A UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
A package extension with object key and signed URL.
The package extension metadata.
Package extension entity with object key and signed URL.
Status Code
Success. Returned the given package extension.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "metadata": { "name": "my package extension", "description": "this is my package extension", "asset_type": "package_extension", "asset_id": "461db2c9-effb-4bfb-8319-f4acf8ba06a3", "project_id": "b275be5f-10ff-47ee-bfc9-63f1ce5addbf", "space_id": "1fd6d4b5-d592-4de2-a3e6-ae53a42d75d0", "owner_id": "IBMid-310000SG2Y", "created_at": "2021-08-02T12:00:24.269Z", "updated_at": "2021-08-02T12:00:24.269Z" }, "entity": { "package_extension": { "type": "conda_yml", "interpreter": "mamba", "object_key": "package_extension/Package_Extension_9GShiX8H0.yml", "href": "/package_extension/Package_Extension_9GShiX8H0.yml" } } }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Delete a package extension.
Deletes a package extension of a given ID. You need to specify either project_id or space_id.
DELETE /v2/package_extensions/{package_extension_guid}Request
Path Parameters
A UUID v4 identifying the package extension.
Example:
b82b95df-fc3e-4273-98f7-473d62a03c2b
Query Parameters
The guid of the space.
Example:
82ae0e27-9b11-4de9-a646-d46ca3c183d4The guid of the project.
Example:
103d3fc4-2e46-4581-a23a-b4484e13519e
Response
Status Code
Success. Deleted the package extension.
Bad request. One of the fields has invalid format/content.
Unauthorized. No/Malformed authentication provided.
Forbidden. User is not allowed to perform the target operation.
{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_type", "message": "The `project_id` field needs to be a uuid v4, but is 12345.", "target": { "type": "field", "name": "project_id" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "invalid_auth_token", "message": "The IAM bearer token is not valid.", "target": { "type": "header", "name": "Authentication" } } ] }{ "trace": "b12692e1-8582-4628-88ca-7a13fefb73e2", "errors": [ { "code": "endpoint_access_forbidden", "message": "max.mustermann@ibm.com is neither editor/admin of project b275be5f-10ff-47ee-bfc9-63f1ce5addbf nor allowlisted Service ID." } ] }
Archive the asset container
Archive the assets database of the asset container.
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.
POST /v2/asset_containers/archive
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Archive request
Response
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Status Code
Accepted
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Get archive information of the asset container
Get archive information of the asset container.
GET /v2/asset_containers/archive_info
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Response
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Get configurations
Get the configurations of a catalog/project/space.
GET /v2/asset_containers/configurations
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Response
Action to take if duplicate assets are found for a given asset
Possible values: [
IGNORE,REJECT,REPLACE,UPDATE]Default duplicate detection strategy for assets of types that do not have duplicate detection strategy defined
Possible values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]Duplicate detection strategies of assets with specified asset types in this catalog/project/space
Authorize reporting in this catalog
Whether assets has to be purged on delete
Days after which assets has to be purged after soft delete
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
No Sample Response
Replace or create configurations
Replace the configurations of a catalog/project/space or create the configurations if they do not exist.
PUT /v2/asset_containers/configurations
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Configurations
Action to take if duplicate assets are found for a given asset
Allowable values: [
IGNORE,REJECT,REPLACE,UPDATE]Default duplicate detection strategy for assets of types that do not have duplicate detection strategy defined
Allowable values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]Duplicate detection strategies of assets with specified asset types in this catalog/project/space
Authorize reporting in this catalog
Whether assets has to be purged on delete
Days after which assets has to be purged after soft delete
Response
Action to take if duplicate assets are found for a given asset
Possible values: [
IGNORE,REJECT,REPLACE,UPDATE]Default duplicate detection strategy for assets of types that do not have duplicate detection strategy defined
Possible values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]Duplicate detection strategies of assets with specified asset types in this catalog/project/space
Authorize reporting in this catalog
Whether assets has to be purged on delete
Days after which assets has to be purged after soft delete
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Restore the asset container
Restore the assets database of the archived asset container. Only successfully archived asset container can be restored.
POST /v2/asset_containers/restore
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Response
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Status Code
OK
Accepted
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
List all asset lists defined for an account
Retrieve a paginated list of asset lists defined for an account.
GET /v2/asset_lists
Request
Query Parameters
Query to retrieve a paginated list of asset list metadatas for which the request user has permission to view.
Search query in Common Expression Language, with special characters encoded. For example, & is %26.
Examples of query parameters:
* id
* type
* state
* access_control.owner
* created_at
* last_updated_atPossible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$%&=|\(\)\s\-\_\^"]+$Example:
type==order%26%26created_at%3E=2023-08-23T21:10:40ZStart token for pagination
Possible values: 1 ≤ length ≤ 512, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Search result limit
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
10This parameter can be repeated to add additional sort fields.
Default: nullExamples of sort fields (these are case insensitive):
- created_at
- -created_at
- last_updated_at
- -last_updated_at
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$
curl --request GET --url '{url}/v2/asset_lists' --header 'authorization: Bearer {access_token}' --header 'accept: application/json'
Response
The Asset list collection response API model.
Collection of asset list results.
Possible values: 0 ≤ number of items ≤ 200
The limit on the number of results returned.
Example:
200The total count on the number of results returned, accounting for filtering but not pagination.
Example:
50A page in a pagination collection.
The next page in the collection.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
{ "limit": 200, "total_count": 1, "first": { "href": "https://api.dataplatform.cloud.ibm.com/v2/asset_lists" }, "next": { "href": "https://api.dataplatform.cloud.ibm.com/v2/asset_lists?start=start_token", "start": "start_token" }, "asset_lists": [ { "name": "my_order", "description": "Order of multiple items", "type": "order", "state": "default_state", "id": "3204c622-dcb8-4728-869f-484b6ac73dff", "asset": { "id": "701f4af4-679c-42d1-80b5-0de5796a7514", "type": "ibm_data_product_version", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08Z", "last_updated_at": "2023-09-17T23:19:08Z", "last_updated_by": "userId" } ] }
Create a new asset list
Use this API to creates a new asset list.
If the state is not specified, the asset list will be created in DEFAULT state.
The list may be created with items, or without items.
The list will be owned by the request user.
POST /v2/asset_lists
Request
The asset list for creation.
Example REST body for asset list creation of type ORDER.
{
"name": "my_order",
"description": "Order of multiple items",
"type": "order",
"items": [
{
"asset": {
"id": "8509d09e-b3d0-4e8b-9682-726a7b95f69a",
"type": "data_asset",
"container": {
"id": "71993ab5-3374-4355-8a38-fc4c32debc00",
"type": "catalog"
}
},
"properties": {
"my_property_1": "Value 1",
"my_property_2": "Value 2"
}
},
{
"asset": {
"id": "8509d09e-b3d0-4e8b-9682-726a7b95f69b",
"type": "data_asset",
"container": {
"id": "71993ab5-3374-4355-8a38-fc4c32debc00",
"type": "catalog"
}
},
"properties": {
"my_property_1": "Value 1",
"my_property_map": {
"my_property_map_key": "Value 2"
}
}
}
]
}Asset list name. A name can contain letters, numbers, understores, dashes, spaces or periods. Names are mutable and reusable.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
My wish listThe type of the asset list. Valid types are: ['order', 'cart', 'wishlist']
Allowable values: [
cart,wishlist,order]Example:
orderAn asset from a container.
The items in the asset list.
Possible values: 0 ≤ number of items ≤ 20
A description of the asset list.
Possible values: 1 ≤ length ≤ 4000, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
This list contains assets for project X.The state of the asset list. Valid states are: ['default_state', 'confirmed']. If not specified, the default value will be 'DEFAULT'.
Allowable values: [
default_state,received,under_review,ready_to_deliver,rejected,in_progress,partially_delivered,succeeded,failed,workflow_exception,cancelled,redeliver,reattempt,rerequest]Default:
default_stateExample:
default_stateA message used for communicating reasons for state changes.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
The reason for the state change.The properties of an asset list item.
curl --request POST --url '{url}/v2/asset_lists' --header 'accept: application/json' --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' --data '{"name": "my_order","description": "Order of multiple items","items": [{"asset": {"metadata": {"id": "8509d09e-b3d0-4e8b-9682-726a7b95f69a","type": "data_asset","container": {"id": "71993ab5-3374-4355-8a38-fc4c32debc00","type": "catalog"}}},"properties": {"my_property_1": "Value 1","my_property_2": "Value 2"}},{"asset": {"metadata": {"id": "8509d09e-b3d0-4e8b-9682-726a7b95f69b","type": "data_asset","container": {"id": "71993ab5-3374-4355-8a38-fc4c32debc00","type": "catalog"}}},"properties": {"my_property_1": "Value 1","my_property_map": {"my_property_map_key": "Value 2"}}}],"type": "order"}'
Response
The Asset list summary API model for retrieval.
The unique identifier of the asset list formatted either as a UUID or a special case such as cart_userID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69fRFC 3339 timestamp when the asset list was created (system managed).
Example:
2022-04-22T03:22:32ZRFC 3339 timestamp when the asset list was last updated (system managed).
Example:
2022-04-22T03:22:32ZThe user who last updated the asset list.
Example:
userIdAsset list name. A name can contain letters, numbers, understores, dashes, spaces or periods. Names are mutable and reusable.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
My wish listThe type of the asset list. Valid types are: ['order', 'cart', 'wishlist']
Possible values: [
cart,wishlist,order]Example:
orderThe state of the asset list. Valid states are: ['default_state', 'confirmed']. If not specified, the default value will be 'DEFAULT'.
Possible values: [
default_state,received,under_review,ready_to_deliver,rejected,in_progress,partially_delivered,succeeded,failed,workflow_exception,cancelled,redeliver,reattempt,rerequest]Example:
default_stateAn asset from a container.
Access control permissions for the asset list.
A description of the asset list.
Possible values: 1 ≤ length ≤ 4000, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
This list contains assets for project X.A message used for communicating reasons for state changes.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
The reason for the state change.The properties of an asset list item.
Status Code
Created
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
Internal Server Error
{ "name": "my_order", "description": "Order of multiple items", "type": "order", "state": "default_state", "id": "3204c622-dcb8-4728-869f-484b6ac73dff", "asset": { "id": "701f4af4-679c-42d1-80b5-0de5796a7514", "type": "ibm_data_product_version", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08Z", "last_updated_at": "2023-09-17T23:19:08Z", "last_updated_by": "userId" }
Delete asset lists
Deletes asset lists based on a query in Common Expression Language format.
DELETE /v2/asset_lists
Request
Query Parameters
Query to delete asset lists for which the request user has permission.
Search query in Common Expression Language, with special characters encoded. For example, & is %26.
Examples of query parameters:
* id
* type
* state
* access_control.owner
* created_at
* last_updated_atPossible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$%&=|\(\)\s\-\_\^"]+$Example:
type==order%26%26created_at%3E=2023-08-23T21:10:40Z
curl --request DELETE --url '{url}/v2/asset_lists?query=created_at%3E%3D2023-08-23T21%3A10%3A40Z' --header 'accept: application/json' --header 'authorization: Bearer {access_token}'
Retrieve an asset list identified by ID
Retrieves the metadata of an asset list of a given identified by ID.
GET /v2/asset_lists/{asset_list_id}Request
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72
curl --request GET --url '{url}/v2/asset_lists/{asset_list_id}' --header 'authorization: Bearer {access_token}' --header 'accept: application/json'
Response
The Asset list summary API model for retrieval.
The unique identifier of the asset list formatted either as a UUID or a special case such as cart_userID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69fRFC 3339 timestamp when the asset list was created (system managed).
Example:
2022-04-22T03:22:32ZRFC 3339 timestamp when the asset list was last updated (system managed).
Example:
2022-04-22T03:22:32ZThe user who last updated the asset list.
Example:
userIdAsset list name. A name can contain letters, numbers, understores, dashes, spaces or periods. Names are mutable and reusable.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
My wish listThe type of the asset list. Valid types are: ['order', 'cart', 'wishlist']
Possible values: [
cart,wishlist,order]Example:
orderThe state of the asset list. Valid states are: ['default_state', 'confirmed']. If not specified, the default value will be 'DEFAULT'.
Possible values: [
default_state,received,under_review,ready_to_deliver,rejected,in_progress,partially_delivered,succeeded,failed,workflow_exception,cancelled,redeliver,reattempt,rerequest]Example:
default_stateAn asset from a container.
Access control permissions for the asset list.
A description of the asset list.
Possible values: 1 ≤ length ≤ 4000, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
This list contains assets for project X.A message used for communicating reasons for state changes.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
The reason for the state change.The properties of an asset list item.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "name": "my_order", "description": "Order of multiple items", "type": "order", "state": "default_state", "id": "3204c622-dcb8-4728-869f-484b6ac73dff", "asset": { "id": "701f4af4-679c-42d1-80b5-0de5796a7514", "type": "ibm_data_product_version", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08Z", "last_updated_at": "2023-09-17T23:19:08Z", "last_updated_by": "userId" }
Delete an asset list identified by ID
Deletes an asset list identified by ID. The user must have permission to perform this action.
DELETE /v2/asset_lists/{asset_list_id}Request
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72
curl --request DELETE --url '{url}/v2/asset_lists/{asset_list_id}' --header 'accept: application/json' --header 'authorization: Bearer {access_token}'
Update the metadata of an asset list
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.
PATCH /v2/asset_lists/{asset_list_id}Request
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
Example REST body for asset list update of the state parameter.
[
{
"op": "replace",
"path": "/state",
"value": "confirmed"
}
]The Json patch path as defined by RFC 6902.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&/\(\)\s\-\_\^"]+$The Json patch from path as defined by RFC 6902.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&/\(\)\s\-\_\^"]+$The Json patch value.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$The Json patch operation as defined by RFC 6902.
Allowable values: [
add,replace,remove,move,copy,test]
curl --request PATCH --url '{url}/v2/asset_lists/{asset_list_id}' --header 'accept: application/json' --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' --data '[{"op": "replace","path": "/state","value": "confirmed"}]'
Response
The Asset list summary API model for retrieval.
The unique identifier of the asset list formatted either as a UUID or a special case such as cart_userID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69fRFC 3339 timestamp when the asset list was created (system managed).
Example:
2022-04-22T03:22:32ZRFC 3339 timestamp when the asset list was last updated (system managed).
Example:
2022-04-22T03:22:32ZThe user who last updated the asset list.
Example:
userIdAsset list name. A name can contain letters, numbers, understores, dashes, spaces or periods. Names are mutable and reusable.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
My wish listThe type of the asset list. Valid types are: ['order', 'cart', 'wishlist']
Possible values: [
cart,wishlist,order]Example:
orderThe state of the asset list. Valid states are: ['default_state', 'confirmed']. If not specified, the default value will be 'DEFAULT'.
Possible values: [
default_state,received,under_review,ready_to_deliver,rejected,in_progress,partially_delivered,succeeded,failed,workflow_exception,cancelled,redeliver,reattempt,rerequest]Example:
default_stateAn asset from a container.
Access control permissions for the asset list.
A description of the asset list.
Possible values: 1 ≤ length ≤ 4000, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
This list contains assets for project X.A message used for communicating reasons for state changes.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
The reason for the state change.The properties of an asset list item.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Conflict
Unsupported Media Type
Internal Server Error
{ "name": "my_order", "description": "Order of multiple items", "type": "order", "state": "default_state", "id": "3204c622-dcb8-4728-869f-484b6ac73dff", "asset": { "id": "701f4af4-679c-42d1-80b5-0de5796a7514", "type": "ibm_data_product_version", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08Z", "last_updated_at": "2023-09-17T23:19:08Z", "last_updated_by": "userId" }
List the items of an asset list identified by ID
Retrieves the list items of an asset list identified by ID.
GET /v2/asset_lists/{asset_list_id}/itemsRequest
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72
Query Parameters
Query to retrieve a paginated list of asset list items for which the request user has permission to view.
Search query in Common Expression Language, with special characters encoded. For example, & is %26.Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$%&=|\(\)\s\-\_\^"]+$Example:
properties.data_product_id==aaff9159-8ba4-4ae5-a9d7-3e59d5903d72%26%26created_at%3E=2023-08-23T21:10:40ZStart token for pagination
Possible values: 1 ≤ length ≤ 512, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Search result limit
Possible values: 1 ≤ value ≤ 200
Default:
200Example:
10This parameter can be repeated to add additional sort fields.
Default: nullExamples of sort fields (these are case insensitive):
- created_at
- -created_at
- last_update_time
- -last_update_time
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$
curl --request GET --url '{url}/v2/asset_lists/{asset_list_id}/items' --header 'accept: application/json' --header 'authorization: Bearer {access_token}'
Response
The Asset list item collection response API model.
Collection of asset list item results.
Possible values: 0 ≤ number of items ≤ 200
The limit on the number of results returned.
Example:
200The total count on the number of results returned, accounting for filtering but not pagination.
Example:
50A page in a pagination collection.
The next page in the collection.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "limit": 200, "total_count": 2, "first": { "href": "https://api.dataplatform.cloud.ibm.com/v2/asset_lists/3204c622-dcb8-4728-869f-484b6ac73dff/items" }, "next": { "href": "https://api.dataplatform.cloud.ibm.com/v2/asset_lists/3204c622-dcb8-4728-869f-484b6ac73dff/items?start=start_token", "start": "start_token" }, "items": [ { "asset": { "id": "8509d09e-b3d0-4e8b-9682-726a7b95f69a", "type": "data_asset", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "properties": { "my_property_1": "Value 1", "my_property_2": "Value 2" }, "id": "6357fce0-41ef-433b-95ee-03ade01bd02d", "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08Z", "last_updated_at": "2023-09-17T23:19:08Z", "last_updated_by": "userId", "asset_list": { "id": "3204c622-dcb8-4728-869f-484b6ac73dff" } }, { "asset": { "id": "8509d09e-b3d0-4e8b-9682-726a7b95f69b", "type": "data_asset", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "properties": { "my_property_1": "Value 1", "my_property_map": { "my_property_map_key": "Value 2" } }, "id": "cdaf6713-ede0-4a61-9fa4-d65467c59e9c", "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08Z", "last_updated_at": "2023-09-17T23:19:08Z", "last_updated_by": "userId", "asset_list": { "id": "3204c622-dcb8-4728-869f-484b6ac73dff" } } ] }
Retrieve an item in an asset list
Retrieves an item identified by ID of an asset list identified by ID.
GET /v2/asset_lists/{asset_list_id}/items/{asset_list_item_id}Request
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72Asset list item id (GUID)
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d73
curl --request GET --url '{url}/v2/asset_lists/{asset_list_id}/items/{asset_list_item_id}' --header 'accept: application/json' --header 'authorization: Bearer {access_token}'
Response
The Asset list item canonical API model.
The unique identifier of the asset list item formatted as a UUID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69fRFC 3339 timestamp when the asset list item was created (system managed).
Example:
2022-04-22T03:22:32ZRFC 3339 timestamp when the asset list item was last updated (system managed).
Example:
2022-04-22T03:22:32ZThe user who last updated the asset list item.
Example:
userIdThe reference to the asset list to which the item belongs.
- asset_list
The unique identifier of the asset list item formatted as a UUID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69f
An asset from a container.
Access control permissions for the asset list.
The properties of an asset list item.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
{ "asset": { "id": "8509d09e-b3d0-4e8b-9682-726a7b95f69a", "type": "data_asset", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "properties": { "my_property_1": "Value 1", "my_property_2": "Value 2" }, "id": "6357fce0-41ef-433b-95ee-03ade01bd02d", "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08Z", "last_updated_at": "2023-09-17T23:19:08Z", "last_updated_by": "userId", "asset_list": { "id": "3204c622-dcb8-4728-869f-484b6ac73dff" } }
Update an asset list item
Use this API to update an asset list item. Specify patch operations using http://jsonpatch.com/ syntax.
Fields that can be patched:
- /properties
PATCH /v2/asset_lists/{asset_list_id}/items/{asset_list_item_id}Request
Path Parameters
Asset list id (GUID, or [type]_[userId])
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d72Asset list item id (GUID)
Possible values: length = 36, Value must match regular expression
^[\w\.,:$&\(\)\s\-\_\^"]+$Example:
aaff9159-8ba4-4ae5-a9d7-3e59d5903d73
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
Example REST body for asset list item update of the properties map.
[
{
"op": "add",
"path": "/properties/my_prop",
"value": {
"key": "Val 1"
}
},
{
"op": "replace",
"path": "/properties/my_prop2",
"value": {
"key": "Val 2"
}
}
]The Json patch path as defined by RFC 6902.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&/\(\)\s\-\_\^"]+$The Json patch from path as defined by RFC 6902.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[\w\.,:$&/\(\)\s\-\_\^"]+$The Json patch value.
The Json patch operation as defined by RFC 6902.
Allowable values: [
add,replace,remove,move,copy,test]
curl --request PATCH --url '{url}/v2/asset_lists/{asset_list_id}/items/{asset_list_item_id}' --header 'accept: application/json' --header 'authorization: Bearer {access_token}' --header 'content-type: application/json' --data '[{"op": "add","path": "/properties/my_prop","value": {"key": "Val 1"}},{"op": "replace","path": "/properties/my_prop2/key","value": "Val 2"}]'
Response
The Asset list item canonical API model.
The unique identifier of the asset list item formatted as a UUID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69fRFC 3339 timestamp when the asset list item was created (system managed).
Example:
2022-04-22T03:22:32ZRFC 3339 timestamp when the asset list item was last updated (system managed).
Example:
2022-04-22T03:22:32ZThe user who last updated the asset list item.
Example:
userIdThe reference to the asset list to which the item belongs.
- asset_list
The unique identifier of the asset list item formatted as a UUID.
Example:
8509d09e-b3d0-4e8b-9682-726a7b95f69f
An asset from a container.
Access control permissions for the asset list.
The properties of an asset list item.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Unsupported Media Type
Internal Server Error
{ "asset": { "id": "8509d09e-b3d0-4e8b-9682-726a7b95f69a", "type": "data_asset", "container": { "id": "71993ab5-3374-4355-8a38-fc4c32debc00", "type": "catalog" } }, "properties": { "my_property_1": "Value 1", "my_property_2": "Value 2" }, "id": "6357fce0-41ef-433b-95ee-03ade01bd02d", "access_control": { "owner": "userId", "bss_account_id": "bss_account_id" }, "created_at": "2023-09-17T23:19:08Z", "last_updated_at": "2023-09-17T23:19:08Z", "last_updated_by": "userId", "asset_list": { "id": "3204c622-dcb8-4728-869f-484b6ac73dff" } }
Searches for 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_typeis 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_typeandrelated_asset_typeare 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_typeis 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_typeandrelated_asset_typeare 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_typeorrelated_asset_typeis set to*#_column, the results are limited to relationship types where one end can be used with any supported column type (currently limited todata_assetcolumns) - 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.
GET /v2/asset_relationship_types
Request
Query Parameters
Required when container_id is specified and the container is not a catalog. Specifies the type of the container (CATALOG/PROJECT/SPACE). Defaults to CATALOG.
Default:
CATALOGContainer ID. This limits results to relationship types that have an endpoint with the specified ID of a catalog, project, or space. If the container is a project or space, the container_type parameter must be also specified, otherwise container_id is treated as a catalog ID. This parameter is required when querying for relationship types associated with a catalog, project, or space. If this parameter is omitted, relationships types are not filtered by their container. Note that any type with an endpoint that has no container ID will also be included the result.
The parameter
type_nameis deprecated, please useasset_typeinsteadAsset Type Name(s). This limits the results to only relationship types that have an endpoint in the specified asset type list, or have an endpoint that is untyped.
Artifact Type Name(s). This limits the results to only relationship types that have an endpoint in the specified artifact type list, or have an endpoint that is untyped.
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 to use when finding relationship types
Default:
25Optional bookmark to use when finding relationship types.
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(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.
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.
If specified, the results are limited to relationship types that can be accessed by the specified BSS account. If
container_idis also specified, the catalog's BSS account must be the same as the BSS account specified here.If
bss_account_idis 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_idis not specified, and the API is called with a regular user (i.e. non-service ID) access token, then the result depends on whethercontainer_idis specified. Ifcontainer_idis specified, then the result includes global relationship types and account-scoped relationship types for the container's BSS account. Ifcontainer_idis not specified, then the result includes global relationship types, and account-scoped relationship types for all of the user's BSS accounts.
Creates an asset relationship type
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
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 |
POST /v2/asset_relationship_types
Request
Query Parameters
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_idquery 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.
Relationship Type request body
First relationship type endpoint (order is not important)
- end1
Default display name for this end of the relationship. This is what will be shown in the UI.
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.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Allowable values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Allowable values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Allowable values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Second relationship type endpoint (order is not important)
- end2
Default display name for this end of the relationship. This is what will be shown in the UI.
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.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Allowable values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Allowable values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Allowable values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Allowable values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Set of flags. These flags determine the relationship type's behavior
- flags
Description of the relationship type
Response
relationship type metadata
- metadata
Unique ID of the relationship type
ID of the user that created the relationship type
Creation timestamp in milliseconds
Creation timestamp in yyyy-MM-dd'T'HH:mm:ss.SSSX format
Update timestamp in milliseconds
Update timestamp in yyyy-MM-dd'T'HH:mm:ss.SSSX format
ID of the user that updated the relationship type
Tenancy of the relationship type
- tenancy
Possible values: [
GLOBAL,BSS_ACCOUNT]
relationship type entity
- entity
First relationship type endpoint (order is not important)
- end1
Default display name for this end of the relationship. This is what will be shown in the UI.
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.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Possible values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Possible values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Possible values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Second relationship type endpoint (order is not important)
- end2
Default display name for this end of the relationship. This is what will be shown in the UI.
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.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Possible values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Possible values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Possible values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Set of flags. These flags determine the relationship type's behavior
- flags
Description of the relationship type
Status Code
Created
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Request
No Sample Response
Searches for relationship type 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, orspace_id.
For a column type:
- set
asset_typeas<asset_type>#_column - if
asset_typeis 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
POST /v2/asset_relationship_types/search_ends
Request
Query Parameters
catalog_id. If no container parameters are set, any asset container the user has access to are allowed.
project_id. If no container parameters are set, any asset containers the user has access to are allowed.
space_id. If no container parameters are set, any asset containers the user has access to are allowed.
asset_type(s). This specifies the asset type(s) whose relationship type ends should be found. This parameter should be repeated for each allowed asset type.
artifact_type(s). This specifies the artifact type(s) whose relationship type ends should be found. This parameter should be repeated for each allowed artifact type.
end_types. This filters the result to only include relationship type ends of the specified type(s) - valid filter values are {ASSET, ARTIFACT, COLUMN}. If this parameter is not specified, all relationship ends that match other criteria will be returned.
Optional limit to use when finding relationship type ends
Default:
25Optional bookmark to use when finding relationship type ends.
orderby. This parameter can be repeated to add additional sort fields.
Default: relationship_display_name_ascSupported 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
Default:
relationship_display_name_ascLimits 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
- options
Possible values: contains only unique items
Possible values: contains only unique items
Possible values: [
ASSET,ARTIFACT,COLUMN]Possible values: [
RELATIONSHIP_NAME_ASC,RELATIONSHIP_NAME_DESC,RELATIONSHIP_DISPLAY_NAME_ASC,RELATIONSHIP_DISPLAY_NAME_DESC,CREATE_TIME_ASC,CREATE_TIME_DESC]
- next
Status Code
Success
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
No Sample Response
Finds relationship types that are used by an asset, column or governance artifact
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.
You can refer to the options in the response to get the full list of relationship names.
POST /v2/asset_relationship_types/search_used_ends
Request
Query Parameters
Catalog ID
Project ID
Space ID
Asset ID
Artifact ID
Artifact Type
Optional limit to use when finding relationship types
Default:
25Includes 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.
Default:
falseorderby. This parameter can be repeated to add additional sort fields.
Default: relationship_display_name_ascSupported 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
Default:
relationship_display_name_asc
Response
- options
Possible values: contains only unique items
Possible values: contains only unique items
Possible values: [
ASSET,ARTIFACT,COLUMN]Possible values: [
RELATIONSHIP_NAME_ASC,RELATIONSHIP_NAME_DESC,RELATIONSHIP_DISPLAY_NAME_ASC,RELATIONSHIP_DISPLAY_NAME_DESC,CREATE_TIME_ASC,CREATE_TIME_DESC]
- next
Status Code
Success
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
No Sample Response
Patches a relationship type
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:
[
{
"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"
}
[
PATCH /v2/asset_relationship_types/{relationship_type_id}Request
Path Parameters
relationship_type_id
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 `{"foo/" : {"~bar" : "value"}}`, the path for `"~bar"` is `"/foo~1/~0bar"`.
[
{
"op": "replace",
"path": "/end2/default_display_name",
"value": "new end2 display name"
},
{
"op": "replace",
"path": "/end1/default_display_name",
"value": "new end1 display name"
},
{
"op": "add",
"path": "/flags/use_for_lineage_traversal",
"value": "true or false"
},
{
"op": "add",
"path": "flags/copy_to_knowledge_graph",
"value": "true or false"
}
]
Response
relationship type metadata
- metadata
Unique ID of the relationship type
ID of the user that created the relationship type
Creation timestamp in milliseconds
Creation timestamp in yyyy-MM-dd'T'HH:mm:ss.SSSX format
Update timestamp in milliseconds
Update timestamp in yyyy-MM-dd'T'HH:mm:ss.SSSX format
ID of the user that updated the relationship type
Tenancy of the relationship type
- tenancy
Possible values: [
GLOBAL,BSS_ACCOUNT]
relationship type entity
- entity
First relationship type endpoint (order is not important)
- end1
Default display name for this end of the relationship. This is what will be shown in the UI.
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.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Possible values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Possible values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Possible values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Second relationship type endpoint (order is not important)
- end2
Default display name for this end of the relationship. This is what will be shown in the UI.
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.
Multiplicity of this end of the relationship. This controls how many targets the relationship can point to.
Possible values: [
ONE,MANY]Map of localized display names, keyed on the ISO 639 language code (e.g. "zh")
- localized_display_name
Optionally specifies the type of the artifact that contains this relationship. If omitted with containing_artifact_types, any artifact types are allowed.
Optionally specify the types of the artifacts that contain this relationship. If omitted with containing_artifact_type, any artifact types are allowed.
Possible values: contains only unique items
Specifies the catalog, project, or space id that contains the asset type. This is only required if the asset type is scoped to a particular catalog, project, or space. It is not allowed for global asset types, for example data_asset.
Specifies the type of the container which contains the asset type. This field is required if the container_id is set. It is ignored if the container_id is unset. Allowed values: 'CATALOG', 'SPACE', 'PROJECT'
Possible values: [
CATALOG,PROJECT,SPACE,EXTERNAL]Example:
CATALOGWhether the relationship attribute is displayed in child asset.
Possible values: [
true,false]Determines processing of the relationship target when the source object is deleted. Allowed values: CASCADE - delete the referenced object, IGNORE - do not delete the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is cloned to a target catalog. Allowed values: CASCADE - clone the referenced object, IGNORE - do not clone the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is published. Allowed values: CASCADE - publish the referenced object, IGNORE - do not publish the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Determines processing of the relationship target when the source object is promoted. Allowed values: CASCADE - promote the referenced object, IGNORE - do not promote the referenced object. Default: IGNORE
Possible values: [
CASCADE,IGNORE]Optionally specifies any override of cascade behavior on
delete, clone, promote and publishbased on specific asset type pairs Note: All duplicate elements will be ignored by the option_overridesSetwhen provided via create or patch REST API(s)Possible values: contains only unique items
Optionally specify the types of the assets that contain this relationship. If omitted with containing_asset_type, any asset types are allowed.
Possible values: contains only unique items
Optionally specifies the type of the asset that contains this relationship. If omitted with containing_asset_types, any asset types are allowed.
Set of flags. These flags determine the relationship type's behavior
- flags
Description of the relationship type
Status Code
Relationship type was successfully patched
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
No Sample Response
List all asset types defined for an account, catalog, project or space.
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
GET /v2/asset_types
Request
Query Parameters
This parameter allows retrieving catalog-scoped asset types. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows retrieving project-scoped asset types. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows retrieving space-scoped asset types. You must provide either a catalog_id, a project_id, a space_id, OR a bss_account_id but not more than one.
This parameter allows retrieving account-scoped asset types. 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.
This parameter allows to retrieve asset types which can be decorated. You can provide either a true or a false.
Default:
FALSEThis 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.
Default:
FALSELanguage code, such as default, en, etc.
Creates an asset type in an account, catalog, project or space.
Creates an asset type in account, catalog, project or space.
POST /v2/asset_types
Request
Query Parameters
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.
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.
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.
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.
Asset Type request body
Fields that are indexed if present in the asset.
Asset type name
Example:
connectionAsset type description
Example:
Connection asset typeExternal Asset Preview. Clients can make use of this to render content appropriately for this asset type.
- external_asset_preview
Base client URL
Example:
https://ibm.comURL parameters
URL path
Example:
idURL parameters fixed
Example:
allow_login_screen=true
Relationship definitions for this asset type.
Provides the IKC UI with information about displaying properties that can be present in the asset
- properties
Metadata about properties that can be present in an instance of a custom asset type.
Example "localized_metadata_attributes": { "name": { "default": "Data Asset", "en": "Data Asset", "fr": "Data Asset" } }
- localized_metadata_attributes
- any property
List of pointers to types this type can decorate.
Identity definition of the assets of the type
- identity
The strategy for detecting duplicate asset of the type
Allowable values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]
List of fields made searchable through Global Search functionality
Define the behavior only if this asset type is used as an attribute.
- attribute_behavior
Remove the attribute when cloning, publishing or promoting the asset
If set to true, the type definition will be custom attributes, which can be used to decorate other asset types and cannot create this as a top level asset of this asset type. If set to false, the type definition will be custom asset type, which can be used to create top level assets of this asset type and/or also decorate other asset types.
Asset type properties and attachments that should be filtered out for users without data access
- data_protection
Indicates if all fields of the asset type are protected. If 'all_fields' is true, then 'fields' is ignored.
Allowable values: [
true,false]Indicates if all attachments of the asset type are protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Allowable values: [
true,false]List of json paths that lead to the fields to be protected. e.g., "scoring.input_data", "columns[].name", "columns[0].code", "*.connection_id", etc. If 'all_fields' is true, then 'field_search_paths' is ignored.
Example:
columns[].nameList of types of attachments of the asset type to be protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Allowable values: [
MANAGED,REFERENCED,REMOTE]
Set it to true if this is to be used for column custom attributes. Set to false if this is used for asset types or attribute. If true, allow_decorators should be false.
Set it to true if the type is expected to support uploading of images, else set it to false.
Name/id of the svg image to be used as the icon for the to be created asset type.
The version of defined asset type
Example:
1
Response
Fields that are indexed if present in the asset.
Asset type name
Example:
connectionAsset type description
Example:
Connection asset typeExternal Asset Preview. Clients can make use of this to render content appropriately for this asset type.
- external_asset_preview
Base client URL
Example:
https://ibm.comURL parameters
URL path
Example:
idURL parameters fixed
Example:
allow_login_screen=true
Relationship definitions for this asset type.
Provides the IKC UI with information about displaying properties that can be present in the asset
- properties
Metadata about properties that can be present in an instance of a custom asset type.
Example "localized_metadata_attributes": { "name": { "default": "Data Asset", "en": "Data Asset", "fr": "Data Asset" } }
- localized_metadata_attributes
- any property
List of pointers to types this type can decorate.
Identity definition of the assets of the type
- identity
The strategy for detecting duplicate asset of the type
Possible values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]
List of fields made searchable through Global Search functionality
Define the behavior only if this asset type is used as an attribute.
- attribute_behavior
Remove the attribute when cloning, publishing or promoting the asset
If set to true, the type definition will be custom attributes, which can be used to decorate other asset types and cannot create this as a top level asset of this asset type. If set to false, the type definition will be custom asset type, which can be used to create top level assets of this asset type and/or also decorate other asset types.
Asset type properties and attachments that should be filtered out for users without data access
- data_protection
Indicates if all fields of the asset type are protected. If 'all_fields' is true, then 'fields' is ignored.
Possible values: [
true,false]Indicates if all attachments of the asset type are protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
true,false]List of json paths that lead to the fields to be protected. e.g., "scoring.input_data", "columns[].name", "columns[0].code", "*.connection_id", etc. If 'all_fields' is true, then 'field_search_paths' is ignored.
Example:
columns[].nameList of types of attachments of the asset type to be protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
MANAGED,REFERENCED,REMOTE]
Set it to true if this is to be used for column custom attributes. Set to false if this is used for asset types or attribute. If true, allow_decorators should be false.
Set it to true if the type is expected to support uploading of images, else set it to false.
Name/id of the svg image to be used as the icon for the to be created asset type.
The version of defined asset type
Example:
1The scope of defined asset type. Derived-field. Will be one of GLOBAL, ACCOUNT, CATALOG, PROJECT, or SPACE.
Example:
GLOBALList of pointers to types this type can be decorated by.
Status Code
Created
Accepted - indicates the asset type creation is being completed in the background
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Request
No Sample Response
Retrieves an asset type of a given 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
GET /v2/asset_types/{type_name}Request
Path Parameters
Asset Type name (eg: data_asset)
Query Parameters
This parameter allows retrieving 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.
This parameter allows retrieving 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.
This parameter allows retrieving 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.
This parameter allows retrieving 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.
Language code, such as default, en, etc.
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
Fields that are indexed if present in the asset.
Asset type name
Example:
connectionAsset type description
Example:
Connection asset typeExternal Asset Preview. Clients can make use of this to render content appropriately for this asset type.
- external_asset_preview
Base client URL
Example:
https://ibm.comURL parameters
URL path
Example:
idURL parameters fixed
Example:
allow_login_screen=true
Relationship definitions for this asset type.
Provides the IKC UI with information about displaying properties that can be present in the asset
- properties
Metadata about properties that can be present in an instance of a custom asset type.
Example "localized_metadata_attributes": { "name": { "default": "Data Asset", "en": "Data Asset", "fr": "Data Asset" } }
- localized_metadata_attributes
- any property
List of pointers to types this type can decorate.
Identity definition of the assets of the type
- identity
The strategy for detecting duplicate asset of the type
Possible values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]
List of fields made searchable through Global Search functionality
Define the behavior only if this asset type is used as an attribute.
- attribute_behavior
Remove the attribute when cloning, publishing or promoting the asset
If set to true, the type definition will be custom attributes, which can be used to decorate other asset types and cannot create this as a top level asset of this asset type. If set to false, the type definition will be custom asset type, which can be used to create top level assets of this asset type and/or also decorate other asset types.
Asset type properties and attachments that should be filtered out for users without data access
- data_protection
Indicates if all fields of the asset type are protected. If 'all_fields' is true, then 'fields' is ignored.
Possible values: [
true,false]Indicates if all attachments of the asset type are protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
true,false]List of json paths that lead to the fields to be protected. e.g., "scoring.input_data", "columns[].name", "columns[0].code", "*.connection_id", etc. If 'all_fields' is true, then 'field_search_paths' is ignored.
Example:
columns[].nameList of types of attachments of the asset type to be protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
MANAGED,REFERENCED,REMOTE]
Set it to true if this is to be used for column custom attributes. Set to false if this is used for asset types or attribute. If true, allow_decorators should be false.
Set it to true if the type is expected to support uploading of images, else set it to false.
Name/id of the svg image to be used as the icon for the to be created asset type.
The version of defined asset type
Example:
1The scope of defined asset type. Derived-field. Will be one of GLOBAL, ACCOUNT, CATALOG, PROJECT, or SPACE.
Example:
GLOBALList of pointers to types this type can be decorated by.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
No Sample Response
Replace an asset type
Replace asset attributes for the given asset type or create a new asset type if the given asset type does not exist.
PUT /v2/asset_types/{type_name}Request
Path Parameters
Asset Type name (eg: data_asset)
Query Parameters
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.
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.
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.
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.
Asset Type request body
Fields that are indexed if present in the asset.
Asset type description
Example:
Connection asset typeExternal Asset Preview. Clients can make use of this to render content appropriately for this asset type.
- external_asset_preview
Base client URL
Example:
https://ibm.comURL parameters
URL path
Example:
idURL parameters fixed
Example:
allow_login_screen=true
Relationship definitions for this asset type.
Provides the IKC UI with information about displaying properties that can be present in the asset
- properties
Metadata about properties that can be present in an instance of a custom asset type.
Example "localized_metadata_attributes": { "name": { "default": "Data Asset", "en": "Data Asset", "fr": "Data Asset" } }
- localized_metadata_attributes
- any property
List of pointers to types this type can decorate.
Identity definition of the assets of the type
- identity
The strategy for detecting duplicate asset of the type
Allowable values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]
List of fields made searchable through Global Search functionality
Define the behavior only if this asset type is used as an attribute.
- attribute_behavior
Remove the attribute when cloning, publishing or promoting the asset
If set to true, the type definition will be custom attributes, which can be used to decorate other asset types and cannot create this as a top level asset of this asset type. If set to false, the type definition will be custom asset type, which can be used to create top level assets of this asset type and/or also decorate other asset types.
Asset type properties and attachments that should be filtered out for users without data access
- data_protection
Indicates if all fields of the asset type are protected. If 'all_fields' is true, then 'fields' is ignored.
Allowable values: [
true,false]Indicates if all attachments of the asset type are protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Allowable values: [
true,false]List of json paths that lead to the fields to be protected. e.g., "scoring.input_data", "columns[].name", "columns[0].code", "*.connection_id", etc. If 'all_fields' is true, then 'field_search_paths' is ignored.
Example:
columns[].nameList of types of attachments of the asset type to be protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Allowable values: [
MANAGED,REFERENCED,REMOTE]
Set it to true if this is to be used for column custom attributes. Set to false if this is used for asset types or attribute. If true, allow_decorators should be false.
Set it to true if the type is expected to support uploading of images, else set it to false.
Name/id of the svg image to be used as the icon for the to be created asset type.
Response
Fields that are indexed if present in the asset.
Asset type name
Example:
connectionAsset type description
Example:
Connection asset typeExternal Asset Preview. Clients can make use of this to render content appropriately for this asset type.
- external_asset_preview
Base client URL
Example:
https://ibm.comURL parameters
URL path
Example:
idURL parameters fixed
Example:
allow_login_screen=true
Relationship definitions for this asset type.
Provides the IKC UI with information about displaying properties that can be present in the asset
- properties
Metadata about properties that can be present in an instance of a custom asset type.
Example "localized_metadata_attributes": { "name": { "default": "Data Asset", "en": "Data Asset", "fr": "Data Asset" } }
- localized_metadata_attributes
- any property
List of pointers to types this type can decorate.
Identity definition of the assets of the type
- identity
The strategy for detecting duplicate asset of the type
Possible values: [
DUPLICATE_DETECTION_BY_NAME,DUPLICATE_DETECTION_BY_NAME_AND_RESOURCE_KEY,DUPLICATE_DETECTION_BY_NAME_AND_FOLDER,DUPLICATE_DETECTION_BY_RESOURCE_KEY,DUPLICATE_DETECTION_NOT_APPLICABLE]
List of fields made searchable through Global Search functionality
Define the behavior only if this asset type is used as an attribute.
- attribute_behavior
Remove the attribute when cloning, publishing or promoting the asset
If set to true, the type definition will be custom attributes, which can be used to decorate other asset types and cannot create this as a top level asset of this asset type. If set to false, the type definition will be custom asset type, which can be used to create top level assets of this asset type and/or also decorate other asset types.
Asset type properties and attachments that should be filtered out for users without data access
- data_protection
Indicates if all fields of the asset type are protected. If 'all_fields' is true, then 'fields' is ignored.
Possible values: [
true,false]Indicates if all attachments of the asset type are protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
true,false]List of json paths that lead to the fields to be protected. e.g., "scoring.input_data", "columns[].name", "columns[0].code", "*.connection_id", etc. If 'all_fields' is true, then 'field_search_paths' is ignored.
Example:
columns[].nameList of types of attachments of the asset type to be protected. If 'all_attachments' is true, then 'attachment_types' is ignored.
Possible values: [
MANAGED,REFERENCED,REMOTE]
Set it to true if this is to be used for column custom attributes. Set to false if this is used for asset types or attribute. If true, allow_decorators should be false.
Set it to true if the type is expected to support uploading of images, else set it to false.
Name/id of the svg image to be used as the icon for the to be created asset type.
The version of defined asset type
Example:
1The scope of defined asset type. Derived-field. Will be one of GLOBAL, ACCOUNT, CATALOG, PROJECT, or SPACE.
Example:
GLOBALList of pointers to types this type can be decorated by.
Status Code
OK
Accepted
Bad Request
Unauthorized
Forbidden
Not Found
Conflict
Too Many Request
Internal Server Error
No Sample Response
Deletes an asset type
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:
- Assets of this type are deleted.
- And in case of other assets, attributes of this type are removed.
DELETE /v2/asset_types/{type_name}Request
Path Parameters
Asset Type name (eg: data_asset)
Query Parameters
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.
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.
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.
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.
Finds relationship types for an asset type
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.
This API is deprecated - use POST /v2/asset_relationship_types/search_ends instead
GET /v2/asset_types/{type_name}/relationshipsRequest
Path Parameters
type_name. This specifies the asset type whose relationships should be found.
Query Parameters
catalog_id. If set, this restricts catalog asset types in the result to the given catalog. If no container parameters are set, any asset container the user has access to are allowed.
catalog_id. If set, this restricts catalog asset types in the result to the given project. If no container parameters are set, any asset containers the user has access to are allowed.
catalog_id. If set, this restricts catalog asset types in the result to the given space. If no container parameters are set, any asset containers the user has access to are allowed.
Optional limit to use when finding relationship types
Default:
25Optional bookmark to use when finding relationship types.
orderby. This parameter can be repeated to add additional sort fields.
Default: relationship_display_name_ascSupported 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
Default:
relationship_display_name_ascLimits 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
- options
Possible values: contains only unique items
Possible values: contains only unique items
Possible values: [
ASSET,ARTIFACT,COLUMN]Possible values: [
RELATIONSHIP_NAME_ASC,RELATIONSHIP_NAME_DESC,RELATIONSHIP_DISPLAY_NAME_ASC,RELATIONSHIP_DISPLAY_NAME_DESC,CREATE_TIME_ASC,CREATE_TIME_DESC]
- next
Status Code
Success
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
No Sample Response
Search for asset metadata within assets of the specified type
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.
See Searchable Asset and Attachment Fields below for the list of fields that can be searched in the query.
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.
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>").
Search With Pagination
The limit request body field can be specified to limit the number of assets in the search results.
The default limit is 200. The maximum limit value is 200, and any greater value is ignored.
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>"
}
Searchable Asset and Attachment Fields
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:
asset.asset_attributes<string>
asset.asset_category<string>
asset.asset_state<string>
asset.asset_type<string>
asset.catalog_id<string>
asset.created_at<string>
asset.delete_timestamp<string>
asset.description<string>
asset.memberIds<string>
asset.editor_id<string>
asset.viewer_id<string>
asset.member_or_owner_id<string>
asset.memberGroupIds<string>
asset.editor_group_id<string>
asset.viewer_group_id<string>
asset.member_or_owner_group_id<string>
asset.mode<number>
asset.name<string>
asset.owner_id<string>
asset.owner_group_id<string>
asset.project_id<string>
asset.rating<number>
asset.resource_key<string>
asset.identity_key<string>
asset.source_asset_id<string>
asset.source_catalog_id<string>
asset.source_project_id<string>
asset.source_space_id<string>
asset.source_system<string>
asset.source_system_asset_id<string>
asset.source_system_created_at<string>
asset.source_system_id<string>
asset.source_history_asset_id<string>
asset.source_history_system_id<string>
asset.space_id<string>
asset.tags<string>
attachment.connection_id<string>
attachment.connection_path<string>
attachment.name<string>
attachment.object_key<string>
POST /v2/asset_types/{type_name}/searchRequest
Path Parameters
Asset Type name (eg: data_asset)
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseThe parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
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".
Lucene query
Example:
*:*Returns the number of query results for each unique value of each named field.
Examples:[ "asset.tags", "asset.asset_type" ]Restrict results to documents with a dimension equal to the specified label. Note that, multiple values for a single key in a drilldown means an OR relation between them and there is an AND relation between multiple keys.
Examples:[ { "asset.tags": [ "tag1", "untagged" ], "asset.asset_type": [ "data_asset", "job" ] } ]- drilldown
Bookmark of the query result
Sort order for the query
Example:
asset.name<string>entity
Example:
entity
Get the status of an account scope or global scope asset type.
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.
GET /v2/asset_types/{type_name}/statusCreate an asset
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.
All asset types have a common set of properties. Some asset types have additional properties.
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 @.
POST /v2/assets
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans 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.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Asset metadata
- Examples:
{ "data_asset": { "mime_type": "text/csv", "dataset": false } }- entity
AssetMetadata Model
Get one or more assets.
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.
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":[
...
]
},
...
]
}
GET /v2/assets/bulk
Request
Query Parameters
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.
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseWhether to include per-asset relationship count. Note: The default will be changed to 'false' in a later release.
Default:
trueWhether to include relationships where source end is a column of the source asset in the asset's relationship counter.
Default:
false
Marks existing assets for delete
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.
DELETE /v2/assets/bulk
Request
Query Parameters
Comma separated list of asset IDs; maximum of 20.
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
If true, asset is also deleted from the trash.
Default:
falseNumber of days after which asset will be purged. Purge On Delete should be true for this to be valid
Copies one or more assets and, if deep copy option is on, their related assets from a source container to a target container.
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.
Copy sends the same Rabbit MQ messages as publish, promote or clone. Messages are sent for all assets that are copied.
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
POST /v2/assets/bulk_copy
Request
Query Parameters
Source catalog ID. Only one of either catalog ID or project ID must be provided.
Source project ID. Only one of either catalog ID or project ID must be provided.
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
CASCADEis 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 andon_promote, in case of copying from project to space.
Default:
falseWhether to automatically copy connections in remote attachments
Default:
trueAction to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans 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.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
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.
To assign owners and other collaborators on newly copied target assets.
- member_roles
Response
Possible values: [
WAITING,IN_PROGRESS,COMPLETED,FAILED]
Status Code
OK - indicates the copy operation has completed - assets and its related assets (if applicable) have been fully copied to the target catalog.
Accepted - indicates that the copy request is being completed in the background.
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Create one or more assets.
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:
{
"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":[
...
]
},
...
]
}
POST /v2/assets/bulk_create
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans 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.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
JSON containing list of assets to be created.
Asset Model
Patch one or more assets.
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)
attachmentsfield 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
pathis/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,partitionsandtransfer_complete.
- The (asset)
The API does not support patching of whole metadata, entity and attachments.
- i.e. The
pathcannot be the following values:/metadata,/entityor/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:
{
"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~0in 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
POST /v2/assets/bulk_patch
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
JSON containing per-asset updates/patches.
Gets the status of asset copy operation
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.
GET /v2/assets/copy_status/{copy_task_id}Create a PUT signed url for an object or a file
Use this API to create a PUT signed url to an object or a file in the catalog/project/space bucket/storage.
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.
You must specify one of these -- catalog_id, project_id or the space_id as a query parameter.
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.
POST /v2/assets/create_object_url
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
object_url request
Gets the status of a deep copy operation
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.
Note: The status of completed deep copy operations is only available for 24 hours.
GET /v2/assets/deepcopy/{deep_copy_task_id}Bulk search duplicate assets
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.
POST /v2/assets/duplicates/bulk_search
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
The maximum number of items to return for each requested asset
Default:
100
The assets to search for duplicate assets.
the assets to search duplicates for
Search duplicate assets
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.
The best_updatable_duplicate_asset_id indicates the highest ranking duplicate asset that can be updated by the authenticated user. This duplicate asset would be updated/replaced if the incoming asset were to be added in the target asset container and the effective duplicate_action were UPDATE/REPLACE. If duplicates are found but this field doesn't have a value, it indicates that the authenticated user doesn't have permission to update any of the duplicates. In such a case, if the incoming asset were to be added in the target asset container and the effective duplicate_action were UPDATE/REPLACE, the transaction would fail.
POST /v2/assets/duplicates/search
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
The maximum number of items to return
Default:
100Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Supply either an existing asset or an asset payload to search for duplicate assets.
Id of the catalog the existing asset resides in. You must provide either a catalog id, a project id, or a space id, but not more than one
Example:
b81c84f5-a551-43bb-9a6e-c8e7820995f9Id of the project the existing asset resides in. You must provide either a catalog id, a project id, or a space id, but not more than one
Example:
814bc4e9-a8e6-4a02-9fb8-096211f09fb5Id of the space the existing asset resides in. You must provide either a catalog id, a project id, or a space id, but not more than one
Example:
21a374d0-9d04-48d5-884b-0f6cbfc67779Id of the existing asset
Example:
c43efbc1-7a65-44b8-bc40-c59f008716a8Revision of the existing asset
Example:
1,2,...,latestThe asset payload, which is the same as the user would provide for creating a new asset.
- asset
- Examples:
{ "data_asset": { "mime_type": "text/csv", "dataset": false } }- entity
AssetMetadata Model
Response
List of matching duplicate assets
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
Example:
b81c84f5-a551-43bb-9a6e-c8e7820995f9Total number of duplicates
Example:
1
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
No Sample Response
Get an ibm_data_source asset
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
GET /v2/assets/ibm_data_source
Request
Query Parameters
Catalog GUID or UID
the bss_account_id
It can be database, project_id or bucket
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Publish an asset from a project which is only referenced in that project
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.
All asset types have a common set of properties. Some asset types have additional properties.
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 @.
POST /v2/assets/publish
Request
Query Parameters
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Asset metadata
Publish Asset Metadata
- entity
Get an asset
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.
GET /v2/assets/{asset_id}Request
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Marks an existing asset for delete
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
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.
DELETE /v2/assets/{asset_id}Request
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
If true, asset is also deleted from the trash.
Default:
falseNumber of days after which asset will be purged. Purge On Delete should be true for this to be valid
Update an asset
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, useaddoperation 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.
PATCH /v2/assets/{asset_id}Request
Custom Headers
Allowable values: [
application/json,application/json-patch+json]
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
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".
Clone an asset
Use this API to clone catalog asset to project. This will create new copy of asset metadata, including asset attachments.
POST /v2/assets/{asset_id}/cloneRequest
Path Parameters
asset_id
Query Parameters
catalog_id must be provided
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans 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.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
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.
Optional owners and other collaborators to assign to newly copied target assets
- member_roles
Set the privacy level mode to be Public (0), Private (8), or Hidden (16)
Add/Update asset 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.
PATCH /v2/assets/{asset_id}/collaboratorsRequest
Custom Headers
Allowable values: [
application/json,application/json-patch+json,application/merge-patch+json]
Path Parameters
Asset GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
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.
Deep copies an asset and its related assets to a catalog, project, or space
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.
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.
Deep copy sends the same Rabbit MQ messages as clone, publish, and promote. Messages are sent for all assets that are copied.
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).
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.
POST /v2/assets/{asset_id}/deepcopyRequest
Path Parameters
asset_id
Query Parameters
project_id
catalog_id
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans 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.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]
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.
requestBody in json
{
"space_id": "string",
"mode": 0,
"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": {
"iam_id": "Another IAM ID",
"roles": [
"role"
]
}
},
"metadata": {
"name": "string",
"description": "string",
"tags": [
"string",
"string"
]
}
}Response
Status Code
OK - indicates the deep copy operation has completed - the asset and its related assets (if applicable) have been fully copied to the target container
Accepted - indicates that the copy request is being completed in the background.
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Update the owner of an asset
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}
or
/v2/assets/{asset_id}/collaborators
PUT /v2/assets/{asset_id}/ownerRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Asset Owner
Example:
test@us.ibm.comExample:
IBMid-310002980
Update privacy settings of an asset
Use this API to change privacy settings on an asset.
- 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.
PUT /v2/assets/{asset_id}/permsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Asset ROV
Promote an asset
Use this API to promote project assets to space. You must have Admin or Editor permissions on both the project and the space.
POST /v2/assets/{asset_id}/promoteRequest
Path Parameters
asset_id
Query Parameters
project_id must be provided
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans 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.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
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.
requestBody in json
{
"space_id": "string",
"mode": 0,
"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": {
"iam_id": "Another IAM ID",
"roles": [
"role"
]
}
},
"metadata": {
"name": "string",
"description": "string",
"tags": [
"string",
"string"
]
}
}Publish an asset
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.
POST /v2/assets/{asset_id}/publishRequest
Path Parameters
asset_id
Query Parameters
project_id must be provided
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans 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.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
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.
requestBody in json
{
"catalog_id": "string",
"mode": 0,
"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": {
"iam_id": "Another IAM ID",
"roles": [
"role"
]
}
},
"metadata": {
"name": "string",
"description": "string",
"tags": [
"string",
"string"
]
}
}Finds related assets
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.
Finds assets and artifacts related to an asset:
- 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.
Finds assets related to an artifact:
- artifact_id and artifact_type must be specified.
- asset_id and container id cannot be specified.
Finds assets and artifacts related to a column:
- 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.
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.
POST /v2/assets/get_relationships
Request
Query Parameters
Catalog ID
Project ID
Space ID
Asset ID
Artifact ID
Artifact Type
Related Asset Types
Related Artifact Types
bookmark
limit. Defaults to 25
Default:
25orderby. This parameter can be repeated to add additional sort fields.
Default: update_time_ascSupported 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
Default:
update_time_ascLimits results to only include the specified relationships. By default, all relationships are included. Repeat the query parameter to specify multiple relationship names.
Whether to lookup the asset names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
falseWhether to lookup the artifact names. This adds overhead, so only set this to true if the artifact names are required. Defaults to false.
Default:
falseWhether to lookup the container names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
false(DEPRECATED) Whether to return relationships where target end is a column for the given source asset, artifact, or column. This parameter is deprecated. Use 'include_target_columns' instead.
Default:
falseWhether to return relationships where target end is a column for the given source asset, artifact, or column.
Default:
falseWhether 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.
Default:
false
Searches for 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:
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.
POST /v2/assets/search_relationships
Request
Query Parameters
Catalog ID. Specifies that a specific catalog_id must be in the returned relationships. If filtering by asset container, either catalog_id, project_id, or space_id must be specified.
Project ID. Specifies that a specific project_id must be in the returned relationships. If filtering by asset container, either catalog_id, project_id, or space_id must be specified.
Space ID. Specifies that a specific space_id must be in the returned relationships. If filtering by asset container, either catalog_id, project_id, or space_id must be specified.
Asset ID. Specifies that a specific asset must be in the returned relationships If specified, either catalog_id, project_id, or space_id must also be specified.
Artifact ID. Specifies that a specific artifact must be in the returned relationships. If specified, artifact_type must also be specified
Artifact Type. Required if artifact_id is specified
Related Asset Types. Filters the result to include relationships based on their target asset type. The parameter can be repeated to specify multiple asset types. If both related_artifact_types and related_asset types are omitted, all target types are included in the result.
Related Artifact Types. Filters the result to include relationships based on their target artifact type. The parameter can be repeated to specify multiple artifact types. If both related_artifact_types and related_asset types are omitted, all target types are included in the result.
bookmark
limit. Defaults to 25
Default:
25orderby. This parameter can be repeated to add additional sort fields.
Default: update_time_ascSupported 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
Default:
update_time_ascLimits results to only include the specified relationships. By default, all relationships are included. Repeat the query parameter to specify multiple relationship names.
Whether to lookup the asset names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
falseWhether to lookup the artifact names. This adds overhead, so only set this to true if the artifact names are required. Defaults to false.
Default:
falseWhether to lookup the container names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
falseIncludes relationships modified after this date/time - specified in ISO-8601 format (examples: 2022-09-01T14:32:17Z, 2022-09-01T14:32:17.802Z). This can be used in conjunction with modified_before to specify a required modification time window.
Includes relationships modified before this date/time - specified in ISO-8601 format (examples: 2022-09-01T14:32:17Z, 2022-09-01T14:32:17.802Z). This can be used in conjunction with modified_after to specify a required modification time window.
(DEPRECATED) Whether to return relationships where target end is a column for the given source asset, artifact, or column. This parameter is deprecated. Use 'include_target_columns' instead.
Default:
falseWhether to return relationships where target end is a column for the given source asset, artifact, or column.
Default:
falseWhether 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.
Default:
false
Create asset 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.
Relationships created with a governance artifact as the source cannot be retrieved, modified, or deleted in the IKC UI.
These relationships can only be accessed through API calls such asPOST /v2/assets/search_relationships,POST /v2/assets/get_relationships, andPOST /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_idand one of the {catalog_id,project_id,space_id} must be set
For Column
- The
asset_idand one of the {catalog_id,project_id,space_id} must be set - The
asset_idof a column must be in the format of<asset_id>#COLUMN#<column_identifier>
For Artifact
- The
artifact_idandartifact_typemust be set. Use the global id of the artifact forartifact_id
POST /v2/assets/set_relationships
Deletes asset 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_idand one of the {catalog_id,project_id,space_id} must be set
For Column
- The
asset_idand one of the {catalog_id,project_id,space_id} must be set - The
asset_idof a column must be in the format of<asset_id>#COLUMN#<column_identifier>
For Artifact
- The
artifact_idandartifact_typemust be set
POST /v2/assets/unset_relationships
Finds relationship types used by an asset
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.
You can refer to the options in the response to get the full list of relationship names.
This API is deprecated - use POST /v2/assets/search_relationships instead.
GET /v2/assets/{asset_id}/relationship_typesRequest
Path Parameters
Asset ID
Query Parameters
Catalog ID
Project ID
Space ID
Optional limit to use when finding relationship types
Default:
25orderby. This parameter can be repeated to add additional sort fields.
Default: relationship_display_name_ascSupported 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
Default:
relationship_display_name_asc
Response
- options
Possible values: contains only unique items
Possible values: contains only unique items
Possible values: [
ASSET,ARTIFACT,COLUMN]Possible values: [
RELATIONSHIP_NAME_ASC,RELATIONSHIP_NAME_DESC,RELATIONSHIP_DISPLAY_NAME_ASC,RELATIONSHIP_DISPLAY_NAME_DESC,CREATE_TIME_ASC,CREATE_TIME_DESC]
- next
Status Code
Success
Bad Request
Unauthorized
Forbidden
Conflict
Too Many Requests
No Sample Response
Finds related assets
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.
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.
This API is deprecated - use POST /v2/assets/get_relationships instead.
GET /v2/assets/{asset_id}/relationshipsRequest
Path Parameters
Asset ID
Query Parameters
Catalog ID
Project ID
Space ID
bookmark
limit. Defaults to 25
Default:
25orderby. This parameter can be repeated to add additional sort fields.
Default: update_time_ascSupported 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
Default:
update_time_ascLimits results to only include the specified relationships. By default, all relationships are included. Repeat the query parameter to specify multiple relationship names.
Whether to lookup the asset names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
falseWhether to lookup the container names. This adds overhead, so only set this to true if the asset names are required. Defaults to false.
Default:
false
Create asset relationships
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.
PUT /v2/assets/{asset_id}/relationships/{relationship_name}Deletes asset relationships
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.
This API is deprecated - use POST /v2/assets/unset_relationships instead.
DELETE /v2/assets/{asset_id}/relationships/{relationship_name}Request
Path Parameters
Source Asset Id
Name of relationship defined on the source asset type
Query Parameters
target asset id. To delete multiple relationships, this parameter can be repeated.
Source Asset Catalog
Source Asset Project
Source Asset Space
Target Asset Catalog
Target Asset Project
Target Asset Space
Determine if a relationship exists between an asset and a target artifact
Use this API to determine if a relationship exists between an asset and a target artifact. The relationship name must correspond to a relationship type defined on the source asset's type. The target artifact must be an asset of the type specified in the relationship type definition. The source and target assets must reside in the same catalog.
HEAD /v2/assets/{asset_id}/relationships/{relationship_name}Request
Path Parameters
Asset GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
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.
Request
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
private_url
Default:
falseresponse-content-disposition
response-content-type
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
Request
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
Update attachment metadata
Update attachment metadata. Only the following fields are allowed to update:
- name
- description
- mime
- size
- partitions
- transfer_complete
PATCH /v2/assets/{asset_id}/attachments/{attachment_id}Request
Custom Headers
Allowable values: [
application/json,application/json-patch+json,application/merge-patch+json]
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
[
{ "op": "add", "path": "/name", "value": "my_attachment"},
{ "op": "replace", "path": "/mime", "value": "text/csv" },
{ "op": "remove", "path":"/description"}
]
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". - The transfer_complete field can only be set to true if its current value is false and the type of attachment is managed.
Mark an attachment as transfer complete
Marks an attachment as transfer complete.
POST /v2/assets/{asset_id}/attachments/{attachment_id}/completeRequest
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Auto update attachment's datasource_type from connection asset
Auto update attachment's datasource_type from connection asset
PATCH /v2/assets/{asset_id}/attachments/{attachment_id}/datasource_typeRequest
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Get resources info for an attachment
Get resources info for an attachment.
GET /v2/assets/{asset_id}/attachments/{attachment_id}/resourcesRequest
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
Increase resources for an attachment
Increase resources for an attachment.
PUT /v2/assets/{asset_id}/attachments/{attachment_id}/resourcesRequest
Path Parameters
Asset GUID
Attachment GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
attachment resource to increase, e.g. {"data_partitions":5, "private_url":false}
List all attributes
Use this API to retrieve all attributes of an asset.
GET /v2/assets/{asset_id}/attributesRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Create an attribute
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).
Create a column_info asset attribute to add column descriptions and/or tags if that attribute does not already exist on the asset.
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.
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"
]
}
}
}
POST /v2/assets/{asset_id}/attributesRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
Attribute metadata. The "entity" is required.
Example:
TestAttribute- entity
Get an attribute
Use this API to retrieve an attribute of an asset.
GET /v2/assets/{asset_id}/attributes/{attribute_key}Request
Path Parameters
asset_id
attribute_key
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Delete an attribute
Use this API to delete an attribute of an asset.
DELETE /v2/assets/{asset_id}/attributes/{attribute_key}Request
Path Parameters
asset_id
attribute_key
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
Update attributes
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.
Note: Use
POST /v2/assets/{asset_id}/attributesto create thecolumn_infoattribute if it does not exist on the asset. UseGET /v2/assets/{asset_id}/attributes/column_infoto 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".
PATCH /v2/assets/{asset_id}/attributes/{attribute_key}Request
Custom Headers
Allowable values: [
application/json,application/json-patch+json]
Path Parameters
asset_id
attribute_key
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Action to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
JSON array of patch operations as defined in RFC 6902.
Get asset document conflicts
Use this API to retrieve asset document conflicts in database.
GET /v2/assets/{asset_id}/conflictsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
The number of items to skip before starting to collect the result set
The maximum number of items to return
Default:
10Whether to retrieve conflict revision document content
Delete asset document conflicts
Use this API to delete asset document conflicts in database.
DELETE /v2/assets/{asset_id}/conflictsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Document conflicts to delete
List of conflicting documents revs
Request
Path Parameters
Asset GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Upload an image for asset
Upload an image for asset. Use this api, you must put the image's binary data to the HTTP body.
For example:
curl -X "PUT" "api_url" -H "Authorization: $access token" --data-binary "@/image_dir_path/abc.png"
PUT /v2/assets/{asset_id}/imagesRequest
Path Parameters
Asset GUID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Request
Path Parameters
Asset GUID
Image id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Get asset or column 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.
GET /v2/assets/{asset_id}/notesRequest
Path Parameters
Asset ID
Query Parameters
The maximum number of asset/column notes to return.
The default value is 25. The limit cannot exceed 200.
Use thenextURL from the response to retrieve the next page of notes.Default:
25Sorting order.
The following fields can be used for sorting. Use hyphen prefix (-) for descending order:column_namecreated_atupdated_atDefault:
-updated_atYou must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Filters the result to include notes on the specified column(s). The parameter should be repeated for each column name.
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Type of notes to include in the search result:
Note Type Description ALLInclude all asset and column notes ASSETInclude asset notes only - cannot be used with the column_namesparameterCOLUMNInclude column notes only Allowable values: [
ALL,ASSET,COLUMN]Default:
ALL
Create notes on an asset
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.
POST /v2/assets/{asset_id}/notesRequest
Path Parameters
Asset ID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Asset notes to be created - limited to 20 notes per request
notes to be created for an asset and for columns of an asset
Get an asset or column note
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.
GET /v2/assets/{asset_id}/notes/{note_id}Request
Path Parameters
Asset ID
Note ID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Response
Asset note metadata
- metadata
system generated unique asset note identifier
unique Identifier of asset associated with this note
Example:
892aaa55-1b0e-438a-b05f-4224246a0f3fname of the column associated with this note
Example:
cityID of user that created the asset note (system managed)
Example:
IBMid-66100421ANID of user that updated the asset note (system managed)
Example:
IBMid-66100421ANRFC 3339 timestamp (yyyy-MM-dd'T'HH:mm:ss'Z') when the asset note was created (system managed)
Example:
2023-05-24T16:34:06ZEpoch timestamp when the asset note was created (system managed)
Example:
1621874046338RFC 3339 timestamp (yyyy-MM-dd'T'HH:mm:ss'Z') when the asset note was updated (system managed)
Example:
2023-05-24T16:34:06ZEpoch timestamp when the asset note was updated (system managed)
Example:
1621874046338
Asset note entity
- entity
a note associated with an asset or a column of an asset
Example:
description of a note
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Delete an asset or a column note
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.
DELETE /v2/assets/{asset_id}/notes/{note_id}Request
Path Parameters
Asset ID
Asset or column note ID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Update an asset or column note
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.
PATCH /v2/assets/{asset_id}/notes/{note_id}Request
Path Parameters
Asset ID
Note ID
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
JSON array of patch operations as defined in RFC 6902. See http://jsonpatch.com/ for more info.
Example :
[ {"op": "replace", "path": "/note", "value": "Description of a Note" } ]
Note:
Only supported operation is replace.
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.
Response
Asset note metadata
- metadata
system generated unique asset note identifier
unique Identifier of asset associated with this note
Example:
892aaa55-1b0e-438a-b05f-4224246a0f3fname of the column associated with this note
Example:
cityID of user that created the asset note (system managed)
Example:
IBMid-66100421ANID of user that updated the asset note (system managed)
Example:
IBMid-66100421ANRFC 3339 timestamp (yyyy-MM-dd'T'HH:mm:ss'Z') when the asset note was created (system managed)
Example:
2023-05-24T16:34:06ZEpoch timestamp when the asset note was created (system managed)
Example:
1621874046338RFC 3339 timestamp (yyyy-MM-dd'T'HH:mm:ss'Z') when the asset note was updated (system managed)
Example:
2023-05-24T16:34:06ZEpoch timestamp when the asset note was updated (system managed)
Example:
1621874046338
Asset note entity
- entity
a note associated with an asset or a column of an asset
Example:
description of a note
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Request
Path Parameters
asset_id
Query Parameters
The maximum number of asset ratings to return.
The default value is 25.Default:
25Bookmark that gives the start of the page.
Sorting order.
Valid values:updated_at,rating
Use hyphen prefix (-) for descending orderDefault:
-updated_atFilter results by user.
Valid values:all,user,other
The default value isallAllowable values: [
all,user,other]Default:
allYou must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Request
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Asset rating to be created
user's rating of an asset
Example:
5user's review of an asset
Example:
Such an asset!
Get the count of each rating value for the specified asset
Get the counts of each rating value for the specified asset.
GET /v2/assets/{asset_id}/ratings/statsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Delete an asset rating
Use this API to delete an asset rating.
DELETE /v2/assets/{asset_id}/ratings/{asset_rating_id}Request
Path Parameters
asset_id
asset_rating_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Use this API to update an asset rating.
Update an asset rating
PATCH /v2/assets/{asset_id}/ratings/{asset_rating_id}Request
Path Parameters
asset_id
asset_rating_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Asset rating to be updated
user's rating of an asset
Example:
5user's review of an asset
Example:
Such an asset!
Get a list of revisions for an asset
Use this API to retrieve an ordered list of revisions for an asset, most to least recent.
GET /v2/assets/{asset_id}/revisionsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
The parameter
includeis deprecated.The maximum number of revisions to return. The default is 25. Maximum is 200
Default:
25The revision number to start from, or 'latest'. Latest revision is the default.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Commit a revision of an asset
Use this API to commit a revision of an asset.
POST /v2/assets/{asset_id}/revisionsRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Commit options
Delete a revision
Use this API to delete a revision of an asset.
DELETE /v2/assets/{asset_id}/revisionsRequest
Path Parameters
asset_id
Query Parameters
You must provide a revision id (1, 2, 3, ...)
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
List all catalogs for a specific account
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.
- Standard Callers: to list all catalogs where caller is collaborator, omit "bss_account_id" field and "include" field.
- 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.
- 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.
GET /v2/catalogs
Request
Query Parameters
limit
Default:
25bookmark
skip
Default:
0Limited 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.
- Use 'catalogs' for including all public catalogs for a specific bss_account_id.
- Use 'projects' for including all projects for a specific bss_account_id.
- Use 'spaces' for including all spaces for a specific bss_account_id.
- Use 'total_count' for including total number of public catalogs for a specific account.
- Use 'catalogs' for including all public catalogs for a specific bss_account_id.
"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.
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. This parameter can be repeated to add additional sort fields.
Default: nullSupported sort fields (these are case insensitive):
- catalog_name_asc
- catalog_name_desc
- create_time_asc
- create_time_desc
- update_time_asc
- update_time_desc
(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.
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.
Filter results by catalogs with a case insensitive name. This matches substrings.
Filter results by catalogs with the specified governance type. Allowed values: governed, ungoverned, all. Default: all
Create a catalog
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.
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.
In CPD, file asset storage for a catalog is provisioned after catalog creation, via a separate call to the Asset Files API. Creating a catalog does not automatically provision this storage.
When creating a catalog in CPD, set the check_bucket_existence query parameter to false, and the request body's bucket structure should just have bucket_type set to assetfiles.
After the catalog is created, call the PUT /v2/asset_files API to create a bucket for this catalog.
Sample request body for creating a catalog in CPD:
{
"name": "catalog1",
"description": "A catalog in CPD",
"generator": "catalogadmin@mycompany.com",
"bucket": {
"bucket_type": "assetfiles"
}
}
POST /v2/catalogs
Request
Query Parameters
Whether an existence check should be performed on the catalog bucket
Default:
trueWhether to check if catalogs with the same name already exist
Default:
false
Note: name, generator, and the bucket structure are required fields in the request body.
Name of the Catalog instance
Generator of the Catalog instance
Description of the Catalog instance
Project id
Space id
Account ID
Capacity Limit
Indicates if the assets in the Catalog are governed. if not specified, it defaults to false. For private catalogs, 'false' should be always passed, because private catalogs can not be governed.
Indicates if the assets in the Catalog are allowed for profiling. if not specified
SAML instance type
UID
Response
Metadata of the Catalog instance
- metadata
GUID of the Catalog instance
URL of the Catalog instance
Example:
ibmid-50h088ud1bCreated time
Information about archiving the catalog
- archive_info
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Entity of the Catalog instance
- entity
Name of the Catalog instance
Generator of the Catalog instance
Description of the Catalog instance
Project id
Space id
Account ID
Capacity Limit
Indicates if the assets in the Catalog are governed. if not specified, it defaults to false. For private catalogs, 'false' should be always passed, because private catalogs can not be governed.
Indicates if the assets in the Catalog are allowed for profiling. if not specified
SAML instance type
UID
URL of the Catalog instance
Status Code
Created
Bad Request
Unauthorized
Forbidden
Too Many Request
No Sample Response
Response
Metadata of the Catalog instance
- metadata
GUID of the Catalog instance
URL of the Catalog instance
Example:
ibmid-50h088ud1bCreated time
Information about archiving the catalog
- archive_info
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Entity of the Catalog instance
- entity
Name of the Catalog instance
Generator of the Catalog instance
Description of the Catalog instance
Project id
Space id
Account ID
Capacity Limit
Indicates if the assets in the Catalog are governed. if not specified, it defaults to false. For private catalogs, 'false' should be always passed, because private catalogs can not be governed.
Indicates if the assets in the Catalog are allowed for profiling. if not specified
SAML instance type
UID
URL of the Catalog instance
Status Code
OK
Unauthorized
Forbidden
Not Found
Internal Server Error
No Sample Response
Request
Query Parameters
Whether an existence check should be performed on the catalog bucket
Default:
trueWhether to check if catalogs with the same name already exist
Default:
false
Example:
{
"catalog": {
"name": "The Default Catalog",
"generator": "API",
"description": "The default catalog",
"bss_account_id": "999",
"is_governed": true,
"bucket": {
"bucket_type": "assetfiles"
}
}
}
Schema for catalogEntity with bucket details
Rehome one or more synced assets.
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.
POST /v2/catalogs/default/rehome
Request
Query Parameters
Set to true to bulk re-home all synced data assets in a catalog
Synced asset to be rehomed - if omitted, all synced assets of
source_metadata_collection_idrepository will be rehomedSource metadata collection id required if all assets of single external repository need to be rehomed
Catalog containing the synced assets to be re-homed. If not specified, synced assets in the default catalog are re-homed.
Get a catalog by catalog ID
Members of the catalog can use this API to retrieve information about a catalog.
GET /v2/catalogs/{catalog_id}Request
Path Parameters
Catalog GUID or UID
Query Parameters
You must provide bss_account_id when querying for uid
Response
Metadata of the Catalog instance
- metadata
GUID of the Catalog instance
URL of the Catalog instance
Example:
ibmid-50h088ud1bCreated time
Information about archiving the catalog
- archive_info
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Entity of the Catalog instance
- entity
Name of the Catalog instance
Generator of the Catalog instance
Description of the Catalog instance
Project id
Space id
Account ID
Capacity Limit
Indicates if the assets in the Catalog are governed. if not specified, it defaults to false. For private catalogs, 'false' should be always passed, because private catalogs can not be governed.
Indicates if the assets in the Catalog are allowed for profiling. if not specified
SAML instance type
UID
URL of the Catalog instance
Status Code
OK
Bad Request
Unauthorized
Forbidden
No Sample Response
Update catalog
Use this API to update the name or description of the catalog.
PATCH /v2/catalogs/{catalog_id}Request
Custom Headers
Allowable values: [
application/json,application/json-patch+json]
Path Parameters
catalog GUID
Query Parameters
Whether to check if catalogs with the same name already exist. Only applicable if the name is to be updated.
Default:
false
JSON array of patch operations as defined in RFC 6902.
[
{ "op": "replace", "path": "/entity/name", "value": "new-name" },
{ "op": "replace", "path": "/entity/description", "value": "new-description" }
]
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".
Response
Metadata of the Catalog instance
- metadata
GUID of the Catalog instance
URL of the Catalog instance
Example:
ibmid-50h088ud1bCreated time
Information about archiving the catalog
- archive_info
Possible values: [
ARCHIVE_SCHEDULED,ARCHIVE_FAILED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED]Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000Example:
2023-05-19T01:45:20.000ZExample:
1684460720000The times that the archive/restore process failed for the asset container. Note that a successful archive/restore will reset this field.
The details of the error.
Entity of the Catalog instance
- entity
Name of the Catalog instance
Generator of the Catalog instance
Description of the Catalog instance
Project id
Space id
Account ID
Capacity Limit
Indicates if the assets in the Catalog are governed. if not specified, it defaults to false. For private catalogs, 'false' should be always passed, because private catalogs can not be governed.
Indicates if the assets in the Catalog are allowed for profiling. if not specified
SAML instance type
UID
URL of the Catalog instance
Status Code
OK
Bad Request
Unauthorized
Forbidden
Conflict
Internal Server Error
No Sample Response
Update catalog properties
Use this API to patch catalog properties.
PATCH /v2/catalogs/{catalog_id}/propertiesRequest
Custom Headers
Allowable values: [
application/json,application/json-patch+json]
Path Parameters
catalog GUID
JSON array of patch operations as defined in RFC 6902.
[
{ "op": "add", "path": "/properties/new-property", "value": "new-value" }
]
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".
Export as a zip file containing appropriate csv files for the selected assets
This API is responsible for preparing a zip file containing csv files related to the selected assets for export.
POST /v2/catalogs/export_assets
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
The id of the ibm_export_asset type asset
The list of export types the operation is expected to handle. Export Type includes
metadata, relationship, lineage. But, for now, we are supporting onlymetadata, relationship.
A json object containing a list of asset IDs; maximum of 100.
Process an import asset
This API begins processing of import assets. This function is used to import lineage mappings from EMD CSV documents.
POST /v2/catalogs/import_assets
Request
Query Parameters
The id of the import_asset
The action to perform on this import_asset. "process" (default): Validate and run an import job, "validate": Validate an import only without starting an import job.
You must provide either a catalog id, a project id, or a space id, but not more than one
When performing a processing request, proceed with the import even if validation fails. This option is only used when 'action' = 'process' (which is the default case)
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans 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.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]
Request temporary security credentials
Request temporary security credentails that can be used for storing asset attachment files.
The endpoint is currently only applicable for AWS deployments.
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
If none of above is supplied, the caller must have permission to create catalogs in the account that the access token is scoped for. The requested credentials will have permission to list and create buckets in the account.
If min_duration_seconds is supplied, the requested temporary credentials must be valid for at least the specified duration. If it is not supplied or if the cached temporary credentials of the same requirement is valid for at least specified duration, the cached credentials will be returned.
Note: when a bucket is shared, the objects in the shared bucket must have the prefix of '{catalog_id}/', e.g. '553fa5a8-bea5-43fa-9f04-b2f5ed39e6d3/myreport.csv'. All the permissions in shared buckets are granted to only allow accesing resources with the prefix of a specific catalog id.
POST /v2/catalogs/temporary_credentials
Request
Request body
Catalog id
ARN of the AWS integration role
External id for AWS integration
Name of the bucket
Indicate if the bucket is shared by multiple asset containers
Minimum duration (in seconds) that the credentials should be valid for. The value cannot be greater than 3600 seconds. If not supplied, cached credentials that have the same requested permission can be returned.
Response
AWS access key, used to identify the user interacting with AWS
AWS secret access key, used to authenticate the user interacting with AWS
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.
The epoch timestamp when the credentials will expire.
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.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
No Sample Response
Delete members from a catalog
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.
DELETE /v2/catalogs/{catalog_id}/members/bulkRequest
Path Parameters
catalog GUID
Query Parameters
Comma-separated list of Member GUIDs, with a maximum of 20.
Type of the members specified in the
member_idsparameter. Specifyuserorgroupif all members are user or access group IDs. Ifmember_idscontains a mixture of user or group IDs, then specifyallformember_typeor alternatively do not specify any value. Ifmember_typeisallor not specified, usemember_typesto indicate the type of each member inmember_idsAllowable values: [
user,group,all]Comma-separated list of types for each member specified in
member_ids. The supported types areuserandgroup. If bothmember_typesandmember_typeparameters are specified,member_typestakes precedence overmember_type. Ifmember_typesis not specified, andmember_typeis not specified or isall, 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, somember_typesshould be specified ifmember_idscontains a mixture of user and access group IDs
Create a data asset
You can use this API to add data assets to a catalog. Data assets could be data from a connection to a data source (ex. tables) or files from your local system uploaded into cloud object storage associated with Projects or Catalog.All asset types have a common set of properties, such as name, description, asset type, visibility, tags, classifications. Data Asset have additional attributes such as mime type, columns with types, and properties. Use v2/attachments API to indicate location of data (ex. table path) from a connection to a data source.
POST /v2/data_assets
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Action to take if the call would result in a duplicate asset.
IGNOREmeans the call will ignore the duplicate and create a new asset.REJECTmeans the call will fail and no asset will be created.UPDATEmeans the best matched duplicate will be updated with the incoming changes according to the predefined rules.REPLACEmeans 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.Allowable values: [
IGNORE,REJECT,UPDATE,REPLACE]Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Data Asset Metadata
- Examples:
{ "data_asset": { "mime_type": "text/csv", "dataset": false } }- entity
AssetMetadata Model
Get a data asset
Use this API to retrieve metadata about a data asset. The response document will contain three top-level fields:
- '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
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.
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'.
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. - 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.
If the above pair of fields are present in 'attachments[i]' then:
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.
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.
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.
- 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.
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.
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.
- 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.
GET /v2/data_assets/{data_asset_id}Request
Path Parameters
data_asset_id
Query Parameters
catalog_id
project_id (only catalog_id is supported at this time)
space_id (only catalog_id is supported at this time)
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Get columns of a data asset
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.
GET /v2/data_assets/{data_asset_id}/columnsRequest
Path Parameters
data_asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Revision id (1, 2, 3, ...), or leave empty for the current asset version. Use 'latest' for the most recent revision.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The maximum number of items to return
Default:
100The bookmark for the next page of results, received from a previous call.
Sorting the columns, e.g., 'data_asset.columns', '-column_info.column_info_quality_score', 'data_asset.columns,column_info.column_info_quality_score
Filter columns by name, e.g., 'A*'
Create a folder asset
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.
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"
}
}
}
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.
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.
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.
POST /v2/folder_assets
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Folder Asset Metadata
- Examples:
{ "folder_asset": { "connection_id": "f1fea17c-a7e5-49e4-9f8e-23cef3e11ed5", "connection_path": "/bucket1/folder1/folder1.1" } }- entity
AssetMetadata Model
Get a folder asset
Use this API to retrieve metadata about a folder asset.
GET /v2/folder_assets/{asset_id}Request
Path Parameters
Enter the id of the folder asset whose metadata you want to retrieve.
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated.Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Get a signed URL of an item to be downloaded
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.
GET /v2/folder_assets/{asset_id}/contentsRequest
Path Parameters
Enter the id of the folder asset whose content you want to download.
Query Parameters
The path to the object from where the folder leaves off. For example if your folder path is
/Bucket1/homedecoreand your object path is/bathrooms/sinkaccessories/soapdish1000.jpgthen the API will return a signed URL that includes the full object key/Bucket1/homedecore/bathrooms/sinkaccessories/soapdish1000.jpg.You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
The type of content you will download. Default is
application/octet-streamDefault:
application/octet-streamcontent_disposition specifies how you want the content downloaded. The default is as an attachment (i.e. a separate file).
Default:
attachment
List all assets in the trash (Marked for delete)
Retrieve all assets in the trash (Marked for delete.
GET /v2/trashed_assets
Request
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
older than the given timestamp. Format: "yyyy-MM-dd'T'hh:mm:ss[.sss]X" Example '2017-11-23T00:00:00-12', '2017-11-23T23:59:59.999Z', etc.
newer than the given timestamp. Format: "yyyy-MM-dd'T'hh:mm:ss[.sss]X" Example '2017-11-23T00:00:00-12', '2017-11-23T23:59:59.999Z', etc.
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated.Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falselimit
Default:
25bookmark
Get count of all assets in the trash (Marked for delete)
Get count of all assets in the trash (Marked for delete.
GET /v2/trashed_assets/count
Delete all assets from trash
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.
DELETE /v2/trashed_assets/purge_all
Get a soft-deleted object from trash
Get a soft-deleted object from trash.
GET /v2/trashed_assets/{asset_id}Request
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Whether to allow access to metadata when the evaluation outcome of data protection rules is Deny.
The parameter
includeis deprecated, please useexcludeinsteadExclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
false
Request
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Restore an asset from the trash
Restore an asset from the trash.
POST /v2/trashed_assets/{asset_id}/restoreRequest
Path Parameters
asset_id
Query Parameters
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
You must provide either a catalog id, a project id, or a space id, but not more than one
Exclude columns from the asset result. Available value: columns. Default value is empty, which will return the complete asset, including the columns.
Defaults to false. If true, deprecated fields are not included in the response. This parameter is provided as a way to check compatibility with future releases and remove duplicated information from responses. It has not been implemented for all deprecated fields. The primary fields that are omitted are collaborator_ids in the asset metadata rov and the owner_id field in the asset metadata.
Default:
falseAction to take if the changes to an asset would make it a duplicate to other assets.
IGNOREmeans the call will continue and update the asset anyway; as a result, the asset will become a duplicate to other assets.REJECTmeans the call will fail and the asset will not be changed. No value means the duplicate_action specified in catalogs/projects/spaces will be used.Allowable values: [
IGNORE,REJECT]
A update operation allowing you to update artifacts based on a simple query.
Execute an operation to update artifacts using a simple query for one or more specified microservices (provider_ids).
POST /v3/search/update_by_query
Execute a query based on the Lucene Syntax
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:
+ = AND operation
| = OR operation
- = NOT
" wraps a phrase
* is a wildcard (you can't use it at the beginning of a word but you can use it alone to signify match all)
( and ) evaluates tokens inside brackets with higher precedence
To use one of these characters literally, escape it with a preceding backslash.
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.
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.
GET /v3/search
Request
Custom Headers
The Tenant id (which is the BSS Account ID) within which this query is being run. Note: you can also use the header name "account_id" for this purpose.
Default:
999
Query Parameters
The Search Query. Add a list of words being sought or use a Lucene query. Your Lucene query can be as simple or as sophisticated as you like.
The maximum number of items to return
Example:
100Use simple query string syntax
Default:
falseFor governance artifacts limited by zone, limit with this role access.
Allowable values: [
viewer,editor]Default:
viewerUse cached authorization info for building ACL filters.
Default:
falseThe ACL filters applied to the query.
Allowable values: [
all,catalog,project,space,category,ibm_watsonx_governance_catalog,ibm_data_product_catalog]Default:
all
Execute a query and pass in a structured query conforming to the Elasticsearch Domain Specific Language.
Execute a query and pass in a structured query based on the Elasticsearch Domain Specific Language
For example:
{
"query": {
"match_all": {}
}
}
You can also use this API to execute the Global Search user search function as follows:
{
"query": {
"gs_user_query": {
"search_string": "the quick red fox jumped over the lazy brown dog",
"search_fields": ["metadata.name", "metadata.description"],
"nlq_analyzer_enabled": true,
"nested": false
}
}
}
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.
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.
When the natural language analyzer is enabled, words which are not relevant to the search will be ignored, and common phrases will be prioritized.
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.
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.
For more information regarding how to use this function, consult the Getting Started section of this guide.
POST /v3/search
Request
Custom Headers
The Tenant id (which is the BSS Account ID) within which this query is being run.
Default:
999
Query Parameters
For governance artifacts limited by zone, limit with this role access.
Allowable values: [
viewer,editor]Default:
viewerUse cached authorization info for building ACL filters.
Default:
falseThe ACL filters applied to the query.
Allowable values: [
all,catalog,project,space,category,ibm_watsonx_governance_catalog,ibm_data_product_catalog]Default:
all
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.
This API will return all available pre search filters
This API will return all available pre search filters
GET /v3/search/search_facet