Introduction to common core functionality APIs for Data and AI software products
You can use the common core functionality REST APIs for Data and AI software products to work with assets and their workspaces: projects, deployment spaces, and catalogs. Common core functionality is shared among multiple products, such as watsonx software, Cloud Pak for Data, and others.
If you are looking for the common core functionality APIs for SaaS products, see here.
For more information, see documentation for:
Endpoint URL
The base URL for all API endpoints is your product software deployment URL. To form a complete request URL for an API endpoint, append the method path to the base URL.
API endpoint
https://{cluster_host}
Example request
curl -H "Authorization: Bearer {access_token}" \
-X GET "https://{cluster_host}/{method_endpoint}"
Authentication
To authenticate to the API, pass an access token or platform API key token
in an Authorization header. See the
IBM Software Hub Platform API Authentication section
for more information.
Curl command with API key to retrieve token
curl -k -X POST \
https://{cluster_host}/icp4d-api/v1/authorize \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{"username":"admin","password":"password"}'
Response
{
"_messageCode_": "200",
"message": "Success",
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...."
}
Error handling
This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. 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.
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:
- entity.name - ?_sort=+entity.name
- metadata.create_time - ?_sort=-metadata.create_time
Use the following parameters to filter the results:
- entity.name - ?entity.name=MyConnection
- entity.datasource_type - ?entity.datasource_type=<asset_id>
- entity.data_source_definition_asset_id - ?entity.data_source_definition_asset_id=<dsd_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 data source definition asset id assigned to the connection. To specify multiple data source definition asset ids, use a comma-separated string, such as entity.data_source_definition_asset_id=<dsd_asset_id>,<dsd_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:
trueSpecify the id or the name of a data source type persona that the connection should present. If the data source type does not support alternate personas, then the connection's data source type is its only persona.
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:
0
curl --url {url}/v2/connections/?project_id={project_id} --header 'Accept: application/json' --header 'Authorization: Bearer {bearer_token}
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.
{ "resources": [ { "metadata": { "asset_id": "71cd92f7-08f7-48ec-b2ed-d2c6c16093df", "asset_type": "connection", "asset_category": "USER", "create_time": "2025-05-15T09:14:11.000Z", "creator_id": "1000331001", "project_id": "51b5dfbd-3c40-4c1f-860e-268b84ff0275", "resource_key": "lh_0000-0000-0000-0000", "usage": { "last_access_time": "2025-05-15T09:14:11.370Z", "last_accessor_id": "1000331001", "access_count": 0 } }, "entity": { "datasource_type": "d22e3e36-5ab3-4361-b418-2dba4b227879", "data_source_definition_searchable": "{host}|{port}|0000-0000-0000-0000", "name": "wxd_presto", "origin_country": "us", "owner_id": "1000331001", "rov": { "mode": 0, "member_roles": { "1000331001": { "user_iam_id": "1000331001", "roles": [ "OWNER" ] } } }, "properties": { "ssl_certificate": "{ssl_certificate}", "deployment_type": "software_dev", "password": "{password}", "instance_id": "0000-0000-0000-0000", "port": "{port}", "engine_id": "presto-01", "host": "{host}", "engine_host": "{host}", "ssl": "true", "engine_port": "{engine_port}", "username": "{username}" }, "interaction_properties": { "source": [ { "name": "table_name", "type": "string", "label": "Table name", "description": "The name of the table to read from", "descriptionHasLink": false, "required": true, "masked": false, "hidden": false, "readonly": false, "uiOnly": false, "multiline": false, "multichoice": false, "displayGroup": "generalSource", "displayOrdinal": 60, "user_defined": false, "user_defined_for_external": false } ], "target": [ { "name": "table_name", "type": "string", "label": "Table name", "description": "The name of the table to write to", "descriptionHasLink": false, "required": true, "masked": false, "hidden": false, "readonly": false, "uiOnly": false, "multiline": false, "multichoice": false, "displayGroup": "generalTarget", "displayOrdinal": 30, "user_defined": false, "user_defined_for_external": false } ] } } } ], "first": { "href": "{url}/v2/connections?project_id=51b5dfbd-3c40-4c1f-860e-268b84ff0275&userfs=false&limit=100" }, "total_count": 1 }
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.
Resource key that should be set in connection asset metadata record instead of using a calculated one by the service.
curl --request POST --url '{url}/v2/connections?test=true&project_id={project_id}' --header 'Accept: application/json' --header 'Authorization: Bearer {bearer_token}' --header 'Content-Type: application/json' --data '{"datasource_type":"d22e3e36-5ab3-4361-b418-2dba4b227879", "properties":{"ssl":"true","deployment_type":"software_dev", "host":"{host}","port":"{port}", "instance_id":"0000-0000-0000-0000", "username":"{username}","password":"{password}", "engine_host":"{host}","engine_id":"presto-01","engine_port":"{engine_port}", "ssl_certificate":"{ssl_certificate}"}, "flags":[],"name":"wxd_presto","origin_country":"us"}'
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.
{ "metadata": { "asset_id": "d096f50b-1eb7-455d-9948-64717b851279", "asset_type": "connection", "asset_category": "USER", "create_time": "2025-05-16T11:22:05.000Z", "creator_id": "1000331001", "project_id": "51b5dfbd-3c40-4c1f-860e-268b84ff0275", "resource_key": "lh_0000-0000-0000-0000", "usage": { "last_access_time": "2025-05-16T11:22:05.597Z", "last_accessor_id": "1000331001", "access_count": 0 } }, "entity": { "datasource_type": "d22e3e36-5ab3-4361-b418-2dba4b227879", "data_source_definition_searchable": "{host}|{port}|0000-0000-0000-0000", "derived_properties": { "data_source_definition_id": "lakehouse", "data_source_identity_properties": [ { "name": "host", "value": "{host}" }, { "name": "port", "value": "{port}" }, { "name": "instance_id", "value": "0000-0000-0000-0000" } ], "data_source_identity_mapping": { "instance_id": "physical_collection", "port": "port", "host": "host" } }, "name": "wxd_presto2", "origin_country": "us", "owner_id": "1000331001", "rov": { "mode": 0, "member_roles": { "1000331001": { "user_iam_id": "1000331001", "roles": [ "OWNER" ] } } }, "properties": { "ssl_certificate": "{ssl_certificate}", "deployment_type": "software_dev", "password": "password", "instance_id": "0000-0000-0000-0000", "port": "{port}", "engine_id": "presto-01", "host": "{host}", "engine_host": "{host}", "ssl": "true", "engine_port": "{engine_port}", "username": "ibmlhadmin" }, "interaction_properties": { "source": [ { "name": "table_name", "type": "string", "label": "Table name", "description": "The name of the table to read from", "descriptionHasLink": false, "required": true, "masked": false, "hidden": false, "readonly": false, "uiOnly": false, "multiline": false, "multichoice": false, "displayGroup": "generalSource", "displayOrdinal": 60, "user_defined": false, "user_defined_for_external": false } ], "target": [ { "name": "table_name", "type": "string", "label": "Table name", "description": "The name of the table to write to", "descriptionHasLink": false, "required": true, "masked": false, "hidden": false, "readonly": false, "uiOnly": false, "multiline": false, "multichoice": false, "displayGroup": "generalTarget", "displayOrdinal": 30, "user_defined": false, "user_defined_for_external": false } ] } } }
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 'ai_factsheet', 'autoai', 'catalog', 'cde', 'cpd', 'dashboardsonprem', 'datarefinery', 'datastage', 'datastage_scapi', 'decision_optimization', 'deployments', 'dph', 'dqr', 'dv', 'dvaas', 'dvaas_ga', 'dvonprem', 'federated_learning', 'governance', 'igc', 'instructlab', 'manta', 'manta_legacy', 'masking_flow', 'mde', 'mdi', 'notebook', 'orchestration_pipelines', 'replication', 'rstudio', 'spss_modeler', 'streamsets', 'udp' and 'wxbia'. If no entity.product is specified, no filtering is applied. To specify multiple products, use a comma-separated string, such as entity.product=catalog,datastage.
Whether to return information about source and target interaction properties.
Whether to return decrypted secrets for unrestricted connections.
Default:
trueThe ID of the function which if specified, then the credentials for function are returned/stored rather than personal or shared credentials.
Specify the id or the name of a data source type persona that the connection should present. If the data source type does not support alternate personas, then the connection's data source type is its only persona.
curl --url {url}/v2/connections/{connection_id}?project_id={project_id} --header 'Accept: application/json' --header 'Authorization: Bearer {bearer_token}
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.
{ "metadata": { "asset_id": "71cd92f7-08f7-48ec-b2ed-d2c6c16093df", "asset_type": "connection", "asset_category": "USER", "create_time": "2025-05-15T09:14:11.000Z", "creator_id": "1000331001", "project_id": "51b5dfbd-3c40-4c1f-860e-268b84ff0275", "resource_key": "lh_0000-0000-0000-0000", "usage": { "last_access_time": "2025-05-15T09:14:11.370Z", "last_accessor_id": "1000331001", "access_count": 0 } }, "entity": { "datasource_type": "d22e3e36-5ab3-4361-b418-2dba4b227879", "data_source_definition_searchable": "{host}|{port}|0000-0000-0000-0000", "name": "wxd_presto", "origin_country": "us", "owner_id": "1000331001", "rov": { "mode": 0, "member_roles": { "1000331001": { "user_iam_id": "1000331001", "roles": [ "OWNER" ] } } }, "properties": { "ssl_certificate": "{ssl_certficate}", "deployment_type": "software_dev", "password": "{password}", "instance_id": "0000-0000-0000-0000", "port": "{port}", "engine_id": "presto-01", "host": { "host": null }, "engine_host": { "host": null }, "ssl": "true", "engine_port": "{engine_port}", "username": "{username}" }, "interaction_properties": { "source": [ { "name": "read_mode", "type": "enum", "label": "Read method", "description": "The method for reading records from the table", "descriptionHasLink": false, "required": false, "masked": false, "hidden": false, "readonly": false, "uiOnly": false, "multiline": false, "multichoice": false, "default_value": "general", "values": [ { "value": "general", "label": "General" }, { "value": "select", "label": "Select statement" } ], "displayGroup": "generalSource", "displayOrdinal": 5, "user_defined": false, "user_defined_for_external": false } ], "target": [ { "name": "table_action", "type": "enum", "label": "Table action", "description": "The action to take on the target table to handle the new data set", "descriptionHasLink": false, "required": false, "masked": false, "hidden": false, "readonly": false, "uiOnly": false, "multiline": false, "multichoice": false, "default_value": "create", "values": [ { "value": "append", "label": "Append" }, { "value": "create", "label": "Create" }, { "value": "replace", "label": "Replace" }, { "value": "truncate", "label": "Truncate" } ], "displayGroup": "generalTarget", "displayOrdinal": 40, "user_defined": false, "user_defined_for_external": false } ] } } }
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
curl --request DELETE --url '{url}/v2/connections/{connection_id}?test=true&project_id={project_id}' --header 'Accept: application/json' --header 'Authorization: Bearer {bearer_token}' --header 'Content-Type: application/json'
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.
{ "trace": "c1q5eufjd8n2bzrk2p3l1ji4i", "errors": [ { "code": "not_found", "message": "A connection with the specified connection ID [{connection_id}] does not exist.", "more_info": "Correct the ID and resubmit the request.", "extra": { "environment_name": "icp4data", "http_status": 404, "id": "CDICO9006E", "source_cluster": null, "source_component": "wdp-connect-connection", "timestamp": "2025-05-19T08:25:00.207Z" } } ] }
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:
trueThe ID of the function which if specified, then the credentials for function are returned/stored rather than personal or shared credentials.
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
curl -X 'PATCH' '{url}/v2/connections/{connection_id}?test=true&persist=true&project_id={project_id}&userfs=false' -H 'accept: application/json;charset=utf-8' -H 'Skip-Enforcement: false' -H 'Authorization: Bearer {bearer_token}' -H 'Content-Type: application/json-patch+json;charset=utf-8' -d '[{"op":"replace","path":"/name","value":"wxd_presto2"},{"op":"add","path":"/properties/instance_name","value":"lakehouse"}]'
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.
Resource key that should be set in connection asset metadata record instead of using a calculated one by the service.
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.
{ "datasource_type": "d22e3e36-5ab3-4361-b418-2dba4b227879", "name": "wxd_presto2", "origin_country": "us", "owner_id": "1000331001", "rov": { "mode": 0, "member_roles": { "1000331001": { "user_iam_id": "1000331001", "roles": [ "OWNER" ] } } }, "properties": { "ssl_certificate": "{ssl_certificate}", "password": "{password}", "instance_id": "0000-0000-0000-0000", "instance_name": "lakehouse", "port": "{port}", "engine_id": "presto-01", "host": { "host": null }, "engine_host": { "host": null }, "ssl": "true", "engine_port": "{engine_port}", "username": "{username}" }, "interaction_properties": { "source": [ { "name": "catalog_name", "type": "string", "label": "Catalog name", "description": "The name of the catalog that contains the schema to read from. It is required when a fully qualified table name has not been provided.", "required": false, "masked": false, "hidden": false, "readonly": false, "uiOnly": false, "multiline": false, "multichoice": false, "displayGroup": "generalSource", "displayOrdinal": 40, "user_defined": false } ], "target": [ { "name": "catalog_name", "type": "string", "label": "Catalog name", "description": "The name of the catalog that contains the schema to write to. It is required when a fully qualified table name has not been provided.", "required": false, "masked": false, "hidden": true, "readonly": false, "uiOnly": false, "multiline": false, "multichoice": false, "displayGroup": "generalTarget", "displayOrdinal": 2147483647, "user_defined": false } ] } }
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.
Example:
iceberg_data%2Ficeberg_schemaThe 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.
Resource key that should be set in connection asset metadata record instead of using a calculated one by the service.
curl -X 'POST' 'https://{url}/v2/connections/assets?path={path_to_asset}&limit=100&offset=0' -H 'accept: application/json;charset=utf-8' -H 'Authorization: Bearer {bearer_token}' -H 'Content-Type: application/json;charset=utf-8' -d '{ "datasource_type": "d22e3e36-5ab3-4361-b418-2dba4b227879", "name": "wxd_presto2", "origin_country": "us", "owner_id": "1000331001", "rov": { "mode": 0, "member_roles": { "1000331001": { "user_iam_id": "1000331001", "roles": [ "OWNER" ] } } }, "properties": { "ssl_certificate": "{ssl_certificate}", "password": "{passwprd}", "instance_id": "0000-0000-0000-0000", "instance_name": "lakehouse", "port": "{port}", "engine_id": "presto-01", "host": "{host}", "engine_host": "{engine_host}", "ssl": "true", "engine_port": "{engine_port}", "username": "{username}" }, "interaction_properties": { "source": [ { "name": "table_name", "type": "string", "label": "Table name", "description": "The name of the table to read from", "required": true, "masked": false, "hidden": false, "readonly": false, "uiOnly": false, "multiline": false, "multichoice": false, "displayGroup": "generalSource", "displayOrdinal": 60, "user_defined": false } ], "target": [ { "name": "table_name", "type": "string", "label": "Table name", "description": "The name of the table to write to", "required": true, "masked": false, "hidden": true, "readonly": false, "uiOnly": false, "multiline": false, "multichoice": false, "displayGroup": "generalTarget", "displayOrdinal": 2147483647, "user_defined": false } ] } }'
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.
{ "path": "iceberg_data/iceberg_schema", "asset_types": [ { "type": "table", "dataset": true, "dataset_container": false } ], "assets": [ { "id": "elt_src_set6", "type": "table", "name": "elt_src_set6", "path": "/iceberg_data/iceberg_schema/elt_src_set6" }, { "id": "reptile", "type": "table", "name": "reptile", "path": "/iceberg_data/iceberg_schema/reptile" }, { "id": "sample_view", "type": "table", "name": "sample_view", "path": "/iceberg_data/iceberg_schema/sample_view" }, { "id": "t004_action_get_record_count_s3_dev_mac_1747389044258", "type": "table", "name": "t004_action_get_record_count_s3_dev_mac_1747389044258", "path": "/iceberg_data/iceberg_schema/t004_action_get_record_count_s3_dev_mac_1747389044258" }, { "id": "test_before_after_sql_dev1", "type": "table", "name": "test_before_after_sql_dev1", "path": "/iceberg_data/iceberg_schema/test_before_after_sql_dev1" } ] }
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.
Example:
iceberg_data%2Ficeberg_schemaThe 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.
curl -X 'GET' '{url}/v2/connections/{connection_id}/assets?path={path_to_asset}&project_id={project_id}&userfs=false&limit=100&offset=0' -H 'accept: application/json;charset=utf-8' -H 'Authorization: Bearer {bearer_token}'
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.
{ "path": "iceberg_data/iceberg_schema", "asset_types": [ { "type": "table", "dataset": true, "dataset_container": false } ], "assets": [ { "id": "elt_src_set6", "type": "table", "name": "elt_src_set6", "path": "/iceberg_data/iceberg_schema/elt_src_set6" }, { "id": "reptile", "type": "table", "name": "reptile", "path": "/iceberg_data/iceberg_schema/reptile" }, { "id": "sample_view", "type": "table", "name": "sample_view", "path": "/iceberg_data/iceberg_schema/sample_view" }, { "id": "t004_action_get_record_count_s3_dev_mac_1747389044258", "type": "table", "name": "t004_action_get_record_count_s3_dev_mac_1747389044258", "path": "/iceberg_data/iceberg_schema/t004_action_get_record_count_s3_dev_mac_1747389044258" }, { "id": "test_before_after_sql_dev1", "type": "table", "name": "test_before_after_sql_dev1", "path": "/iceberg_data/iceberg_schema/test_before_after_sql_dev1" } ] }{ "trace": "2o19zmke6jfdnti89az0t1sgn", "errors": [ { "code": "not_found", "message": "The asset with id 79269454-1d51-49e4-aed8-f1739dd5e52a could not be found.", "extra": { "environment_name": "icp4data", "http_status": 404, "id": "CDICW9031E", "source_cluster": "NULL", "source_component": "wdp-connect-connection", "timestamp": "2025-05-20T11:38:44.429Z" } } ] }
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.
curl --request GET --url '{url}/v2/connections/assets/{asset_id}?project_id={project_id}&userfs=false&limit=100&offset=0' --header 'Authorization: Bearer {bearer_token}' --header 'Content-Type: application/json' --header 'accept: application/json;charset=utf-8'
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.
{ "connections_discovered_asset_collection": { "summary": "Connections Discovered Asset Collection", "value": { "path": "data_asset/Book1.csv", "fields": [ { "name": "aaa", "columnProperties": {}, "type": { "type": "varchar", "length": 1024, "scale": 0, "nullable": true, "signed": false } }, { "name": " bbb", "columnProperties": {}, "type": { "type": "varchar", "length": 1024, "scale": 0, "nullable": true, "signed": false } }, { "name": " ccc", "columnProperties": {}, "type": { "type": "varchar", "length": 1024, "scale": 0, "nullable": true, "signed": false } } ], "first": { "href": "{url}/v2/connections/assets/e4adc79b-be7f-4c42-a48f-d0203942b0eb?project_id=04213ccd-523d-4122-a101-6e4d78fd2af8&userfs=false&offset=0&limit=100" }, "prev": { "href": "{url}/v2/connections/assets?offset=0&limit=100&path=data_asset%2FBook1.csv" }, "next": { "href": "{url}/v2/connections/assets?offset=100&limit=100&path=data_asset%2FBook1.csv" }, "total_count": 1 } } }
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
curl -X 'GET' 'https://{url}/v2/connections/{connection_id}/actions?project_id={project_id}&userfs=false' -H 'accept: application/json;charset=utf-8' -H 'Accept-Language: en-US' -H 'Authorization: Bearer {bearer_token}'
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:
- get_datasource_info - to get Data source info of a datasource.
- 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_approx_record_count - to get the approximate number of records available for the specified asset.
- get_signed_url - to get a signed URL for accessing a datasource.
- test - to check if a connection can be established to the datasource.
- validate - to validate the connection properties without establishing a connection.
Allowable values: [
get_datasource_info,get_dsd_details,get_oauth2_tokens,get_record_count,get_approx_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
curl -X 'PUT' '{url}/v2/connections/{connection_id}/actions/validate?project_id={project_id}&userfs=false' -H 'accept: application/json;charset=utf-8' -H 'Authorization: Bearer {bearer_token}' -H 'Content-Type: application/json;charset=utf-8' -d '{ "engine_host": "{engine_host}", "host": "{host}" }'
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.
{ "connection_action_response": { "summary": "Connection action response", "value": { "resource_key": "lh_0000-0000-0000-0000" } } }
Request
Path Parameters
The name of file to download
Query Parameters
The hash of file to download
curl -X 'GET' 'https://{url}/v2/connections/files/{file_name}?hash={file_hash}' -H 'accept: application/octet-stream'
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.
Upload a file
Upload a file and get back a signed handle in 'Location' header with a hash
POST /v2/connections/files/{file_name}Request
Path Parameters
The name of file to upload
curl -X 'POST' '{url}/v2/connections/files/{file_name}' -H 'accept: */*' -H 'Authorization: Bearer {bearer_token}' -H 'Content-Type: application/octet-stream' --data-binary '@{file_path}'
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
Request
Path Parameters
The name of file to delete
Query Parameters
The hash of file to delete
curl -X 'DELETE' '{url}/v2/connections/files/{file_name}?hash={file_hash}' -H 'accept: */*' -H 'Authorization: Bearer {bearer_token}'
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
curl --request GET --url '{url}/v2/connections/files?limit=100&offset=0' --header 'Accept: application/json' --header 'Authorization: Bearer {bearer_token}'
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.
{ "connection_action_response": { "summary": "Connection action response", "value": { "resources": [ { "createdAt": "2025-05-22T09:11:58.733917839Z", "url": "/v2/connections/files/book1_csv?hash=e3dkcGFlczI1Nn14UEthdFBTM1VDbEh4OEM2MTFCcE9JNEtRZzlOQUdraXVxcHNYVER1WWpMK0ZPR09nMkJYQVlWQ0FjMVZ4blZJZVJYYW9QaEF0a08xYjJteUNqOXdZK2x4MXdyK2ZKYmY5L0h6RzM2R0E4ZkFoVlk0YzMvOXNqZWhzNnpFRzJQZDQ5TkV1RXZGMk10c21BemNKTTdOYUpMblBwaXpjdk40dzJMblV2bVl1T2c9&digest=zMwdUQJxJhUG8EOMvHzIsghMTs4UWhRKa5fFZWNnhSYx_5f53e4cbx81b6x46f7xa712x67756378a441", "hash": "e3dkcGFlczI1Nn14UEthdFBTM1VDbEh4OEM2MTFCcE9JNEtRZzlOQUdraXVxcHNYVER1WWpMK0ZPR09nMkJYQVlWQ0FjMVZ4blZJZVJYYW9QaEF0a08xYjJteUNqOXdZK2x4MXdyK2ZKYmY5L0h6RzM2R0E4ZkFoVlk0YzMvOXNqZWhzNnpFRzJQZDQ5TkV1RXZGMk10c21BemNKTTdOYUpMblBwaXpjdk40dzJMblV2bVl1T2c9", "digest": "zMwdUQJxJhUG8EOMvHzIsghMTs4UWhRKa5fFZWNnhSYx_5f53e4cbx81b6x46f7xa712x67756378a441", "fileName": "book1_csv" }, { "createdAt": "2025-05-23T11:15:30.373931581Z", "url": "/v2/connections/files/book1_csv_2?hash=e3dkcGFlczI1Nn1kWTdadkswRXczN1dZbEtwUTRYYjRPbkhWVE9taVZZVzdxcndTSU1NMWpKWUEydlNRTGswV1lmSkZCd2FHRGNweFRCcmZobUNuMnBDRW8wWEpEamJ5YmpvM0FXVzhRY2RwRUk1OHlCYXN1b1h4aUI4aFlxcms3OUZsUmtGWHdGWXhJR0VnN2lmQVgxcG5oQmVkek14QlVGZVBVUkpLUkNIU2FVVUdTUVIydDA9&digest=zMwdUQJxJhUG8EOMvHzIsghMTs4UWhRKa5fFZWNnhSYx_259d2dddxc2d4x4b15xa3d9x1329f9ac583d", "hash": "e3dkcGFlczI1Nn1kWTdadkswRXczN1dZbEtwUTRYYjRPbkhWVE9taVZZVzdxcndTSU1NMWpKWUEydlNRTGswV1lmSkZCd2FHRGNweFRCcmZobUNuMnBDRW8wWEpEamJ5YmpvM0FXVzhRY2RwRUk1OHlCYXN1b1h4aUI4aFlxcms3OUZsUmtGWHdGWXhJR0VnN2lmQVgxcG5oQmVkek14QlVGZVBVUkpLUkNIU2FVVUdTUVIydDA9", "digest": "zMwdUQJxJhUG8EOMvHzIsghMTs4UWhRKa5fFZWNnhSYx_259d2dddxc2d4x4b15xa3d9x1329f9ac583d", "fileName": "book1_csv_2" }, { "createdAt": "2025-05-23T11:15:18.714000849Z", "url": "/v2/connections/files/book1_csv_2?hash=e3dkcGFlczI1Nn1UQ0VPaEtXcnA3cElqMUxyZEVmS1N1TVF6TWRIMVFTWXc0V2Q4ME10K1BWNkFTMzRrdXVLc3hmSEt1eVVwU3BXL0FWaXRCWi9NWVB0Z1J3T091dDVTdnpQRDNjMWpoVEtQMUFTTFpob3JjdkEyRTQ4U1pQOTNMU1g3clFBSHJuaDhOZExuR0lZUWVuNjczK2k1TEE2ZnB1ZGF0VGNaOGhHNnVLNDBLSk1ybTA9&digest=zMwdUQJxJhUG8EOMvHzIsghMTs4UWhRKa5fFZWNnhSYx_6971721cxf318x4dabx963ax0a7be614328e", "hash": "e3dkcGFlczI1Nn1UQ0VPaEtXcnA3cElqMUxyZEVmS1N1TVF6TWRIMVFTWXc0V2Q4ME10K1BWNkFTMzRrdXVLc3hmSEt1eVVwU3BXL0FWaXRCWi9NWVB0Z1J3T091dDVTdnpQRDNjMWpoVEtQMUFTTFpob3JjdkEyRTQ4U1pQOTNMU1g3clFBSHJuaDhOZExuR0lZUWVuNjczK2k1TEE2ZnB1ZGF0VGNaOGhHNnVLNDBLSk1ybTA9", "digest": "zMwdUQJxJhUG8EOMvHzIsghMTs4UWhRKa5fFZWNnhSYx_6971721cxf318x4dabx963ax0a7be614328e", "fileName": "book1_csv_2" }, { "createdAt": "2025-05-22T09:17:09.542080302Z", "url": "/v2/connections/files/book1_csv_2?hash=e3dkcGFlczI1Nn1aRzY2bS9yb09IbENsVWREQnc0cFg2cno2R0dweWEvdkFSaGFjMm9HZjNJOWlrQnVqY0h6WFErdW9jNG9zR0MxMGhEbmpnNmZZUkxCVjVrUUZiY0tIYnpINk1wTkRJZS9jT1pYV09jdDhCQmZEU0FIQVRYY25Pd3VqbUNpOXY2UzNsbkpjMGd2QlhoWmFBVDlrcnB2Sks2dDdjbGVkQjBBY2laRWZEcHNBUXM9&digest=zMwdUQJxJhUG8EOMvHzIsghMTs4UWhRKa5fFZWNnhSYx_3d65737cx20d3x470axbf50x3677179bebf6", "hash": "e3dkcGFlczI1Nn1aRzY2bS9yb09IbENsVWREQnc0cFg2cno2R0dweWEvdkFSaGFjMm9HZjNJOWlrQnVqY0h6WFErdW9jNG9zR0MxMGhEbmpnNmZZUkxCVjVrUUZiY0tIYnpINk1wTkRJZS9jT1pYV09jdDhCQmZEU0FIQVRYY25Pd3VqbUNpOXY2UzNsbkpjMGd2QlhoWmFBVDlrcnB2Sks2dDdjbGVkQjBBY2laRWZEcHNBUXM9", "digest": "zMwdUQJxJhUG8EOMvHzIsghMTs4UWhRKa5fFZWNnhSYx_3d65737cx20d3x470axbf50x3677179bebf6", "fileName": "book1_csv_2" } ], "offset": 0, "total_count": 4 } } }
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:
- 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 'private', 'public' 'spark', 'streams', 'java', 'local' and 'external'. 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=private,public.
Specify the perspective the data source types must support to be included in the returned list. The available perspectives are 'cpd', 'dph', 'wx'. If no entity.perspective is specified, no filtering is applied. To specify multiple perspectives, use a comma-separated string, such as entity.perspective=cpd,wx.
Specify the product the data source type must support to be returned. The available products are 'ai_factsheet', 'autoai', 'catalog', 'cde', 'cpd', 'dashboardsonprem', 'datarefinery', 'datastage', 'datastage_scapi', 'decision_optimization', 'deployments', 'dph', 'dqr', 'dv', 'dvaas', 'dvaas_ga', 'dvonprem', 'federated_learning', 'governance', 'igc', 'instructlab', 'manta', 'manta_legacy', 'masking_flow', 'mde', 'mdi', 'notebook', 'orchestration_pipelines', 'replication', 'rstudio', 'spss_modeler', 'streamsets', 'udp' and 'wxbia'. If no entity.product is specified, no filtering is applied. To specify multiple products, use a comma-separated string, such as entity.product=catalog,datastage.
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:
falseWhether to show data source definition asset feature metadata properties or not.
Default:
true
curl -X 'GET' '{url}/v2/datasource_types?offset=0&limit=100&generate_transitive_conditions=false&show_data_source_definitions_only=false&show_data_source_definition_section=true' -H 'accept: application/json;charset=utf-8' -H 'Accept-Language: en-US' -H 'Authorization: Bearer {bearer_token}'
Response
A page from a collection of data source types.
List of data source types
Contains map of key as resourceId and value as resourceName
- fips_noncompliant_resources
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.
{ "resources": [ { "metadata": { "asset_id": "029e5d1c-ba73-4b09-b742-14c3a39b6cf9", "asset_type": "datasource_type", "creator_id": "IBM" }, "entity": { "name": "informix", "label": "IBM Informix", "description": "IBM Informix is a database that contains relational, object-relational, or dimensional data. You can use the Informix connector to access data from an on-prem Informix database server or from IBM Informix on Cloud.", "type": "database", "allowed_as_source": true, "allowed_as_target": true, "allowed_for_discovery_only": false, "allowed_as_source_lookup": true, "data_shape": "rectangular", "auto_discovery": false, "secure_gateway": "optional", "fips_compliance": "none", "tags": [ "IBM" ], "supported_environments": [ "cloud", "java", "local", "private", "spark" ], "supported_plans": [], "supported_products": [ "catalog", "cpd", "dashboards", "dashboardsonprem", "datarefinery", "datastage", "datastage_scapi", "dv", "dvaas_ga", "mde", "mdi", "ml", "studio" ], "status": "active", "extensible": false } }, { "metadata": { "asset_id": "048ed1bf-516c-46f0-ae90-fa3349d8bc1c", "asset_type": "datasource_type", "creator_id": "IBM" }, "entity": { "name": "postgresql-ibmcloud", "label": "IBM Cloud Databases for PostgreSQL", "description": "IBM Cloud Databases for PostgreSQL is an open-source object-relational database that is highly customizable. It's a feature-rich enterprise database with JSON support. For the PostgreSQL connector that is not on IBM Cloud, select the PostgreSQL connector.", "type": "database", "allowed_as_source": true, "allowed_as_target": true, "allowed_for_discovery_only": false, "allowed_as_source_lookup": true, "data_shape": "rectangular", "auto_discovery": true, "secure_gateway": "not_applicable", "tags": [ "IBM" ], "supported_environments": [ "cloud", "java", "local", "private", "spark" ], "supported_plans": [], "supported_products": [ "catalog", "cde", "cdeonprem", "cpd", "dashboards", "dashboardsonprem", "datarefinery", "datastage", "datastage_scapi", "dv", "dvaas_ga", "manta", "mdi", "ml", "studio" ], "status": "active", "extensible": false } }, { "metadata": { "asset_id": "05b7f0ea-6ae4-45e2-a455-cc280f110825", "asset_type": "datasource_type", "creator_id": "IBM" }, "entity": { "name": "googlecloudstorage", "label": "Google Cloud Storage", "description": "Google Cloud Storage is an online file storage web service for storing and accessing data on Google Cloud Platform Infrastructure.", "type": "file", "allowed_as_source": true, "allowed_as_target": true, "allowed_for_discovery_only": false, "allowed_as_source_lookup": false, "data_shape": "rectangular", "auto_discovery": false, "secure_gateway": "not_applicable", "supported_environments": [ "cloud", "java", "local", "private", "spark" ], "supported_plans": [], "supported_products": [ "catalog", "cpd", "datarefinery", "datastage", "datastage_scapi", "mdi", "ml", "studio" ], "status": "active", "extensible": false } } ], "first": { "href": "{url}/v2/datasource_types?limit=100" }, "last": { "href": "{url}/v2/datasource_types?offset=0&limit=100" }, "offset": 0, "total_count": 3 }
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".
The locale of labels and descriptions.
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.
curl -X 'POST' '{url}/v2/datasource_types' -H 'accept: application/json;charset=utf-8' -H 'Authorization: Bearer {bearer_token}' -H 'Content-Type: application/json;charset=utf-8' -d '{ "base_datasource_type": "e59b1c36-6f30-4879-9f74-7e81dde4cca6", "name": "new_custom_datasource", "label": "Custom JDBC datasource", "description": "Custom datasource for test purposes.", "allowed_as_source": true, "allowed_as_target": true, "status": "active", "origin_country": "us", "owner_id": "1000331001", "rov": { "mode": 0, "member_roles": { "1000331001": { "user_iam_id": "1000331001", "roles": [ "OWNER" ] } } }, "properties": { "row_limit_support": "none", "password": "{password}", "jdbc_url": "{jdbc_url}", "jdbc_driver": "{jdbc_driver}", "username": "TM_CC_USER_1" }, "property_definitions": [ { "name": "string", "type": "boolean", "label": "string", "description": "string", "placeholder": "string", "required": true, "masked": true, "multiline": true, "hidden": true, "default_value": "string", "values": [ { "value": "string", "label": "string", "supported_environments": [ "private" ], "supported_products": [ "catalog", "studio" ] } ], "group": "string" } ], "source_system": { "name": "_java._heap_size", "type": "integer", "label": "Heap size", "description": "Specify the maximum Java Virtual Machine heap size in megabytes.", "descriptionHasLink": false, "required": false, "masked": false, "hidden": false, "readonly": false, "uiOnly": false, "multiline": false, "multichoice": false, "default_value": "512", "displayGroup": "other", "displayOrdinal": 2147483647, "supported_products": [ "datastage_scapi" ], "user_defined": false, "user_defined_for_external": false } }'
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.
{ "datasource_types": [ { "metadata": { "asset_id": "2a2466dd-c444-4f19-8bb3-68f870fc963d", "asset_type": "datasource_type", "asset_category": "SYSTEM", "catalog_id": "efbf8bd5-cff2-4811-9566-637a49f4d1eb", "create_time": "2025-05-29T10:41:50.000Z", "creator_id": "1000331001", "owner_id": "1000331001", "source_system": { "created": 0, "last_modified": 0 }, "usage": { "last_access_time": "2025-05-29T10:41:50.680Z", "last_accessor_id": "1000331001", "access_count": 0 } }, "entity": { "base_datasource_type": "e59b1c36-6f30-4879-9f74-7e81dde4cca6", "name": "new_custom_datasource", "label": "Custom JDBC datasource", "description": "Custom datasource for test purposes.", "allowed_as_source": true, "allowed_as_target": true, "properties": { "row_limit_support": "none", "password": "{password}", "jdbc_driver": { "jdbc_driver": null }, "jdbc_url": { "jdbc_url": null }, "username": "TM_CC_USER_1" }, "property_definitions": [ { "name": "string", "type": "boolean", "label": "string", "description": "string", "placeholder": "string", "required": true, "masked": true, "multiline": true, "hidden": true, "default_value": "string", "values": [ { "value": "string", "label": "string", "supported_environments": [ "private" ], "supported_products": [ "catalog", "studio" ] } ], "group": "string" } ], "status": "active", "origin_country": "us", "owner_id": "1000331001", "rov": { "mode": 0, "member_roles": { "1000331001": { "user_iam_id": "1000331001", "roles": [ "OWNER" ] } } } } } ] }
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 'private', 'public' 'spark', 'streams', 'java', 'local' and 'external'. 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=private,public.
Specify the perspective the data source types must support to be included in the returned list. The available perspectives are 'cpd', 'dph', 'wx'. If no entity.perspective is specified, no filtering is applied. To specify multiple perspectives, use a comma-separated string, such as entity.perspective=cpd,wx.
Specify the product the data source type must support to be returned. The available products are 'ai_factsheet', 'autoai', 'catalog', 'cde', 'cpd', 'dashboardsonprem', 'datarefinery', 'datastage', 'datastage_scapi', 'decision_optimization', 'deployments', 'dph', 'dqr', 'dv', 'dvaas', 'dvaas_ga', 'dvonprem', 'federated_learning', 'governance', 'igc', 'instructlab', 'manta', 'manta_legacy', 'masking_flow', 'mde', 'mdi', 'notebook', 'orchestration_pipelines', 'replication', 'rstudio', 'spss_modeler', 'streamsets', 'udp' and 'wxbia'. If no entity.product is specified, no filtering is applied. To specify multiple products, use a comma-separated string, such as entity.product=catalog,datastage.
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 show data source definition asset feature metadata properties or not.
Default:
true
curl -X 'GET' '{url}/v2/datasource_types/{datasource_type_id}?generate_transitive_conditions=false&show_data_source_definition_section=true' -H 'accept: application/json;charset=utf-8' -H 'Accept-Language: en-US' -H 'Authorization: Bearer {bearer_token}'
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.
{ "metadata": { "asset_id": "029e5d1c-ba73-4b09-b742-14c3a39b6cf9", "asset_type": "datasource_type", "creator_id": "IBM" }, "entity": { "name": "informix", "label": "IBM Informix", "description": "IBM Informix is a database that contains relational, object-relational, or dimensional data. You can use the Informix connector to access data from an on-prem Informix database server or from IBM Informix on Cloud.", "type": "database", "allowed_as_source": true, "allowed_as_target": true, "allowed_for_discovery_only": false, "allowed_as_source_lookup": true, "data_shape": "rectangular", "auto_discovery": false, "secure_gateway": "optional", "fips_compliance": "140-2", "tags": [ "IBM" ], "supported_environments": [ "cloud", "java", "local", "private", "spark" ], "supported_plans": [], "supported_products": [ "catalog", "cpd", "dashboards", "dashboardsonprem", "datarefinery", "datastage", "datastage_scapi", "dv", "dvaas_ga", "mde", "mdi", "ml", "studio" ], "status": "active", "extensible": false } }
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}Request
Path Parameters
The data source type.
curl -X 'DELETE' '{url}/v2/datasource_types/{datasource_type}' -H 'accept: */*' -H 'Authorization: Bearer {bearer_token}'
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
curl -X 'PATCH' '{url}/v2/datasource_types/{data_source_type}' -H 'accept: application/json;charset=utf-8' -H 'Authorization: Bearer {bearer_token}' -H 'Content-Type: application/json-patch+json;charset=utf-8' -d '[ { "op": "replace", "path": "/name", "from": "custom_datasource", "value": "new_name_for_custom_datasource" } ]'
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".
The locale of labels and descriptions.
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.
{ "base_datasource_type": "e59b1c36-6f30-4879-9f74-7e81dde4cca6", "name": "new_name_for_custom_datasource", "label": "Custom datasource", "description": "Custom datasource.", "allowed_as_source": true, "allowed_as_target": true, "properties": { "row_limit_support": "none", "password": "{password}", "jdbc_driver": { "jdbc_driver": null }, "jdbc_url": { "jdbc_url": null }, "username": "TM_CC_USER_1" }, "property_definitions": [ { "name": "string", "type": "boolean", "label": "string", "description": "string", "placeholder": "string", "required": true, "masked": true, "multiline": true, "hidden": true, "default_value": "string", "values": [ { "value": "string", "label": "string", "supported_environments": [ "private" ], "supported_products": [ "catalog", "studio" ] } ], "group": "string" } ], "status": "active", "origin_country": "us", "owner_id": "1000331001", "rov": { "mode": 0, "member_roles": { "1000331001": { "user_iam_id": "1000331001", "roles": [ "OWNER" ] } } } }
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-]{3,36}$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]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}$Deprecated. Use of this query parameter exhibits poor performance characteristics. Use the more efficient "bookmark" query parameter instead. The offset to use to define the starting index of projects to return in the query results. Used for pagination in conjunction with the "limit" query parameter.
Possible values: value ≥ 0
Default:
0
curl -X 'GET' '{api_domain}/v2/projects?bss_account_id={bss_account_id}&include=fields&limit=10' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
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}$A list of projects returned in the query results.
Status Code
OK
Unauthorized
Forbidden
Too Many Requests
{ "total_results": 10, "bookmark": "{bookmark}", "resources": [ { "metadata": { "guid": "{project_id}", "url": "/v2/projects/{project_id}", "created_at": "2024-11-01T13:21:07.773Z", "updated_at": "2024-11-01T13:21:11.520Z" }, "entity": { "name": "Project Name", "description": "A project description.", "type": "cpd", "generator": "cpdaas-portal-projects", "public": false, "creator": "zapp.brannigan@ibm.com", "storage": { "type": "bmcos_object_storage", "properties": { "bucket_name": "{bucket_name}", "bucket_region": "us-south", "endpoint_url": "https://s3.us-west.cloud-object-storage.test.appdomain.cloud" }, "guid": "{storage_id}" }, "scope": { "bss_account_id": "{bss_account_id}", "saml_instance_name": "IBM w3id", "enforce_members": true } } } ] }{ "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 10,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-]{3,36}$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
curl -X 'GET' '{api_domain}/v2/projects/total?bss_account_id={bss_account_id}' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
Response
The project total.
The project total.
Possible values: value ≥ 0
Example:
10
Status Code
OK
Bad Request
Unauthorized
Forbidden
Too Many Requests
{ "total": 10 }{ "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"]
curl -X 'GET' '{api_domain}/v2/projects/{project_id}?include=fields' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
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,streams_designer,spss_modeler,experiments,data_refinery]
Status Code
OK
No Content
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "metadata": { "guid": "{project_id}", "url": "/v2/projects/{project_id}", "created_at": "2024-11-01T13:21:07.773Z", "updated_at": "2024-11-01T13:21:11.520Z" }, "entity": { "name": "Project Name", "generator": "cpdaas-portal-projects", "description": "A project description.", "public": false, "storage": { "type": "bmcos_object_storage", "properties": { "bucket_name": "{bucket_name}", "bucket_region": "us-south", "credentials": { "admin": { "api_key": "{api_key}", "service_id": "{service_id}", "access_key_id": "{access_key_id}", "secret_access_key": "{secret_access_key}" }, "editor": { "api_key": "{api_key}", "service_id": "{service_id}", "access_key_id": "{access_key_id}", "secret_access_key": "{secret_access_key}", "resource_key_crn": "{resource_key_crn}" }, "viewer": { "api_key": "{api_key}", "service_id": "{service_id}", "access_key_id": "{access_key_id}", "secret_access_key": "{secret_access_key}", "resource_key_crn": "{resource_key_crn}" } }, "endpoint_url": "https://s3.us-west.cloud-object-storage.test.appdomain.cloud" }, "guid": "{storage_id}" }, "scope": { "bss_account_id": "{bss_account_id}", "saml_instance_name": "IBM w3id", "enforce_members": true }, "type": "cpd", "creator": "zapp.brannigan@ibm.com", "creator_iam_id": "IBMid-55000353XF", "catalog": { "public": false, "guid": "{catalog_id}" } } }{ "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,streams_designer,spss_modeler,experiments,data_refinery]The GitHub repository associated with the project.
curl -X 'PATCH' '{api_domain}/v2/projects/{project_id}' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '{ "name": "Project Name", "description": "A project description.", "compute": [ { "type": "code-assistant", "guid": "{code_assistant_instance_id}", "crn": "{code_assistant_instance_crn}", "name": "IBM watsonx Code Assistant", "label": "code-assistant", "credentials": {} } ] }'
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,streams_designer,spss_modeler,experiments,data_refinery]
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "metadata": { "guid": "{project_id}", "url": "/v2/projects/{project_id}", "created_at": "2024-11-01T13:21:07.773Z", "updated_at": "2024-11-01T13:21:11.520Z" }, "entity": { "name": "Project Name", "generator": "cpdaas-portal-projects", "description": "A project description.", "public": false, "storage": { "type": "bmcos_object_storage", "properties": { "bucket_name": "{bucket_name}", "bucket_region": "us-south", "credentials": { "admin": { "api_key": "{api_key}", "service_id": "{service_id}", "access_key_id": "{access_key_id}", "secret_access_key": "{secret_access_key}" }, "editor": { "api_key": "{api_key}", "service_id": "{service_id}", "access_key_id": "{access_key_id}", "secret_access_key": "{secret_access_key}", "resource_key_crn": "{resource_key_crn}" }, "viewer": { "api_key": "{api_key}", "service_id": "{service_id}", "access_key_id": "{access_key_id}", "secret_access_key": "{secret_access_key}", "resource_key_crn": "{resource_key_crn}" } }, "endpoint_url": "https://s3.us-west.cloud-object-storage.test.appdomain.cloud" }, "guid": "{storage_id}" }, "scope": { "bss_account_id": "{bss_account_id}", "saml_instance_name": "IBM w3id", "enforce_members": true }, "type": "cpd", "creator": "zapp.brannigan@ibm.com", "creator_iam_id": "IBMid-55000353XF", "catalog": { "public": false, "guid": "{catalog_id}" } } }{ "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]A list of comma-separated usernames corresponding to project members that are used to filter the query results.
Possible values: 1 ≤ length ≤ 100
curl -X 'GET' '{api_domain}/v2/projects/{project_id}/members' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
Response
A list of project members.
A list of project members.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "members": [ { "user_name": "zapp.brannigan@ibm.com", "role": "admin", "state": "ACTIVE", "type": "user", "id": "IBMid-55000353XF" } ] }{ "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.
curl -X 'POST' '{api_domain}/v2/projects/{project_id}/members' -H 'Accept: application/json' -H 'cpdaas-include-permissions: false' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '{ "members": [ { "user_name": "zapp.brannigan@ibm.com", "id": "IBMid-55000353XF", "role": "admin", "state": "ACTIVE", "type": "user" } ] }'
Response
A list of project members.
A list of project members.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "members": [ { "user_name": "zapp.brannigan@ibm.com", "role": "admin", "state": "ACTIVE", "type": "user", "id": "IBMid-55000353XF" } ] }{ "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
curl -X 'DELETE' '{api_domain}/v2/projects/{project_id}/members?user_names=zapp.brannigan%40ibm.com' -H 'Accept: */*' -H 'Authorization: Bearer {bearer_auth_token}'
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.
curl -X 'PATCH' '{api_domain}/v2/projects/{project_id}/members' -H 'Accept: application/json' -H 'cpdaas-include-permissions: false' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '{ "members": [ { "user_name": "zapp.brannigan@ibm.com", "id": "IBMid-55000353XF", "role": "editor" } ] }'
Response
A list of project members.
A list of project members.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "members": [ { "user_name": "zapp.brannigan@ibm.com", "role": "admin", "state": "ACTIVE", "type": "user", "id": "IBMid-55000353XF" } ] }{ "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
curl -X 'GET' '{api_domain}/v2/projects/{project_id}/members/zapp.brannigan%40ibm.com?resolve_groups=true' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
Response
A project member.
The username of the project member. If the member type is "service", "profile", 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,profile]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
{ "id": "IBMid-55000353XF", "state": "ACTIVE", "type": "user", "user_name": "zapp.brannigan@ibm.com", "role": "admin" }{ "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
curl -X 'DELETE' '{api_domain}/v2/projects/{project_id}/members/zapp.brannigan%40ibm.com' -H 'Accept: */*' -H 'Authorization: Bearer {bearer_auth_token}'
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
curl -X 'GET' '{api_domain}/v2/projects/{project_id}/tags' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
Response
A list of tags associated with the project.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
[ "development", "production", "test" ]{ "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 (&)(&).
curl -X 'POST' '{api_domain}/v2/projects/{project_id}/tags' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '[ "development", "test", "production" ]'
Response
A list of tags associated with the project.
Status Code
Created
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests
[ "development", "production", "test" ]{ "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
curl -X 'DELETE' '{api_domain}/v2/projects/{project_id}/tags?tag_names=development' -H 'Accept: */*' -H 'Authorization: Bearer {bearer_auth_token}'
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
^[^,]+$
curl -X 'PATCH' '{api_domain}/v2/projects/{project_id}/tags' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '[ { "op": "add", "tags": [ "development", "test" ] }, { "op": "remove", "tags": [ "production" ] } ]'
Response
A list of tags associated with the project.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests
[ "development", "test" ]{ "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
curl -X 'POST' '{api_domain}/v2/projects/{project_id}/tags/development' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '{}'
Response
A list of tags associated with the project.
Status Code
Created
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests
[ "development" ]{ "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
curl -X 'DELETE' '{api_domain}/v2/projects/{project_id}/tags/development' -H 'Accept: */*' -H 'Authorization: Bearer {bearer_auth_token}'
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." }
Get audit events settings
Get audit events settings.
GET /v2/projects/{project_id}/settings/audit_eventsRequest
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
curl -X 'GET' '{api_domain}/v2/projects/{project_id}/settings/audit_events' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
Response
The audit events settings group.
The enablement flag for the audit events feature.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "enabled": false }{ "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 audit events settings
Update audit events settings.
PUT /v2/projects/{project_id}/settings/audit_eventsRequest
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 audit events settings group.
The enablement flag for the audit events feature.
curl -X 'PUT' '{api_domain}/v2/projects/{project_id}/settings/audit_events' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '{ "enabled": false }'
Response
The audit events settings group.
The enablement flag for the audit events feature.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "enabled": false }{ "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 access restrictions settings
Get access restrictions settings.
GET /v2/projects/{project_id}/settings/access_restrictionsRequest
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
curl -X 'GET' '{api_domain}/v2/projects/{project_id}/settings/access_restrictions' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
Response
The access restrictions settings group.
Restrict access to project data. Setting used to manage the "Mark as sensitive" control state.
Permission modifiers for the project data access restrictions. Setting used to manage the "Mark as sensitive" control state.
Govern reporting tool access to project data. (e.g. "wkc-bi-data-service").
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "data": false, "data_permissions": { "editor": false }, "reporting": { "authorized": false } }{ "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 access restrictions settings
Update access restrictions settings.
PUT /v2/projects/{project_id}/settings/access_restrictionsRequest
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 access restrictions settings group.
Restrict access to project data. Setting used to manage the "Mark as sensitive" control state.
Default:
falsePermission modifiers for the project data access restrictions. Setting used to manage the "Mark as sensitive" control state.
Govern reporting tool access to project data. (e.g. "wkc-bi-data-service").
curl -X 'PUT' '{api_domain}/v2/projects/{project_id}/settings/access_restrictions' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '{ "data": false, "data_permissions": { "editor": false }, "reporting": { "authorized": false } }'
Response
The access restrictions settings group.
Restrict access to project data. Setting used to manage the "Mark as sensitive" control state.
Permission modifiers for the project data access restrictions. Setting used to manage the "Mark as sensitive" control state.
Govern reporting tool access to project data. (e.g. "wkc-bi-data-service").
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "data": false, "data_permissions": { "editor": false }, "reporting": { "authorized": false } }{ "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
curl -X 'GET' '{api_domain}/v2/projects/{project_id}/settings/folders' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
Response
The folders settings group.
The enablement flag for the folders feature.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "enabled": false }{ "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.
curl -X 'PUT' '{api_domain}/v2/projects/{project_id}/settings/folders' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '{ "enabled": false }'
Response
The folders settings group.
The enablement flag for the folders feature.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "enabled": false }{ "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 JupyterLab integration
Get JupyterLab integration.
GET /v2/projects/{project_id}/integrations/jupyterlabRequest
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
curl -X 'GET' '{api_domain}/v2/projects/{project_id}/integrations/jupyterlab' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
Response
The JupyterLab feature integration.
The project integration 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:
f6167e97-09cf-48f0-bebf-a6da964de9ad
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "guid": "{integration_id}" }{ "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 JupyterLab integration
Update JupyterLab integration.
PUT /v2/projects/{project_id}/integrations/jupyterlabRequest
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 JupyterLab feature integration.
The project integration 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:
f6167e97-09cf-48f0-bebf-a6da964de9ad
curl -X 'PUT' '{api_domain}/v2/projects/{project_id}/integrations/jupyterlab' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '{ "guid": "{integration_id}" }'
Response
The JupyterLab feature integration.
The project integration 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:
f6167e97-09cf-48f0-bebf-a6da964de9ad
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "guid": "{integration_id}" }{ "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 JupyterLab integration
Delete JupyterLab integration.
DELETE /v2/projects/{project_id}/integrations/jupyterlabRequest
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
curl -X 'DELETE' '{api_domain}/v2/projects/{project_id}/integrations/jupyterlab' -H 'Accept: */*' -H 'Authorization: Bearer {bearer_auth_token}'
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." }
List tokens
List tenant access tokens issued (created) for the project (tenant).
GET /v2/projects/{project_id}/tokensRequest
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
curl -X 'GET' '{api_domain}/v2/projects/{project_id}/tokens' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
Response
A list of project tenant access tokens.
A list of project tenant access tokens.
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "tokens": [ { "guid": "{token_id}", "name": "Tenant Access Token Name", "scopes": [ { "audience": "project", "guid": "{project_id}", "role": "viewer" } ], "creator": { "username": "zapp.brannigan@ibm.com", "id": "IBMid-55000353XF" }, "created_at": "2024-11-05T18:31:07.091Z", "last_used_at": "2024-11-05T18:31:07.091Z", "schema_version": "2.0.0", "token": "{tenant_access_token}" } ] }{ "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 token
Issues (creates) a new tenant access token for the project (tenant).
POST /v2/projects/{project_id}/tokensRequest
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 creating a new project tenant access token.
The name of the tenant access token.
Example:
Tenant Access Token NameA list of project tenant access token scopes.
curl -X 'POST' '{api_domain}/v2/projects/{project_id}/tokens' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '{ "name": "Tenant Access Token Name", "scopes": [ { "audience": "project", "guid": "{project_id}", "role": "viewer" } ] }'
Response
A project tenant access token.
The name of the tenant access token.
Example:
Tenant Access Token NameThe tenant access token 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:
7ce920a2-9086-4d78-9166-10ee6fdda581A list of project tenant access token scopes.
The field storing token creator attributes.
The date and time the tenant access token was created in UTC (ISO 8601).
Example:
2019-03-05T23:15:36.175ZThe schema version of the tenant token metadata / document model.
Possible values: Value must match regular expression
^[0-9]+\.[0-9]+\.[0-9]+$Example:
2.0.0The tenant access token.
Example:
p-2+g5ASLXe4czs2Ibly+2CwSA==;zsqNGTYUy86zW4mTerJKGg==:enx9a0RFh6FuQ6iBIexQohTI6drj23yp3uHH7Xz2jxoq4lSkU2USgUrwt6t5wVPf7jrjWn4joMZyK9GSazjwjcEaTIi6HqFPRg==The date and time the tenant access token was last used in UTC (ISO 8601).
Example:
2019-10-02T19:26:49.684Z
Status Code
Created
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "guid": "{token_id}", "name": "Tenant Access Token Name", "scopes": [ { "audience": "project", "guid": "{project_id}", "role": "viewer" } ], "creator": { "username": "zapp.brannigan@ibm.com", "id": "IBMid-55000353XF" }, "created_at": "2025-07-16T12:54:12.121Z", "last_used_at": "2025-07-16T12:54:12.121Z", "schema_version": "2.0.0", "token": "{tenant_access_token}" }{ "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." }
Revoke all tokens
Revokes (deletes) all tenant access tokens previously issued (created) for the project (tenant).
DELETE /v2/projects/{project_id}/tokensRequest
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
curl -X 'DELETE' '{api_domain}/v2/projects/{project_id}/tokens' -H 'Accept: */*' -H 'Authorization: Bearer {bearer_auth_token}'
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." }
Get token
Returns the metadata for a tenant access token specified by ID.
GET /v2/projects/{project_id}/tokens/{token_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-b131f12bc773The token ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
7ce920a2-9086-4d78-9166-10ee6fdda581
curl -X 'GET' '{api_domain}/v2/projects/{project_id}/tokens/{token_id}' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
Response
A project tenant access token.
The name of the tenant access token.
Example:
Tenant Access Token NameThe tenant access token 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:
7ce920a2-9086-4d78-9166-10ee6fdda581A list of project tenant access token scopes.
The field storing token creator attributes.
The date and time the tenant access token was created in UTC (ISO 8601).
Example:
2019-03-05T23:15:36.175ZThe schema version of the tenant token metadata / document model.
Possible values: Value must match regular expression
^[0-9]+\.[0-9]+\.[0-9]+$Example:
2.0.0The tenant access token.
Example:
p-2+g5ASLXe4czs2Ibly+2CwSA==;zsqNGTYUy86zW4mTerJKGg==:enx9a0RFh6FuQ6iBIexQohTI6drj23yp3uHH7Xz2jxoq4lSkU2USgUrwt6t5wVPf7jrjWn4joMZyK9GSazjwjcEaTIi6HqFPRg==The date and time the tenant access token was last used in UTC (ISO 8601).
Example:
2019-10-02T19:26:49.684Z
Status Code
OK
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests
{ "guid": "{token_id}", "name": "Tenant Access Token Name", "scopes": [ { "audience": "project", "guid": "{project_id}", "role": "viewer" } ], "creator": { "username": "zapp.brannigan@ibm.com", "id": "IBMid-55000353XF" }, "created_at": "2025-07-16T12:54:12.121Z", "last_used_at": "2025-07-16T12:54:12.121Z", "schema_version": "2.0.0", "token": "{tenant_access_token}" }{ "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." }
Revoke token
Revokes (deletes) a single tenant access token previously issued (created) for the project (tenant).
DELETE /v2/projects/{project_id}/tokens/{token_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-b131f12bc773The token ID.
Possible values: Value must match regular expression
^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$Example:
7ce920a2-9086-4d78-9166-10ee6fdda581
curl -X 'DELETE' '{api_domain}/v2/projects/{project_id}/tokens/{token_id}' -H 'Accept: */*' -H 'Authorization: Bearer {bearer_auth_token}'
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." }
Introspect token
Validates a tenant access token specified via the Authorization HTTP header.
GET /v2/projects/tokens/introspect
Request
No Request Parameters
curl -X 'GET' '{api_domain}/v2/projects/{project_id}/tokens/introspect' -H 'Accept: application/json' -H 'Authorization: Bearer {tenant_access_token}'
Response
A project tenant access token.
The name of the tenant access token.
Example:
Tenant Access Token NameThe tenant access token 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:
7ce920a2-9086-4d78-9166-10ee6fdda581A list of project tenant access token scopes.
The field storing token creator attributes.
The date and time the tenant access token was created in UTC (ISO 8601).
Example:
2019-03-05T23:15:36.175ZThe schema version of the tenant token metadata / document model.
Possible values: Value must match regular expression
^[0-9]+\.[0-9]+\.[0-9]+$Example:
2.0.0The tenant access token.
Example:
p-2+g5ASLXe4czs2Ibly+2CwSA==;zsqNGTYUy86zW4mTerJKGg==:enx9a0RFh6FuQ6iBIexQohTI6drj23yp3uHH7Xz2jxoq4lSkU2USgUrwt6t5wVPf7jrjWn4joMZyK9GSazjwjcEaTIi6HqFPRg==The date and time the tenant access token was last used in UTC (ISO 8601).
Example:
2019-10-02T19:26:49.684Z
Status Code
OK
Bad Request
Unauthorized
Too Many Requests
{ "guid": "{token_id}", "name": "Tenant Access Token Name", "scopes": [ { "audience": "project", "guid": "{project_id}", "role": "viewer" } ], "creator": { "username": "zapp.brannigan@ibm.com", "id": "IBMid-55000353XF" }, "created_at": "2025-07-16T12:54:12.121Z", "last_used_at": "2025-07-16T12:54:12.121Z", "schema_version": "2.0.0", "token": "{tenant_access_token}" }{ "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": "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 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 watsonx.ai 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-ProjectsBMCOS properties to be associated with the project.
- storage
The type of the associated project storage.
Example:
bmcos_object_storageUnique guid of the associated project storage object.
Example:
d0e410a0-b358-42fc-b402-dba83316413aThe unique ID of the plan associated with the COS instance. The value is 1e4e33e4-cfa6-4f12-9016-be594a6d5f87 for the One Rate plan.
Example:
1e4e33e4-cfa6-4f12-9016-be594a6d5f87A cloud resource name of the Cloud Object Storage instance in WSC (not required in CP4D or in AWS).
Example:
crn:v1:staging:public:cloud-object-storage:global:a/a7026b374f39f570d20984c1ac6ecf63:5778e94f-c8c7-46a8-9878-d5eeadb51161::Set to true of the COS instance is delegated by the account admin
Default:
false
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]
curl -X 'POST' '{api_domain}/v2/projects' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}' -H 'Content-Type: application/json' -d '{ "name": "Project Name", "description": "A project description.", "type": "cpd", "generator": "Transactional-API_Swagger_Docs", "storage": { "type": "assetfiles" }, "catalog": { "public": false }, "enforce_members": true, "settings": { "access_restrictions": { "data": false, "reporting": { "authorized": false } }, "audit_events": { "enabled": false } } }'
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
curl -X 'DELETE' '{api_domain}/transactional/v2/projects/{project_id}' -H 'Accept: */*' -H 'Authorization: Bearer {bearer_auth_token}'
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
curl -X 'GET' '{api_domain}/transactional/v2/projects/{project_id}/transactions/{transaction_id}' -H 'Accept: application/json' -H 'Authorization: Bearer {bearer_auth_token}'
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:
cpdSpace settings.
curl '{cluster_host}/v2/spaces' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{ "name": "space-name", "description": "space description", "tags": ["tag1", "tag2"], "generator": "Spaces-API_Swagger-Docs", "stage": { "production": false, "name": "QA" }, "type": "cpd", "settings": { "folders": { "enabled": true }, "access_restrictions": { "reporting": { "authorized": true } } } }'
Response
Common metadata for a resource.
Status Code
Accepted
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
{ "entity": { "compute": [ { "crn": "crn:v1:cpd:private:pm-20:private:a/cpduser:99999999-9999-9999-9999-999999999999::", "guid": "99999999-9999-9999-9999-999999999999", "name": "Watson Machine Learning", "type": "machine_learning" } ], "members": [ { "id": "1000331001", "role": "admin", "state": "active", "type": "user" } ], "name": "test", "scope": { "bss_account_id": "cpdaccount" }, "settings": { "folders": { "enabled": false } }, "stage": { "production": false }, "status": { "state": "preparing" }, "type": "cpd" }, "metadata": { "created_at": "2025-05-28T12:18:06.179Z", "creator_id": "1000331001", "id": "2531bf6d-d63c-4e33-a141-5142d52d9d50", "url": "/v2/spaces/2531bf6d-d63c-4e33-a141-5142d52d9d50" } }
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
curl '{cluster_host}/v2/spaces?name=space_name&total_count=true&limit=10&include=members' --header 'Authorization: Bearer {token}'
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
{ "first": { "href": "https://host/v2/spaces" }, "limit": 100, "resources": [ { "entity": { "compute": [ { "crn": "crn:v1:cpd:private:pm-20:private:a/cpduser:99999999-9999-9999-9999-999999999999::", "guid": "99999999-9999-9999-9999-999999999999", "name": "Watson Machine Learning", "type": "machine_learning" } ], "name": "test", "scope": { "bss_account_id": "cpdaccount" }, "settings": { "folders": { "enabled": false } }, "stage": { "production": false }, "status": { "state": "active" }, "type": "cpd" }, "metadata": { "created_at": "2025-05-28T12:18:06.179Z", "creator_id": "1000331001", "id": "2531bf6d-d63c-4e33-a141-5142d52d9d50", "updated_at": "2025-05-28T12:18:06.925Z", "url": "/v2/spaces/2531bf6d-d63c-4e33-a141-5142d52d9d50" } } ] }
Request
Path Parameters
The space identification.
Query Parameters
A list of comma-separated space sections to include in the query results. Example: '?include=members'.
Available fields:
- members (returns up to 100 members)
- credentials (returns S3 bucket temporary credentials)
- nothing (does not return space entity and metadata)
curl '{host}/v2/spaces/{space_id}' --header 'Authorization: Bearer {token}'
Response
Common metadata for a resource.
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
{ "entity": { "compute": [ { "crn": "crn:v1:cpd:private:pm-20:private:a/cpduser:99999999-9999-9999-9999-999999999999::", "guid": "99999999-9999-9999-9999-999999999999", "name": "Watson Machine Learning", "type": "machine_learning" } ], "name": "test", "scope": { "bss_account_id": "cpdaccount" }, "settings": { "folders": { "enabled": false } }, "stage": { "production": false }, "status": { "state": "active" }, "type": "cpd" }, "metadata": { "created_at": "2025-05-28T12:18:06.179Z", "creator_id": "1000331001", "id": "2531bf6d-d63c-4e33-a141-5142d52d9d50", "updated_at": "2025-05-28T12:18:06.925Z", "url": "/v2/spaces/2531bf6d-d63c-4e33-a141-5142d52d9d50" } }
Update the space
Partially update this space. Allowed paths are:
- /name
- /description
- /compute
- /stage/name
- /type
- /settings/folders/enabled
- /settings/access_restrictions/reporting/authorized
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.
curl --request PATCH '{cluster_host}/v2/spaces/c20d7836-a994-4fb3-a202-f5babda146bf' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '[ { "op": "add", "path": "/description", "value": "space-description" }, { "op": "replace", "path": "/name", "value": "space-name-updated" }, { "op": "replace", "path": "/name", "value": "space-name-updated" }, { "op": "add", "path": "/stage/name", "value": "stage-name" }, { "op": "replace", "path": "/type", "value": "cpd" }, { "op": "add", "path": "/settings/access_restrictions/reporting/authorized", "value": true } ]'
Response
Common metadata for a resource.
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
{ "entity": { "compute": [ { "crn": "crn:v1:cpd:private:pm-20:private:a/cpduser:99999999-9999-9999-9999-999999999999::", "guid": "99999999-9999-9999-9999-999999999999", "name": "Watson Machine Learning", "type": "machine_learning" } ], "description": "space description", "members": [ { "id": "1000331001", "role": "admin", "state": "active", "type": "user" } ], "name": "test", "scope": { "bss_account_id": "cpdaccount" }, "settings": { "folders": { "enabled": false } }, "stage": { "production": false }, "status": { "state": "active" }, "type": "cpd" }, "metadata": { "created_at": "2025-05-28T12:18:06.179Z", "creator_id": "1000331001", "id": "2531bf6d-d63c-4e33-a141-5142d52d9d50", "updated_at": "2025-05-28T14:37:31.479Z", "url": "/v2/spaces/2531bf6d-d63c-4e33-a141-5142d52d9d50" } }
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'.
curl '{cluster_host}/v2/spaces{space_id}?include=members' --header 'Authorization: Bearer {token}'
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
{ "first": { "href": "https://host/v2/spaces/2531bf6d-d63c-4e33-a141-5142d52d9d50/members" }, "limit": 100, "resources": [ { "id": "1000331001", "role": "admin", "state": "active", "type": "user" } ] }
Request
Path Parameters
The space identification.
Member information.
curl '{host}/v2/spaces/{space_id}/members' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{ "members": [ { "id": "1000331001", "role": "admin", "type": "user" } ] }'
Response
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
{ "resources": [ { "id": "iam-ServiceId-a1e4dc16-768f-4033-8553-942012f28db7", "role": "viewer", "state": "active", "type": "service" } ] }
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}Request
Path Parameters
The space identification.
The member identification.
curl '{host}/v2/spaces/{space_id}/members/{member_id}' --header 'Authorization: Bearer {token}'
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,profile]
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
{ "id": "1000331001", "role": "admin", "state": "active", "type": "user" }
Remove the space member
Removes the specified member from the space.
DELETE /v2/spaces/{space_id}/members/{member_id}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.
curl --request PATCH '{host}/v2/spaces/{space_id}/members/{member_id}' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '[{ "op": "add", "path": "/role", "value": "admin" }]'
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,profile]
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
{ "id": "ServiceId-a1e4dc16-768f-4033-8553-942012f28db7", "role": "admin", "state": "active", "type": "service" }
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.
curl '{cluster_host}/v2/asset_exports?space_id={space_id}&limit=1&start={start_page_token}' --header 'Authorization: Bearer {token}'
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
{ "first": { "href": "https://host/v2/asset_exports?project_id=7e9066c4-bbae-4565-a968-05e2ab43253a" }, "limit": 100, "resources": [ { "entity": { "assets": { "all_assets": true }, "format": "json", "skip_notification": true, "status": { "state": "completed" } }, "metadata": { "created_at": "2025-05-28T15:31:34.821Z", "creator_id": "1000331001", "id": "cd34356f-3df6-4e50-90cc-1b921997eb5a", "name": "export123", "project_id": "7e9066c4-bbae-4565-a968-05e2ab43253a", "updated_at": "2025-05-28T15:31:40.409Z", "url": "/v2/asset_exports/cd34356f-3df6-4e50-90cc-1b921997eb5a" } } ] }
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
curl '{cluster_host}/v2/asset_exports?space_id={space_id}' --header 'Authorization: Bearer {token}' --header 'Content-Type: application/json' --data '{ "name": "export-name", "description": "export-description", "encryption_key": "encryption_key", "format": "json", "assets": { "all_assets": false, "asset_ids": ["{asset-id1}", "{asset-id2}"] } }'
Response
Common metadata for a import/export.
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
{ "entity": { "assets": { "all_assets": true }, "format": "json", "skip_notification": true, "status": { "state": "pending" } }, "metadata": { "created_at": "2025-05-28T15:31:34.821Z", "creator_id": "1000331001", "id": "cd34356f-3df6-4e50-90cc-1b921997eb5a", "name": "export123", "project_id": "7e9066c4-bbae-4565-a968-05e2ab43253a", "url": "/v2/asset_exports/cd34356f-3df6-4e50-90cc-1b921997eb5a" } }
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
curl --request DELETE '{host}/v2/asset_exports/{export_id}?project_id={project_id}&hard_delete=true' --header 'Authorization: Bearer {token}'
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
curl '{host}/v2/asset_exports/{export_id}?project_id={project_id}' --header 'Authorization: Bearer {token}'
Response
Common metadata for a import/export.
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
{ "entity": { "assets": { "all_assets": true }, "format": "json", "skip_notification": true, "status": { "state": "completed" } }, "metadata": { "created_at": "2025-05-28T15:31:34.821Z", "creator_id": "1000331001", "id": "cd34356f-3df6-4e50-90cc-1b921997eb5a", "name": "export123", "project_id": "7e9066c4-bbae-4565-a968-05e2ab43253a", "updated_at": "2025-05-28T15:31:40.409Z", "url": "/v2/asset_exports/cd34356f-3df6-4e50-90cc-1b921997eb5a" } }
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
curl '{host}/v2/asset_exports/{export_id}/content?project_id={project_id}' --header 'Authorization: Bearer {token}'
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.
curl '{cluster_host}/v2/asset_imports?space_id={space_id}&limit=1&start={start_page_token}' --header 'Authorization: Bearer {token}'
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
{ "first": { "href": "https://host/v2/asset_imports?hard_delete=true&project_id=7e9066c4-bbae-4565-a968-05e2ab43253a" }, "limit": 100, "resources": [ { "entity": { "format": "json", "skip_notification": true, "status": { "state": "completed" } }, "metadata": { "created_at": "2025-05-28T15:37:27.594Z", "creator_id": "1000331001", "id": "b6aa0f5f-e498-4e12-bc29-687ed5d0863a", "project_id": "7e9066c4-bbae-4565-a968-05e2ab43253a", "updated_at": "2025-05-28T15:37:35.034Z", "url": "/v2/asset_imports/b6aa0f5f-e498-4e12-bc29-687ed5d0863a" } } ] }
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
curl '{cluster_host}/v2/asset_imports?space_id={space_id}' --header 'Authorization: Bearer {token}' --form 'file=@"/path/to/zip/file.zip"' --form 'encryption_key="encryption_key"' --form 'format="json"'
Response
Common metadata for a import/export.
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
{ "entity": { "format": "json", "skip_notification": true, "status": { "state": "pending" } }, "metadata": { "created_at": "2025-05-28T15:37:27.594Z", "creator_id": "1000331001", "id": "b6aa0f5f-e498-4e12-bc29-687ed5d0863a", "project_id": "7e9066c4-bbae-4565-a968-05e2ab43253a", "url": "/v2/asset_imports/b6aa0f5f-e498-4e12-bc29-687ed5d0863a" } }
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
curl --request DELETE '{host}/v2/asset_imports/{import_id}?hard_delete=true&project_id={project_id}' --header 'Authorization: Bearer {token}'
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
curl '{host}/v2/asset_imports/{import_id}?project_id={project_id}' --header 'Authorization: Bearer {token}'
Response
Common metadata for a import/export.
Status Code
OK.
Bad request
Unauthorized
Forbidden, an authentication error including trying to access a forbidden space.
Resource not found
Internal Server Error
{ "entity": { "format": "json", "skip_notification": true, "status": { "state": "completed" } }, "metadata": { "created_at": "2025-05-28T15:37:27.594Z", "creator_id": "1000331001", "id": "b6aa0f5f-e498-4e12-bc29-687ed5d0863a", "project_id": "7e9066c4-bbae-4565-a968-05e2ab43253a", "updated_at": "2025-05-28T15:37:35.034Z", "url": "/v2/asset_imports/b6aa0f5f-e498-4e12-bc29-687ed5d0863a" } }
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.
curl -X "GET" \ "$API_DOMAIN/v2/jobs?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json"
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.
Example of a list of jobs under a specific project.
{ "total_rows": 2, "results": [ { "metadata": { "name": "Example Job - Configured", "description": "This is an example job with some configurations.", "asset_id": "d4cf2284-b64d-43d2-accb-aeb40e6f3fe8", "owner_id": "1000000000", "version": 0 }, "entity": { "job": { "asset_ref_type": "data_flow", "configuration": { "env_id": "shaper_rruntime", "env_type": "shaper_rruntime", "env_variables": [] }, "schedule": "0 4 1 * *", "schedule_info": { "startOn": 1747281600000, "endOn": 1747454400000, "repeat": true }, "last_run_initiator": "deprecated field", "last_run_time": "deprecated field", "last_run_status": "deprecated field", "last_run_status_timestamp": 0, "future_scheduled_runs": [], "enable_notifications": true, "notification_types": { "success": true, "warning": false, "failure": true }, "retention_policy": { "amount": 200 }, "project_name": "Example Project", "asset_ref": "1bf61353-659f-447d-895b-d8816dc6e9b5", "schedule_id": "ae77bbc9-9816-4c1f-bd87-a6c3c8549b6e", "schedule_creator_id": "1000000000" } } }, { "metadata": { "name": "Example Job", "description": "This is an example job.", "asset_id": "26b72316-f946-45e8-89cd-806786541caa", "owner_id": "1000000000", "version": 0 }, "entity": { "job": { "asset_ref_type": "data_flow", "configuration": { "env_id": "shaper_rruntime", "env_type": "shaper_rruntime", "env_variables": [] }, "last_run_initiator": "deprecated field", "last_run_time": "deprecated field", "last_run_status": "deprecated field", "last_run_status_timestamp": 0, "future_scheduled_runs": [], "enable_notifications": true, "project_name": "Example Project", "asset_ref": "1bf61353-659f-447d-895b-d8816dc6e9b5", "schedule_id": "", "schedule_creator_id": "" } } } ] }
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, only for DataStage, Orchestration Flow, Machine Learning Stream, and Synthetic data flow jobs.
Array of parameter sets, only for DataStage, Orchestration Flow, Machine Learning Stream, and Synthetic data flow jobs.
curl -X "POST" \ "$API_DOMAIN/v2/jobs?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d \ '{ "job": { "name": "Example Job", "description": "Example Description", "asset_ref": "0e4321fe-164f-4aee-1234-f916da97e816", "configuration": { "env_id": "example_runtime" }, "retention_policy": { "days": 2 }, "notification_types": { "success": false, "warning": false, "failure": true }, "schedule_info": { "startOn": 1234596800000, "endOn": 1234994000000, "repeat": true }, "schedule": "20 * * * 0,3", "job_parameters": [ { "name": "job_param_1", "value": "The value could be of any type" } ], "parameter_sets": [ { "name": "paramset_1", "value_set": "red", "ref": "31abfd90-5497-4605-8ac1-d85896fe6c6f", "values": [ { "name": "job_param_2", "value": "The value could be of any type" } ] } ] } }'
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.
Example of a created job in the specific project.
{ "metadata": { "project_id": "1fc3fd0b-119c-4b86-1234-5c397f7c2c90", "sandbox_id": "1fc3fd0b-119c-4b86-1234-5c397f7c2c90", "usage": { "last_updated_at": "2025-05-09T20:28:43Z", "last_updater_id": "1000000000", "last_update_time": 1746822523733, "last_accessed_at": "2025-05-09T20:28:43Z", "last_access_time": 1746822523733, "last_accessor_id": "1000000000", "access_count": 0 }, "rov": { "mode": 0, "collaborator_ids": {}, "member_roles": { "1000000000": { "user_iam_id": "1000000000", "roles": [ "OWNER" ] } } }, "is_linked_with_sub_container": false, "name": "Example Job", "description": "This is an example job.", "asset_type": "job", "origin_country": "us", "rating": 0, "total_ratings": 0, "catalog_id": "0bdc1617-956e-4413-a393-ada9febae1a4", "created": 1746822523733, "created_at": "2025-05-09T20:28:43Z", "owner_id": "1000000000", "size": 0, "version": 2, "asset_state": "available", "asset_attributes": [ "job" ], "asset_id": "26b72316-f946-45e8-89cd-806123441caa", "asset_category": "USER", "creator_id": "1000000000" }, "entity": { "job": { "asset_ref_type": "data_flow", "configuration": { "env_id": "shaper_rruntime", "env_type": "shaper_rruntime", "env_variables": [] }, "schedule": "20 * * * 0,6", "schedule_info": { "startOn": 1154693760000, "endOn": 1155142040001, "repeat": true }, "last_run_initiator": "deprecated field", "last_run_time": "deprecated field", "last_run_status": "deprecated field", "last_run_status_timestamp": 0, "future_scheduled_runs": [ "2025-05-09T00:20:00.000Z", "2025-05-09T01:20:00.000Z", "2025-05-09T02:20:00.000Z" ], "enable_notifications": true, "notification_types": { "success": false, "warning": false, "failure": true }, "retention_policy": { "days": 1 }, "serving_name": "example_job_1", "project_name": "Example Project", "asset_ref": "1bf61353-659f-447d-895b-d8816dc6e993", "schedule_id": "", "schedule_creator_id": "" } }, "href": "/v2/assets/26b72316-f946-45e8-89cd-806123441caa?project_id=1fc3fd0b-119c-4b86-1234-5c397f7c2c90", "asset_id": "26b72316-f946-45e8-89cd-806123441caa" }
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.
curl -X "GET" \ "$API_DOMAIN/v2/jobs/$JOB_ID?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json"
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.
Example of getting a job with specific ID in a specific project.
{ "metadata": { "name": "Example Job - Configured", "description": "This is an example job with some configurations.", "asset_id": "d4cf2284-b64d-43d2-accb-aeb40e6f3fe8", "owner_id": "1000000000", "version": 2 }, "entity": { "job": { "schedule": "20 * * * 0,6", "asset_ref": "0e1234fe-164f-4aee-4321-f916da97e816", "schedule_id": "420a86f7-4fc2-1i1u-a80d-e942ac265f0b", "project_name": "Example Project", "configuration": { "env_id": "shaper_rruntime", "env_type": "shaper_rruntime", "env_variables": [] }, "last_run_time": "deprecated field", "schedule_info": { "endOn": 1234144000000, "repeat": true, "startOn": 1234696760000 }, "asset_ref_type": "data_flow", "last_run_status": "deprecated field", "retention_policy": { "days": 2 }, "last_run_initiator": "deprecated field", "notification_types": { "failure": true, "success": false, "warning": false }, "schedule_creator_id": "1000000000", "enable_notifications": true, "future_scheduled_runs": [], "last_run_status_timestamp": 0 } } }
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.
curl -X "DELETE" \ "$API_DOMAIN/v2/jobs/$JOB_ID?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json"
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)
curl -X "PATCH" \ "$API_DOMAIN/v2/jobs/$JOB_ID?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d \ '[ { "op": "replace", "path": "/metadata/name", "value": "New Job Name" }, { "op": "add", "path": "/metadata/description", "value": "Sample description." } ]'
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.
Example of updating information of a job.
{ "metadata": { "project_id": "1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "sandbox_id": "1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "usage": { "last_updated_at": "2025-05-12T06:15:47Z", "last_updater_id": "1000000000", "last_update_time": 1747030547645, "last_accessed_at": "2025-05-12T06:15:47Z", "last_access_time": 1747030547645, "last_accessor_id": "1000000000", "access_count": 0 }, "rov": { "mode": 0, "collaborator_ids": {}, "member_roles": { "1000000000": { "user_iam_id": "1000000000", "roles": [ "OWNER" ] } } }, "is_linked_with_sub_container": false, "name": "New Job Name", "description": "Sample description.", "asset_type": "job", "origin_country": "us", "rating": 0, "total_ratings": 0, "catalog_id": "0bdc1617-956e-4413-a393-ada9febae1a4", "created": 1746822523733, "created_at": "2025-05-09T20:28:43Z", "owner_id": "1000000000", "size": 0, "version": 2, "asset_state": "available", "asset_attributes": [ "job" ], "asset_id": "26b72316-f946-45e8-89cd-806786541caa", "asset_category": "USER", "creator_id": "1000000000", "is_branched": true }, "entity": { "job": { "schedule": "20 * * * 0,6", "asset_ref": "0e1234fe-164f-4aee-4321-f916da97e816", "schedule_id": "420a86f7-1iui-4b0a-a80d-e942ac265f0b", "project_name": "Example Project", "serving_name": "example_serving_name", "configuration": { "env_id": "shaper_rruntime", "env_type": "shaper_rruntime", "env_variables": [] }, "last_run_time": "deprecated field", "schedule_info": { "endOn": 1234544000000, "repeat": true, "startOn": 1234696760000 }, "asset_ref_type": "data_flow", "last_run_status": "deprecated field", "retention_policy": { "days": 2 }, "last_run_initiator": "deprecated field", "notification_types": { "failure": true, "success": false, "warning": false }, "schedule_creator_id": "1000000000", "enable_notifications": true, "future_scheduled_runs": [], "last_run_status_timestamp": 0 } }, "href": "/v2/assets/26b234sdf6-f946-45e8-89cd-80643256541caa?project_id=1fc3fd0b-119c-4b86-9161-5c397f7c2c98" }
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}Request
Path Parameters
The serving_name value of the job to be used in place of the job ID.
Query Parameters
Set to true for calls in git-based projects.
Default:
false
curl -X "GET" \ "$API_DOMAIN/v2/jobs/serving_name/$SERVING_NAME" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json"
Response
- Examples:
[ "serving_name does not exist in DB" ]
Status Code
Success.
Bad request. See the error message for details.
You are not authorized to access the service. See response for more information.
An error occurred. See response for more information.
Example of getting the availability of a specific serving_name.
{ "results": [ "serving_name does not exist in DB" ] }
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]
curl -X "GET" \ "$API_DOMAIN/v2/jobs/$JOB_ID/runs?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json"
Response
Example:
204Array of all jobs.
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.
Example of getting a list of runs of a specific job in a specific project.
{ "total_rows": 3, "next": null, "results": [ { "href": "/v2/jobs/d4cf2284-b64d-43d2-accb-aeb40e6f3fe8/runs/c1233b1d-479b-4188-9450-46d0d6ba59ed?project_id=1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "entity": { "job_run": { "state": "Running", "job_ref": "d4cf2284-b64d-43d2-accb-aeb40e6f3fe8", "duration": 109, "end_time": "2025-05-10T23:23:41.519Z", "job_name": "Example Job - Configured", "job_type": "data_flow", "asset_ref_id": "1bf61353-659f-447d-895b-d8816dc6e9b5", "project_name": "Example Project", "configuration": { "env_id": "shaper_rruntime", "env_type": "shaper_rruntime", "env_variables": [] }, "asset_ref_name": "customer.csv_flow", "isScheduledRun": false, "job_parameters": [], "parameter_sets": [], "resource_usage": null, "runtime_job_id": "d6ac00a8-f075-440d-9327-f90bebb0432b", "last_state_change_timestamp": "2025-05-10T23:23:41Z" }, "container_name": "", "directory_asset": { "path": "" } }, "asset_id": "c1233b1d-479b-4188-9450-46d0d6ba59ed", "metadata": { "name": "job run", "usage": { "last_updated_at": "2025-05-10T23:23:41Z", "last_update_time": 1234568221519 }, "created": 1747032195369, "asset_id": "c1233b1d-479b-4188-9450-46d0d6ba59ed", "owner_id": "1000000000", "asset_type": "job_run", "created_at": "2025-05-12T06:43:15.369Z", "creator_id": "1000000000", "project_id": "1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "description": "", "asset_category": "USER" }, "attachments": [ { "id": "983aa4b2-1234-45w2-81aa-ffc9c1524fb0", "mime": "application/json", "name": "832a6336-iu88-4df1-43jj-3f8d1ebc309d", "is_remote": false, "asset_type": "job_run", "is_managed": false, "object_key": "job_run/log/832a6336-iu88-4df1-43jj-3f8d1ebc309d", "create_time": 1754868221569, "description": "log for job run 832a6336-iu88-4df1-43jj-3f8d1ebc309d", "is_referenced": true, "is_partitioned": true, "is_object_key_read_only": false, "is_user_provided_path_key": true } ] }, { "href": "/v2/jobs/d4cf2284-b64d-43d2-accb-aeb40e6f3fe8/runs/f7b88151-dce5-4c96-81fd-c10e2f65459e?project_id=1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "entity": { "job_run": { "name": "Example Job Run 2", "state": "Canceled", "job_ref": "d4cf2284-b64d-43d2-accb-aeb40e6f3fe8", "duration": null, "end_time": "2025-05-12T06:41:39.998Z", "job_name": "Example Job - Configured", "job_type": "data_flow", "description": "Example description", "asset_ref_id": "1bf61353-659f-447d-895b-d8816dc6e9b5", "project_name": "Example Project", "configuration": { "env_id": "shaper_rruntime", "env_type": "shaper_rruntime", "env_variables": [] }, "asset_ref_name": "customer.csv_flow", "isScheduledRun": false, "job_parameters": [], "parameter_sets": [], "resource_usage": null, "runtime_job_id": "777b53cd-0f9b-4902-b245-9b3f2aaa6975" }, "container_name": "", "directory_asset": { "path": "" } }, "asset_id": "f7b88151-dce5-4c96-81fd-c10e2f65459e", "metadata": { "name": "Example Job Run 2", "created": 1747032062364, "asset_id": "f7b88151-dce5-4c96-81fd-c10e2f65459e", "owner_id": "1000000000", "asset_type": "job_run", "created_at": "2025-05-12T06:41:02.364Z", "creator_id": "1000000000", "project_id": "1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "description": "Example description", "asset_category": "USER" }, "attachments": [ { "id": "6b5e3e5d-3e82-44f9-ab11-6e1ef058e29a", "mime": "application/json", "name": "f7b88151-dce5-4c96-81fd-c10e2f65459e", "is_remote": false, "asset_type": "job_run", "creator_id": "1000000000", "is_managed": false, "object_key": "job_run/log/f7b88151-dce5-4c96-81fd-c10e2f65459e", "create_time": 1747032100055, "description": "log for job run f7b88151-dce5-4c96-81fd-c10e2f65459e", "is_referenced": true, "is_partitioned": true, "is_object_key_read_only": false, "is_user_provided_path_key": true } ] }, { "href": "/v2/jobs/d4cf2284-b64d-43d2-accb-aeb40e6f3fe8/runs/57ccc54b-dcee-485c-9bcd-17827680597d?project_id=1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "entity": { "job_run": { "name": "Example Job Run", "state": "Completed", "job_ref": "d4cf2284-b64d-43d2-accb-aeb40e6f3fe8", "duration": 54, "end_time": "2025-05-12T06:38:46.505Z", "job_name": "Example Job - Configured", "job_type": "data_flow", "description": "Example description", "asset_ref_id": "1bf61353-659f-447d-895b-d8816dc6e9b5", "project_name": "Example Project", "configuration": { "env_id": "shaper_rruntime", "env_type": "shaper_rruntime", "env_variables": [] }, "asset_ref_name": "customer.csv_flow", "isScheduledRun": false, "job_parameters": [], "parameter_sets": [], "resource_usage": null, "runtime_job_id": "632decfa-d785-42e0-82f0-2d6118f96a46" }, "container_name": "", "directory_asset": { "path": "" } }, "asset_id": "57ccc54b-dcee-485c-9bcd-17827680597d", "metadata": { "name": "Example Job Run", "created": 1747031835676, "asset_id": "57ccc54b-dcee-485c-9bcd-17827680597d", "owner_id": "1000000000", "asset_type": "job_run", "created_at": "2025-05-12T06:37:15.676Z", "creator_id": "1000000000", "project_id": "1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "description": "Example description", "asset_category": "USER" }, "attachments": [ { "id": "815929f1-7691-49c2-9b96-9496e14a7b68", "mime": "application/json", "name": "57ccc54b-dcee-485c-9bcd-17827680597d", "is_remote": false, "asset_type": "job_run", "is_managed": false, "object_key": "job_run/log/57ccc54b-dcee-485c-9bcd-17827680597d", "create_time": 1747031926536, "description": "log for job run 57ccc54b-dcee-485c-9bcd-17827680597d", "is_referenced": true, "is_partitioned": true, "is_object_key_read_only": false, "is_user_provided_path_key": true } ] } ] }
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, only for DataStage, Orchestration Flow, Machine Learning Stream, and Synthetic data flow jobs.
Array of parameter sets, only for DataStage, Orchestration Flow, Machine Learning Stream, and Synthetic data flow jobs.
curl -X "POST" \ "$API_DOMAIN/v2/jobs/$JOB_ID/runs?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d \ '{ "job_run": { "name": "Job Run", "description": "Description", "configuration": { "env_variables": [ "key1=value1", "key2=value2" ] }, "job_parameters": [ { "name": "job_param_", "value": "The value could be of any type" } ], "parameter_sets": [ { "name": "paramset_1", "value_set": "red", "ref": "31abfd90-5497-4605-8ac1-d85896fe6c6f", "values": [ { "name": "job_param_1", "value": "The value could be of any type" } ] } ] } }'
Response
AssetJobRunMetadata Model
Array of attachments.
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.
Example of starting a run for a job
{ "href": "/v2/jobs/d4cf2284-b64d-43d2-accb-aeb40e6f3fe8/runs/57ccc54b-dcee-485c-9bcd-17827680597d?project_id=1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "entity": { "job_run": { "name": "Example Job Run", "state": "Starting", "job_ref": "d4cf2284-b64d-43d2-accb-aeb40e6f3fe8", "duration": null, "end_time": null, "job_name": "Example Job - Configured", "job_type": "data_flow", "description": "Example description", "asset_ref_id": "1bf61353-659f-447d-895b-d8816dc6e9b5", "project_name": "Example Project", "configuration": { "env_id": "shaper_rruntime", "env_type": "shaper_rruntime", "env_variables": [ "key1=value1", "key2=value2" ] }, "asset_ref_name": "customer.csv_flow", "isScheduledRun": false, "job_parameters": [], "parameter_sets": [], "resource_usage": null, "runtime_job_id": "d4cf2284-b64d-43d2-accb-aeb40e6f3fe8" }, "container_name": "", "directory_asset": { "path": "" } }, "asset_id": "57ccc54b-dcee-485c-9bcd-17827680597d", "metadata": { "name": "Example Job Run", "usage": { "last_updated_at": "2025-05-11T19:53:22Z", "last_updater_id": "1000000000", "last_access_time": 1234542002977, "last_accessed_at": "2025-05-11T19:53:22Z", "last_accessor_id": "1000000000", "last_update_time": 1234542002977 }, "created": 1234531835676, "asset_id": "57ccc54b-dcee-485c-9bcd-17827680597d", "owner_id": "1000000000", "asset_type": "job_run", "created_at": "2025-05-12T06:37:15.676Z", "creator_id": "1000000000", "project_id": "1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "description": "Example description", "asset_category": "USER" }, "attachments": [] }
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.
If set to true, metrics of the job run would not be fetched.
curl -X "GET" \ "$API_DOMAIN/v2/jobs/$JOB_ID/runs/$RUN_ID?project_id=$PROJECT_ID&skip_metrics=$SKIP_METRICS" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json"
Response
AssetJobRunMetadata Model
Array of attachments.
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.
Example of getting a specific run of a job
{ "href": "/v2/jobs/d4cf2284-b64d-43d2-accb-aeb40e6f3fe8/runs/f7b88151-dce5-4c96-81fd-c10e2f65459e?project_id=1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "entity": { "job_run": { "name": "Example Job Run", "state": "Completed", "job_ref": "d4cf2284-b64d-43d2-accb-aeb40e6f3fe8", "duration": null, "end_time": "2025-05-12T06:41:39.998Z", "job_name": "Example Job - Configured", "job_type": "data_flow", "description": "Example description", "asset_ref_id": "1bf61353-659f-447d-895b-d8816dc6e9b5", "project_name": "Example Project", "configuration": { "env_id": "shaper_rruntime", "env_type": "shaper_rruntime", "env_variables": [ "key1=value1", "key2=value2" ] }, "asset_ref_name": "customer.csv_flow", "isScheduledRun": false, "job_parameters": [], "parameter_sets": [], "resource_usage": null, "runtime_job_id": "777b53cd-0f9b-4902-b245-9b3f2aaa6975", "last_state_change_timestamp": "2025-05-11T19:56:19Z" }, "container_name": "", "directory_asset": { "path": "" } }, "asset_id": "f7b88151-dce5-4c96-81fd-c10e2f65459e", "metadata": { "name": "Example Job Run", "usage": { "last_updated_at": "2025-05-11T19:56:19Z", "last_update_time": 1234542179025 }, "created": 1234532062364, "asset_id": "f7b88151-dce5-4c96-81fd-c10e2f65459e", "owner_id": "1000000000", "asset_type": "job_run", "created_at": "2025-05-12T06:41:02.364Z", "creator_id": "1000000000", "project_id": "1fc3fd0b-119c-4b86-9161-5c397f7c2c98", "description": "Example description", "asset_category": "USER" }, "attachments": [ { "id": "6b5e3e5d-3e82-44f9-ab11-6e1ef058e29a", "mime": "application/json", "name": "f7b88151-dce5-4c96-81fd-c10e2f65459e", "is_remote": false, "asset_type": "job_run", "is_managed": false, "object_key": "job_run/log/f7b88151-dce5-4c96-81fd-c10e2f65459e", "create_time": 1234532100055, "description": "log for job run f7b88151-dce5-4c96-81fd-c10e2f65459e", "is_referenced": true, "is_partitioned": true, "is_object_key_read_only": false, "is_user_provided_path_key": true } ] }
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.
curl -X DELETE \ "$API_DOMAIN/v2/jobs/$JOB_ID/runs/$RUN_ID?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json"
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.
curl -X "GET" \ "$API_DOMAIN/v2/jobs/$JOB_ID/runs/$RUN_ID/logs?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json"
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.
Example of a runtime log of a specific job run.
{ "results": [ "Setting up certificate.", "Use CPD_JAVA_CACERTS...", "1", "FIPS is turned on. The underlying OS seems to be FIPS enabled and FIPS_MODE is set to true.", "Certificate was added to keystore", "Skipping, no custom WDP certs found.", "Enabling OpenJCEPlusFIPS.FIPS140-3-withIBMKS profile", "Setting 'LC_ALL'.", "2025-08-10 23:20:16.539+0000 INFO: Loading libraries.", "2025-08-10 23:20:16.563+0000 INFO: Running jsonlite v 1.8.5", "2025-08-10 23:20:16.564+0000 INFO: Running dplyr v 1.0.9", "2025-08-10 23:20:16.565+0000 INFO: Running dbplyr v 2.2.1", "Warning: Your system is mis-configured: ‘/var/db/timezone/localtime’ is not a symlink", "2025-08-10 23:20:18.190+0000 INFO: Running Arrow version 14.0.2.1", "2025-08-10 23:20:18.192+0000 INFO: Runtime environment: Spark", "2025-08-10 23:20:18.192+0000 INFO: Initializing parameters for Data Refinery flow.", "2025-08-10 23:20:18.249+0000 INFO: Set additional spark config properties.", "2025-08-10 23:20:38.868+0000 INFO: Connect to spark failed. Retrying...", "2025-08-10 23:21:44.471+0000 INFO: Connected to Spark runtime environment.", "2025-08-10 23:21:44.472+0000 INFO: R version 4.3.3 (2024-02-29)", "2025-08-10 23:21:44.472+0000 INFO: Running Spark version 3.4.4", "2025-08-10 23:21:44.548+0000 INFO: Running Sparklyr version 1.7.6", "2025-08-10 23:21:44.550+0000 INFO: Registering UDFs.", "2025-08-10 23:21:50.645+0000 INFO: Setting httr configs", "2025-08-10 23:21:50.649+0000 INFO: Received source and target information from job run configuration.", "2025-08-10 23:21:50.653+0000 INFO: Completed processing user info from authentication token.", "2025-08-10 23:21:50.853+0000 INFO: Running ShaperFlowPkg version 5.2.3 (IMAGE:5.2.0.427)", "2025-08-10 23:21:50.854+0000 INFO: Running Connector version 12.1.386", "2025-08-10 23:21:50.854+0000 INFO: Number of partitions: 1", "2025-08-10 23:21:51.026+0000 INFO: Reading Data Refinery flow: Example_Job_flow", "2025-08-10 23:21:51.027+0000 INFO: Creating Spark payload: Processing source and target properties, and operations.", "2025-08-10 23:21:52.493+0000 INFO: Completed reading properties for 'source1': Source1.csv", "2025-08-10 23:21:52.493+0000 INFO: Data source type: assetfiles", "2025-08-10 23:21:52.495+0000 INFO: AvailMemBytes: 1288212714 Size: 277474 Push_Filters: FALSE Cache: TRUE", "2025-08-10 23:23:15.870+0000 INFO: Validating operation: 6e5e50c0-2uis-41fe-990d-45e77411d457", "2025-08-10 23:23:29.016+0000 WARNING: Data asset name 'Example Asset' already exists. Data asset will be overwritten.", "2025-08-10 23:23:29.642+0000 INFO: Completed reading properties for 'target1': target1_shaped", "2025-08-10 23:23:29.642+0000 INFO: Data source type: assetfiles", "2025-08-10 23:23:29.643+0000 INFO: Running Spark payload.", "2025-08-10 23:23:39.581+0000 INFO: Time taken to run spark payload: 9 secs", "2025-08-10 23:23:40.702+0000 INFO: Patched size 240135 mime text/csv (discovery: text/plain ) for asset: 8d5c536c-b1ea-2345-934s-c2f3720d7962", "2025-08-10 23:23:40.704+0000 INFO: Applying lineage event: DATASET_MODIFIED_BY_DATAFLOW", "2025-08-10 23:23:40.753+0000 INFO: Total execution time : 1 min 49 secs", "2025-08-10 23:23:40.753+0000 INFO: Updating job run status to 'FINISHED'.", "2025-08-10 23:23:40.753+0000 INFO: 2066 rows read.", "2025-08-10 23:23:40.754+0000 INFO: 219474 bytes read.", "2025-08-10 23:23:40.754+0000 INFO: 2066 rows written.", "2025-08-10 23:23:40.754+0000 INFO: 203828 bytes written.", "" ], "total_count": 49 }
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: {}
curl -X "POST" \ "$API_DOMAIN/v2/jobs/$JOB_ID/runs/$RUN_ID/cancel?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{}'
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: {}
curl -X "POST" \ "$API_DOMAIN/v2/jobs/$JOB_ID/runs/$RUN_ID/pause?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{}'
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: {}
curl -X "POST" \ "$API_DOMAIN/v2/jobs/$JOB_ID/runs/$RUN_ID/resume?project_id=$PROJECT_ID" \ -H "Authorization: Bearer $BEARER_AUTH_TOKEN" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d '{}'
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
curl -X "GET" "${api_domain}/v2/environments?project_id=${project_id}" -H "Accept: application/json" -H "Authorization: Bearer ${bearer_auth_token}"
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" }, "node_selector": [ { "label_name": "custom_lable_name", "label_value": "custom_lable_value" } ], "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": "45f12dfe-aa78-5b8d-9f38-0ee223c47309", "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/45f12dfe-aa78-5b8d-9f38-0ee223c47309" }, "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": "45f12dfe-aa78-5b8d-9f38-0ee223c47309"
},
"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.
curl -X "POST" "${api_domain}/v2/environments?project_id=${project_id}" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer ${bearer_auth_token}" -d '{ "type": "notebook", "name": "my notebook environment", "description": "this is my notebook environment", "display_name": "My Notebook Environment", "hardware_specification": { "guid": "f3ebac7d-0a75-410c-8b48-a931428cc4c5" }, "software_specification": { "guid": "45f12dfe-aa78-5b8d-9f38-0ee223c47309" }, "tools_specification": { "supported_kernels": [ { "name": "python3", "display_name": "Python 3.11", "language": "python", "version": "3.11" } ] } }'
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" }, "node_selector": [ { "label_name": "custom_lable_name", "label_value": "custom_lable_value" } ], "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": "45f12dfe-aa78-5b8d-9f38-0ee223c47309", "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/45f12dfe-aa78-5b8d-9f38-0ee223c47309" }, "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.
curl -X "GET" "${api_domain}/v2/environments/${environment_guid}?project_id=${project_id}" -H "Accept: application/json" -H "Authorization: Bearer ${bearer_auth_token}"
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" }, "node_selector": [ { "label_name": "custom_lable_name", "label_value": "custom_lable_value" } ], "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": "45f12dfe-aa78-5b8d-9f38-0ee223c47309", "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/45f12dfe-aa78-5b8d-9f38-0ee223c47309" }, "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
curl -X "DELETE" "${api_domain}/v2/environments/${environment_guid}?project_id=${project_id}" -H "Authorization: Bearer ${bearer_auth_token}"
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": "45f12dfe-aa78-5b8d-9f38-0ee223c47309"
},
"/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.
curl -X "PATCH" "${api_domain}/v2/environments/${environment_guid}?project_id=${project_id}" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer ${bearer_auth_token}" -d '{ "/metadata/name": "my updated notebook environment", "/metadata/description": "this is my updated notebook environment", "/entity/environment/display_name": "My Updated Notebook 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.
curl -X "GET" "${api_domain}/v2/hardware_specifications" -H "Accept: application/json" -H "Authorization: Bearer ${bearer_auth_token}"
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" }, "node_selector": [ { "label_name": "custom_lable_name", "label_value": "custom_lable_value" } ], "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"
},
"node_selector": [
{
"label_name": "custom_lable_name",
"label_value": "custom_lable_value"
}
],
"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
curl -X "POST" "${api_domain}/v2/hardware_specifications?project_id=${project_id}" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer ${bearer_auth_token}" -d '{ "name": "my hardware specification", "description": "this is my hardware specification", "nodes": { "cpu": { "units": "2", "model": "" }, "mem": { "size": "8Gi" } } }'
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" }, "node_selector": [ { "label_name": "custom_lable_name", "label_value": "custom_lable_value" } ], "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
curl -X "GET" "${api_domain}/v2/hardware_specifications/${hardware_specification_guid}?project_id=$project_id" -H "Accept: application/json" -H "Authorization: Bearer ${bearer_auth_token}"
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" }, "node_selector": [ { "label_name": "custom_lable_name", "label_value": "custom_lable_value" } ], "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
curl -X "DELETE" "${api_domain}/v2/hardware_specifications/${hardware_specification_guid}?project_id=$project_id" -H "Accept: application/json" -H "Authorization: Bearer ${bearer_auth_token}"
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
curl -X "PATCH" "${api_domain}/v2/hardware_specifications/${hardware_specification_guid}?project_id=${project_id}" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer ${bearer_auth_token}" -d '{ "/metadata/name": "my updated hardware specification", "/metadata/description": "this is my updated hardware specification.", "/entity/hardware_specification/nodes/cpu/units": "3" }'
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" }, "node_selector": [ { "label_name": "custom_lable_name", "label_value": "custom_lable_value" } ], "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.
curl -X "GET" "${api_domain}/v2/software_specifications" -H "Accept: application/json" -H "Authorization: Bearer ${bearer_auth_token}"
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": "45f12dfe-aa78-5b8d-9f38-0ee223c47309", "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/45f12dfe-aa78-5b8d-9f38-0ee223c47309" }, "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
curl -X "POST" "${api_domain}/v2/software_specifications?project_id=${project_id}" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer ${bearer_auth_token}" -d '{ "name": "my software specification", "description": "this is my software specification", "base_software_specification": { "guid": "ab9e1b80-f2ce-592c-a7d2-4f2344f77194" } }'
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": "45f12dfe-aa78-5b8d-9f38-0ee223c47309", "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/45f12dfe-aa78-5b8d-9f38-0ee223c47309" }, "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.
curl -X "PATCH" "${api_domain}/v2/software_specifications/${software_specification_guid}?project_id=${project_id}" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer ${bearer_auth_token}" -d '{ "/metadata/name": "my updated software specification", "/metadata/description": "this is my updated software specification.", "/entity/software_specification/display_name": "My Updated 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
curl -X "GET" "${api_domain}/v2/software_specifications/${software_specification_guid}?project_id=$project_id" -H "Accept: application/json" -H "Authorization: Bearer ${bearer_auth_token}"
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": "45f12dfe-aa78-5b8d-9f38-0ee223c47309", "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/45f12dfe-aa78-5b8d-9f38-0ee223c47309" }, "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
curl -X "DELETE" "${api_domain}/v2/software_specifications/${software_specification_guid}?project_id=$project_id" -H "Accept: application/json" -H "Authorization: Bearer ${bearer_auth_token}"
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
curl -X "PUT" "${api_domain}/v2/software_specifications/${software_specification_guid}/package_extensions/${package_extension_guid}?project_id=$project_id" -H "Authorization: Bearer ${bearer_auth_token}"
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
curl -X "DELETE" "${api_domain}/v2/software_specifications/${software_specification_guid}/package_extensions/${package_extension_guid}?project_id=$project_id" -H "Authorization: Bearer ${bearer_auth_token}"
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
curl -X "GET" "${api_domain}/v2/package_extensions?project_id=${project_id}" -H "Accept: application/json" -H "Authorization: Bearer ${bearer_auth_token}"
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
curl -X "POST" "${api_domain}/v2/package_extensions?project_id=${project_id}" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer ${bearer_auth_token}" -d '{ "name": "my package extension", "description": "this is my package extension", "type": "conda_yml", "interpreter": "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
curl -X "GET" "${api_domain}/v2/package_extensions/${package_extension_guid}?project_id=${project_id}" -H "Accept: application/json" -H "Authorization: Bearer ${bearer_auth_token}"
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
curl -X "PATCH" "${api_domain}/v2/package_extensions/${package_extension_guid}?project_id=${project_id}" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer ${bearer_auth_token}" -d '{ "/metadata/name": "my updated package extension", "/metadata/description": "this is my updated package extension" }'
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
curl -X "GET" "${api_domain}/v2/package_extensions/${package_extension_guid}?project_id=${project_id}" -H "Accept: application/json" -H "Authorization: Bearer ${bearer_auth_token}"
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
curl -X "DELETE" "${api_domain}/v2/package_extensions/${package_extension_guid}?project_id=${project_id}" -H "Authorization: Bearer ${bearer_auth_token}"
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,ARCHIVE_FAILED_CONTAINER_REMOVED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED,UNKNOWN]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.
Indicates whether the container was archived into the CAMS internal bucket, as opposed to the containers own bucket.
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,ARCHIVE_FAILED_CONTAINER_REMOVED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED,UNKNOWN]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.
Indicates whether the container was archived into the CAMS internal bucket, as opposed to the containers own bucket.
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_BY_IDENTITY_KEY_OR_RESOURCE_KEY]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_BY_IDENTITY_KEY_OR_RESOURCE_KEY]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_BY_IDENTITY_KEY_OR_RESOURCE_KEY]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,ARCHIVE_FAILED_CONTAINER_REMOVED,ARCHIVED,RESTORE_SCHEDULED,RESTORE_FAILED,UNKNOWN]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.
Indicates whether the container was archived into the CAMS internal bucket, as opposed to the containers own bucket.
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 assetlist metadata and asset metadata of assetlists based on masking conditions, 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:
created_at%3E%3D%222023-08-23T21%3A10%3A40Z%22%26%26limit%3D10%26%26archived%3D%22false%22Start 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.
Possible values: 0 ≤ value ≤ 200
Example:
200The total count on the number of results returned, accounting for filtering but not pagination.
Possible values: 0 ≤ value ≤ 200
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,access_revoked]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,access_revoked]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.
Parameter indicates whether the assetlist is archived or not.
Example:
true
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:
created_at%3E%3D%222023-08-23T21%3A10%3A40Z%22%26%26limit%3D10%26%26archived%3D%22false%22
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,access_revoked]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.
Parameter indicates whether the assetlist is archived or not.
Example:
true
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)
- /properties (Functional users)
- /archived (Functional users and Asset Owner 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,access_revoked]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.
Parameter indicates whether the assetlist is archived or not.
Example:
true
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.
Possible values: 0 ≤ value ≤ 200
Example:
200The total count on the number of results returned, accounting for filtering but not pagination.
Possible values: 0 ≤ value ≤ 200
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
Determines whether instances of this relationship type should be shared across copies of this asset. For example, a primary key constraint that constrains a table.
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
Determines whether instances of this relationship type should be shared across copies of this asset. For example, a primary key constraint that constrains a table.
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
Determines whether instances of this relationship type should be shared across copies of this asset. For example, a primary key constraint that constrains a table.
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
Determines whether instances of this relationship type should be shared across copies of this asset. For example, a primary key constraint that constrains a table.
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)multiplicity(value can be scaled up from ONE to MANY, but it cannot be scaled down from MANY to ONE)
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"
}
]
Update multiplicity in end1:
Allowed value: "MANY"
This field can only be updated from "ONE" to "MANY". Updates from "MANY" to "ONE" are not allowed.
[
{
"op": "replace",
"path": "/end1/multiplicity",
"value": "MANY"
}
]
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"
}
]
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