common_core service has 17 resource kinds, each listed below with its endpoints, fields, and dependencies. Values resolve late, so you reference another resource with ${kind.ref_name}. For defaults, validation rules, and examples, run wxctl explain <kind>.
YAML envelope & reference syntax
YAML envelope & reference syntax
- Envelope: A config is one or more YAML documents separated by
---. Each has top-levelkindandref_name, then the fields below at the top level (not nested underspec). ref_name: Unique handle for this resource within the config. Used to reference it from other resources, then stripped before the API call (not a schema field).- References: Reference another resource by its ref_name:
${<kind>.<ref_name>}resolves to its id,${<kind>.<ref_name>.<field>}to a specific field. Values resolve late, at plan/apply time.
asset_promotion
Promotes a project-side asset, a native model the training job stored under a known name, into a deployment space.
Runs on SaaS + Software · ID field id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v2/assets |
| Read | GET | /v2/assets/{id} |
| Delete | DELETE | /v2/assets/{id} |
| Field | Type | Required | Description |
|---|---|---|---|
asset_name | string | Required | The asset name the training code stored (the name contract). Resolves the project-side source asset and adopts the promoted copy in the target space. |
asset_type | string | Optional | CAMS asset type for the name search + promote (default wml_model). |
project_id | string | Required | Source project id, where the training job stored the asset. Used as the required project_id query on the search + promote calls. The handler owns every request, so the Query location never triggers generic materialization. |
space_id | string | Required | Target deployment space id the asset is promoted into. |
job_run | string | Optional | Ordering-only reference to the job_run that trains + stores the model. The handler never reads or sends it, pre_create/pre_delete always return Handled, so generic materialization never runs for this resource (mirrors project_id/space_id above). location: Query (not LocalOnly) only so references still produces the DAG edge job_run -> asset_promotion; LocalOnly/Computed fields are excluded from graph-edge collection entirely. Whole-field reference (${job_run.x.id}), nested refs make no graph edge. |
id, source_asset_id.
Depends on
project_id→project(optional)space_id→space(optional)job_run→job_run(optional)
model_tracking→.model(optional)wml_deployment→.asset(optional)
business_term
A Business Term is a glossary entry that defines standardized business vocabulary and semantics for data governance in Watsonx Data.
Runs on SaaS + Software · ID field artifact_id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v3/glossary_terms |
| Read | GET | /v3/glossary_terms/{artifact_id} |
| List | GET | /v3/glossary_terms |
| Update | PATCH | /v3/glossary_terms/{artifact_id} |
| Delete | DELETE | /v3/glossary_terms/{artifact_id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Unique name identifier for the business term within the glossary. This name serves as the primary human-readable reference and should clearly represent the business concept being defined. Must be unique within the glossary to prevent ambiguity and ensure clear term identification across the organization. |
short_description | string | Optional | Brief description of the business term shown in summary views, search results, and quick previews. Should provide a concise definition that users can quickly understand without reading the full long_description. Typically 1-2 sentences. |
long_description | string | Optional | Comprehensive definition and explanation of the business term. Should include detailed business context, scope, usage guidelines, and any important clarifications. This is the authoritative definition used for governance, compliance, and data literacy purposes. Supports rich text formatting for detailed documentation. |
abbreviations | array<string> | Optional | List of alternate abbreviations or acronyms commonly used for this term. Helps users find the term when searching by abbreviation and documents variant forms used across different parts of the organization. Examples: [“CX”, “CUST_EXP”] for “Customer Experience”. |
example | string | Optional | Example usage or illustrative context showing how the term is applied in practice. Helps users understand concrete applications of abstract concepts and clarifies the term’s scope through real-world scenarios. Can include sample data values or usage contexts. |
tags | array<string> | Optional | User-defined tags for organizing and discovering terms through faceted search and filtering. Tags can represent data domains, regulatory frameworks, business processes, or any other categorization dimension relevant to the organization. Complements the formal category hierarchy with flexible, multi-dimensional classification. |
steward_ids | array<string> | Optional | List of user identifiers assigned as stewards for this business term. Stewards are responsible for maintaining the term’s definition, reviewing proposed changes, and ensuring the term is correctly applied to data assets. Stewards have governance authority over the term’s lifecycle. |
steward_group_ids | array<string> | Optional | List of group identifiers assigned as steward groups for this term. Allows stewardship responsibility to be assigned to teams or organizational units rather than individual users, distributing governance duties across a group. |
parent_category | object | Optional | Primary category assignment that places this term within the governance taxonomy hierarchy. This establishes the term’s main classification and cannot be changed after creation to maintain taxonomy stability. The parent category determines the term’s primary organizational context and affects how it appears in hierarchical navigation. |
categories | array<object> | Optional | List of secondary category relationships for multi-dimensional classification. Allows the term to be associated with multiple categories beyond the primary parent_category, enabling cross-cutting organizational views and faceted taxonomy navigation. Each entry is a category relationship object with metadata about the association. |
related_terms | array<object> | Optional | List of relationships to other business terms that are conceptually related but not synonyms. Helps users navigate the semantic network of business concepts and discover connected terms. Each relationship can specify the nature of the relationship (e.g., “has_a”, “part_of”). |
synonym_terms | array<object> | Optional | List of business terms that are synonyms or represent the same business concept with different naming. Synonym relationships help unify vocabulary across organizational silos and enable users to find the authoritative term when using alternate terminology. Each entry references another business term that is considered equivalent in meaning. |
data_classes | array<object> | Optional | List of data class assignments that associate this term with data classification rules and patterns. Data classes define technical patterns (e.g., regex, data types) for identifying data that represents this business concept. Enables automated term assignment to data assets based on content analysis. |
classifications | array<object> | Optional | List of classification assignments for governance, security, or compliance labeling. Classifications can indicate data sensitivity levels, regulatory scope (PII, PHI, PCI), retention policies, or other governance metadata. Drives policy enforcement and access control decisions for data assets associated with this term. |
custom_attributes | array<object> | Optional | List of custom attribute values for organization-specific metadata extensions. Allows organizations to capture additional governance metadata beyond the standard fields, such as business owner contacts, approval workflows, data quality metrics, or domain-specific properties. Each custom attribute has a name and value. |
effective_start_date | string | Optional | ISO 8601 timestamp indicating when this term definition becomes effective and should be used for governance purposes. Enables planned rollout of terminology changes and supports time-based governance processes. If not specified, the term is immediately effective upon creation. |
effective_end_date | string | Optional | ISO 8601 timestamp indicating when this term definition expires or is superseded. Allows organizations to phase out deprecated terminology while maintaining historical context. Terms past their end date may be hidden from active use while remaining available for historical data interpretation. |
workflow_state | string | Optional | Lifecycle state of the business term controlling its visibility and governance status. DRAFT terms are works in progress not yet ready for general use. PUBLISHED terms are approved and actively used for governance. ARCHIVED terms are retired but retained for historical reference. This state cannot be changed after creation through updates - state transitions use separate workflow APIs. |
artifact_id, version_id.
business_terms
Business Terms provides bulk creation functionality for multiple business terms in a single API call.
Runs on SaaS + Software · ID field name
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v3/glossary_terms |
| Read | GET | /v3/glossary_terms/{name} |
| Delete | DELETE | /v3/glossary_terms/{name} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Name identifier for this business terms operation. Used as a reference within configuration files to identify the batch. |
terms | array<object> | Optional | Array of business term definitions to create. Each term object should include name, short_description, long_description, and optionally parent_category. The parent_category should be an object with an id field referencing the category artifact_id. Required if import_file is not specified. |
import_file | string | Optional | Path to a CSV file containing business terms to import. The CSV should have columns matching the term fields (name, short_description, long_description, etc.). Required if terms is not specified. |
merge_option | string | Optional | Merge option for import operations (only used with import_file). Controls how imported terms are merged with existing terms. Valid values: all, specified, none. Ignored for inline terms. |
async_mode | boolean | Optional | Whether to run the import operation asynchronously (only used with import_file). When true, the API returns immediately and processes the import in the background. Ignored for inline terms. |
catalog
A Catalog is a metadata repository that organizes and manages table schemas, partitions, and file locations for data lake operations in Watsonx Data.
Runs on SaaS + Software · ID field guid
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v2/catalogs?check_bucket_existence=false |
| Read | GET | /v2/catalogs/{guid} |
| List | GET | /v2/catalogs |
| Update | PATCH | /v2/catalogs/{guid} |
| Delete | DELETE | /v2/catalogs/{guid} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Unique name identifier for the catalog. This name must be unique across all catalogs in the Watsonx Data instance and is used in SQL queries and data operations to specify which catalog contains the target tables. The name becomes part of the three-part table naming convention: catalog.schema.table. |
description | string | Optional | Human-readable description of the catalog’s purpose and contents. Used for documentation and helping users understand what data and schemas are organized within this catalog. This description appears in catalog listings and management interfaces. |
generator | string | Optional | Identifier for the tool or system that generated this catalog. Used for tracking catalog provenance and management tooling. Defaults to ‘wxctl’ when created by this tool. |
bucket | object | Required | Bucket configuration for catalog storage. Specifies the bucket name and type for storing catalog metadata and table data. |
storage | object | Optional | Storage configuration that specifies where catalog metadata and table data are physically stored. References a bucket resource and defines the cloud storage provider type for accessing the data. |
tags | array<string> | Optional | Categorization tags for organizing and discovering catalogs. Tags help users filter and find catalogs based on data domain, sensitivity level, environment, or other organizational dimensions. These tags are user-defined and have no impact on catalog functionality. |
guid, created_at.
Consumers
common_core_connection→.catalog_id(optional)schema→.catalog_id(required)
category
A Category is a hierarchical classification structure used to organize and group data assets, business terms, and other governance artifacts in Watsonx Data.
Runs on SaaS + Software · ID field artifact_id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v3/categories |
| Read | GET | /v3/categories/{artifact_id} |
| List | GET | /v3/categories |
| Update | PATCH | /v3/categories/{artifact_id} |
| Delete | DELETE | /v3/categories/{artifact_id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Unique name identifier for the category within its parent scope. This name is used as the primary human-readable reference and appears in governance catalogs, taxonomy browsers, and asset classification interfaces. The name should clearly represent the classification concept or organizational dimension this category represents. |
long_description | string | Optional | Detailed description explaining the category’s purpose, scope, and what types of assets or terms should be classified under it. This description helps users understand when to apply this category and provides governance context for data classification decisions. Supports rich text for comprehensive documentation. |
parent_category | string | Optional | Reference to the parent category in the hierarchy. When specified, this category becomes a subcategory of the parent, enabling multi-level taxonomy structures. Categories without a parent are root-level categories. This creates a soft dependency on another category resource for hierarchical organization. The live /v3/categories create API names this field parent_category_id on the wire (a bare parent_category → 400 “not allowed in request”), so it is sent via api_field. |
artifact_id, created_at.
Depends on
parent_category→category(optional)
category→.parent_category(optional)
common_core_connection
A Connection is a data source configuration that enables Watsonx Data to access external databases, object storage systems, and other data repositories.
Runs on SaaS + Software · ID field asset_id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v2/connections |
| Read | GET | /v2/connections/{asset_id} |
| List | GET | /v2/connections |
| Update | PATCH | /v2/connections/{asset_id} |
| Delete | DELETE | /v2/connections/{asset_id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Unique name identifier for the connection. This name must be unique across all connections in the Watsonx Data instance and is used as the primary human-readable reference when configuring catalogs, running queries, or managing data sources. |
datasource_type | string | Required | Type of external data source this connection represents. Can be either a named type (postgresql, mysql, oracle, db2, netezza, s3, cos, azure) or a UUID identifying a custom datasource definition. Determines which connection properties are required and how the system authenticates and communicates with the datasource. Database types use JDBC connections with username/password authentication. Storage types use cloud-native protocols with key-based authentication. This type cannot be changed after connection creation. |
description | string | Optional | Human-readable description of the connection’s purpose and contents. Used for documentation and helping users understand what data source this connection provides access to. Appears in connection listings and management interfaces. |
properties | object | Required | Connection properties specific to the datasource type. The required properties vary based on datasource_type. Database connections typically require host, port, database, username, and password. Storage connections require bucket/url, access_key, and secret_key. Properties are validated based on the datasource_type to ensure all required credentials are provided. |
catalog_id | string | Optional | Reference to a catalog resource that this connection is associated with. When specified, the connection is scoped to the catalog for metadata management and query operations. Creates a soft dependency on the catalog resource. Mutually exclusive with project_id and space_id. Passed as query parameter in API requests. |
project_id | string | Optional | IBM Cloud project identifier for scoping the connection within a specific project context. When specified, the connection is accessible only within the designated project. Mutually exclusive with catalog_id and space_id. Cannot be changed after connection creation. Passed as query parameter in API requests. |
space_id | string | Optional | IBM Cloud space identifier for scoping the connection within a specific deployment space. When specified, the connection is accessible only within the designated space. Mutually exclusive with catalog_id and project_id. Cannot be changed after connection creation. Passed as query parameter in API requests. |
test | string | Optional | When set to “false”, the IBM Cloud /v2/connections endpoint skips its synchronous connectivity check against the datasource during create. Useful for declarative configs whose credentials reference hosts not reachable from the control plane (development, staging fixtures, etc.) and for tests. Defaults to true server-side. |
asset_id.
Depends on
catalog_id→catalog(optional)project_id→project(optional)space_id→space(optional)
- warn (doc_cited, 2026-05-08): In Data Refinery flows, the IBM watsonx.data Presto connection (and the plain Presto, Apache Hive, Cognos Analytics, and several other connections) can be used as a source only, not as a target. Data Refinery also cannot connect to data sources that use Kerberos authentication.
- info (doc_cited, 2026-05-08): In SPSS Modeler, SQL pushback offloads supported operations to the source database. Connections that support SQL pushback include PostgreSQL, MySQL, Db2, Oracle, Microsoft SQL Server, Snowflake, Teradata, and the IBM watsonx.data Presto connection (which is read-only inside SPSS Modeler). Object-storage and file connectors, which have no SQL engine, do not support SQL pushback.
- info (doc_cited, 2026-05-08): The IBM watsonx.data Presto connection targets one of three deployment types (Developer edition, as a Service, on Red Hat OpenShift). All three take a hostname, a port (default 443), and an instance ID, except as a Service which takes a Cloud Resource Name (CRN) in place of the instance ID. Credentials vary by deployment: Developer edition uses a username and password; as a Service uses an API key (the username is ibmlhapikey_<account-email> and the password is the API key); on Red Hat OpenShift uses either a username and password or a username and API key. SSL is enabled by default and any certificate must be in PEM format.
- warn (doc_cited, 2026-05-08): Engine connection details on the IBM watsonx.data Presto connection are deprecated. You can still add and update them, but they will be discontinued in a future release. The watsonx.data Presto connection can read from watsonx.data and write Iceberg and Delta Lake tables to object storage; the plain Presto connection is read-only. Known limitations: TIME and TIMESTAMP data types are unsupported on the Presto C++ engine, and writing Delta Lake tables to Azure Data Lake Storage is unsupported.
data_asset
A Data Asset uploads a local file such as a CSV into a space or project as a CAMS data asset and exposes its asset id for downstream consumers such as an AutoAI experiment’s training_data_references.
Runs on SaaS + Software · ID field asset_id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v2/assets |
| Read | GET | /v2/assets/{asset_id} |
| List | GET | /v2/asset_types/data_asset/search |
| Delete | DELETE | /v2/assets/{asset_id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Asset name (shown in the space catalog). |
description | string | Optional | Human-readable description. |
mime_type | string | Optional | MIME type of the uploaded file. Defaults to text/csv. |
source_path | string | Required | Local path to the file to upload. Resolved against the config file’s directory. |
space_id | string | Optional | The space ID scope. |
project_id | string | Optional | The project ID scope. |
asset_id, created_at.
Depends on
space_id→space(optional)project_id→project(optional)
autoai_experiment→.training_data(required)
environment
A notebook runtime environment in a watsonx.ai project.
Runs on SaaS + Software · ID field guid
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v2/environments |
| Read | GET | /v2/environments/{guid} |
| List | GET | /v2/environments?types=notebook |
| Delete | DELETE | /v2/environments/{guid} |
| Field | Type | Required | Description |
|---|---|---|---|
display_name | string | Required | The environment display name (the identity discovery matches on). |
type | string | Optional | Environment type. Defaults to notebook. |
project_id | string | Optional | The project ID scope. |
guid, created_at.
Depends on
project_id→project(optional)
job→.environment(optional)notebook→.environment(optional)
job
A platform Job definition in a watsonx.ai project: a reusable run configuration binding a runnable asset (a script_asset or a notebook) to a runtime environment.
Runs on SaaS + Software · ID field asset_id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v2/jobs |
| Read | GET | /v2/jobs/{asset_id} |
| List | GET | /v2/jobs |
| Delete | DELETE | /v2/jobs/{asset_id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Job name (shown in the project’s Jobs list). |
description | string | Optional | Human-readable description. |
asset | string | Required | Id of the runnable asset this job executes, a script_asset or a notebook. Sent in the create body as asset_ref. References either kind so the job is created after the asset it binds (mirrors wml_deployment.asset, primary field is the script id; a ${notebook.x.guid} value is accepted via also_allows). |
environment | string | Optional | The runtime environment guid the job runs on. Sent under configuration.env_id. |
env_variables | array<object> | Optional | Environment-variable overrides passed to each run (name/value objects in config, readable YAML, individually sensitive-markable). Sent under configuration.env_variables, converted by JobHandler to an array of “NAME=value” strings, the wire shape the API actually requires (live-verified 2026-07-05, both SaaS and CP4D: the object shape 400s with “must be string”). ${env:VAR}-interpolatable and sensitive (redacted in logs / run records). |
schedule | string | Optional | Cron schedule string for recurring runs (e.g. “0 2 * * *”). Sent under the job envelope as job.schedule. An empty string means unscheduled. Maps to the Jobs API job.schedule field (POST/PATCH /v2/jobs). |
schedule_info | object | Optional | Optional schedule metadata sent under job.schedule_info: repeat (bool) and startOn / endOn (epoch-ms integers). Passed through verbatim to the Jobs API. |
project_id | string | Optional | The project ID scope. |
asset_id, created_at.
Depends on
asset→script_asset(required)asset→notebook(optional)environment→environment(optional)project_id→project(optional)
job_run→.job(required)
job_run
A single execution of a platform job.
Runs on SaaS + Software · ID field id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v2/jobs/{job}/runs |
| Read | GET | /v2/jobs/{job}/runs/{id} |
| List | GET | /v2/jobs/{job}/runs |
| Delete | DELETE | /v2/jobs/{job}/runs/{id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Run name, display only. The server stores every run as “Notebook Job” regardless of the submitted name (both CPDaaS and CP4D, live-pinned 2026-07-05); identity rides the WXCTL_IDENTITY env marker instead, so the name is submitted but never matched or diffed. |
job | string | Required | Id of the parent job to run. Fills the {job} path segment. References job.asset_id → DAG edge so the run submits after the job exists. |
env_variables | array<object> | Optional | Per-run environment-variable overrides (name/value objects in config, readable YAML, individually sensitive-markable), folded into the submit body by the handler as an array of “NAME=value” strings, the wire shape the API actually requires (live-verified 2026-07-05, both SaaS and CP4D: the object shape 400s with “must be string”). ${env:VAR}-interpolatable and sensitive. LocalOnly, the handler owns the submit body, so it is never materialized generically; the api_field records the wire path so redaction covers the response envelopes ([results.]entity.job_run.configuration.env_variables, responses echo the values back verbatim). It is still folded into the identity hash, and the validation stamp step injects a reserved WXCTL_IDENTITY=<hash8> entry here (replacing any user entry of that name), the run’s identity marker. |
project_id | string | Optional | The project ID scope for the run endpoints. |
generation | integer | Optional | Optional re-run nonce (Kubernetes metadata.generation semantics). Bump to launch a new run with all other inputs unchanged; folded into the identity hash and never sent to the API body. Prior generations are retained. |
id, state.
Depends on
job→job(required)project_id→project(optional)
asset_promotion→.job_run(optional)
package_extension
A Package Extension defines additional Python packages to include in a software specification.
Runs on SaaS + Software · ID field asset_id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v2/package_extensions |
| Read | GET | /v2/package_extensions/{asset_id} |
| List | GET | /v2/package_extensions |
| Delete | DELETE | /v2/package_extensions/{asset_id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Name of the package extension. |
description | string | Optional | Human-readable description. |
type | string | Required | Extension type. ‘requirements_txt’ accepts a plain pip requirements file, ‘custom_library’ accepts a tar.gz with a Python package. ‘conda_yml’ and ‘pip_zip’ are kept for backward schema-compatibility but rejected by IBM Cloud. |
source_path | string | Required | Local path to the file to upload (requirements.txt for requirements_txt, tar.gz for custom_library). Resolved against the config file’s directory. |
space_id | string | Optional | The space ID scope. |
project_id | string | Optional | The project ID scope. |
asset_id, created_at.
Depends on
space_id→space(optional)project_id→project(optional)
software_specification→.package_extensions(optional)
project
A Project is a collaborative workspace that organizes assets, tools, notebooks, jobs, and data connections for data science and AI workflows.
Runs on SaaS + Software · ID field guid
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /transactional/v2/projects |
| Read | GET | /v2/projects/{guid} |
| List | GET | /v2/projects?limit=100 |
| Update | PATCH | /v2/projects/{guid} |
| Delete | DELETE | /v2/projects/{guid} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | The name of the project. Must be non-empty and cannot contain certain special characters. Used as the primary human-readable identifier for the project. |
description | string | Optional | Human-readable description of the project’s purpose, scope, and contents. Displayed in project listings and management interfaces. |
type | string | Optional | The project type. The ‘cpd’ type classifies IBM Cloud Pak for Data projects. The ‘wx’ type classifies IBM watsonx projects. The ‘wca’ type classifies IBM watsonx Code Assistant projects. |
tags | array<string> | Optional | User-defined tags for organizing and filtering projects. Tags help categorize projects by purpose, team, environment, or other organizational dimensions. |
storage | object | Optional | Object storage configuration for the project. Required for project creation. Specifies the Cloud Object Storage instance and credentials for storing project assets. |
generator | string | Optional | Identifier for the tool or system that created this project. Defaults to ‘wxctl-cli’ when created by this tool. Used for tracking project provenance. |
guid, created_at, updated_at.
Consumers
ai_service→.project_id(optional)asset_promotion→.project_id(optional)autoai_experiment→.project_id(optional)common_core_connection→.project_id(optional)data_asset→.project_id(optional)environment→.project_id(optional)job→.project_id(optional)job_run→.project_id(optional)model→.provider_config.watsonx_project_id(optional)model_tracking→.project_id(optional)notebook→.project_id(optional)package_extension→.project_id(optional)script_asset→.project_id(optional)software_specification→.project_id(optional)wml_deployment→.project_id(optional)wml_function→.project_id(optional)wml_model→.project_id(optional)wml_script→.project_id(optional)
rule
A Rule is an automated policy enforcement mechanism that implements data governance controls in Watsonx Data.
Runs on SaaS + Software · ID field guid
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v3/enforcement/rules |
| Read | GET | /v3/enforcement/rules/{guid} |
| List | GET | /v3/enforcement/rules |
| Update | PUT | /v3/enforcement/rules/{guid} |
| Delete | DELETE | /v3/enforcement/rules/{guid} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Unique name identifier for the rule. This name must be unique across all rules and serves as the primary human-readable reference for rule identification, monitoring, and management. The name should clearly describe the governance policy or control that the rule implements. |
description | string | Optional | Human-readable description explaining the rule’s purpose, business rationale, and governance objectives. Should document what policy the rule enforces, why it exists, and what outcomes it achieves. Helps governance teams understand and maintain the rule over time. |
governance_type_id | string | Required | Identifier specifying the type of governance control this rule implements. The governance type determines what events the rule can respond to, what actions are available, and how the rule integrates with the broader governance framework. The live /v3/enforcement/governance_types surface accepts Access and ResourceControl; query that endpoint for the full set. |
trigger | array | Required | Trigger condition specification that defines when the rule should execute. The trigger is an array representing a condition expression, typically in the form of [subject, operator, value] (e.g., [“term_id”]]). The trigger structure varies by governance_type_id and is evaluated by the governance engine to determine rule execution timing. |
action | object | Required | Action specification that defines what operations the rule performs when triggered. Actions can include access grants/denials, metadata assignments, notifications, workflow initiations, data quality checks, or cascading subactions. The action structure varies by governance_type_id and can contain nested subactions for complex multi-step governance workflows. Actions are executed atomically when the trigger condition is met. |
state | string | Optional | Lifecycle state controlling whether the rule is actively enforced. The live /v3/enforcement/rules API uses lowercase states: draft rules are defined but not executed, allowing testing and review before activation; active rules are enforced by the governance engine and execute automatically when their trigger conditions are met; archived rules are retired but retained for reference. Defaults to draft. |
guid, rule_id.
rules
Rules provides bulk creation functionality for multiple governance rules in a single API call.
Runs on SaaS + Software · ID field name
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v3/enforcement/rules |
| Read | GET | /v3/enforcement/rules/{name} |
| List | GET | /v3/enforcement/rules |
| Delete | DELETE | /v3/enforcement/rules/{name} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Name identifier for this rules operation. Used as a reference within configuration files to identify the batch. |
rules | array<object> | Optional | Array of rule definitions to create. Each rule object should include name, description, governance_type_id, trigger, action, and optionally state. The trigger should be an array representing a condition expression, and the action should be an object defining the enforcement behavior. Required if import_file is not specified. |
import_file | string | Optional | Path to a JSON file containing rules to import. The JSON should have a “rules” array with rule objects matching the rule schema. Required if rules is not specified. |
script_asset
A Script Asset uploads a local Python file into a watsonx.ai project (or space) as a CAMS asset of type script, exposing its asset id for a platform job to run.
Runs on SaaS + Software · ID field asset_id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v2/assets |
| Read | GET | /v2/assets/{asset_id} |
| List | GET | /v2/asset_types/script/search |
| Delete | DELETE | /v2/assets/{asset_id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Script asset name (shown in the project catalog). |
description | string | Optional | Human-readable description. |
language | string | Optional | Script language. Defaults to python3. |
software_spec | string | Optional | Base software specification name (e.g. runtime-25.1-py3.12). Carried into entity.script.runtime when present. Name-to-id resolution is wired live in Phase 5. |
source_path | string | Required | Local path to the Python file to upload. Resolved against the config file’s directory. |
space_id | string | Optional | The space ID scope (space_id XOR project_id). |
project_id | string | Optional | The project ID scope (space_id XOR project_id). |
asset_id, created_at.
Depends on
space_id→space(optional)project_id→project(optional)
job→.asset(required)
software_specification
A Software Specification defines a runtime environment for deploying AI services and functions.
Runs on SaaS + Software · ID field asset_id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v2/software_specifications |
| Read | GET | /v2/software_specifications/{asset_id} |
| List | GET | /v2/software_specifications |
| Update | PATCH | /v2/software_specifications/{asset_id} |
| Delete | DELETE | /v2/software_specifications/{asset_id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Name of the software specification. |
description | string | Optional | Human-readable description of the software specification. |
base_software_specification | string | Required | Name of the base software specification to derive from (e.g., runtime-25.1-py3.12). Resolved to a GUID by the pre_create handler. |
package_extensions | array<string> | Optional | List of package extension references. Each entry is a ${package_extension.ref_name} reference resolved to a GUID by the pre_create handler. |
space_id | string | Optional | The space ID scope. |
project_id | string | Optional | The project ID scope. |
asset_id, created_at.
Depends on
package_extensions→package_extension(optional)space_id→space(optional)project_id→project(optional)
ai_service→.software_spec(required)wml_function→.software_spec(required)wml_script→.software_spec(required)
space
A Space is a deployment environment for promoting and managing machine learning models, functions, and other AI assets.
Runs on SaaS + Software · ID field id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v2/spaces |
| Read | GET | /v2/spaces/{id} |
| List | GET | /v2/spaces |
| Update | PATCH | /v2/spaces/{id} |
| Delete | DELETE | /v2/spaces/{id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Name of the space. Used as the primary human-readable identifier for the space in listings and management interfaces. |
description | string | Optional | Human-readable description of the space’s purpose and contents. Displayed in space listings and management interfaces. |
storage | object | Optional | 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. |
tags | array<string> | Optional | User-defined tags for organizing and filtering spaces. Tags help categorize spaces by purpose, team, environment, or other dimensions. |
generator | string | Optional | Identifier for the tool or system that created this space. Defaults to ‘wxctl’ when created by this tool. Used for tracking space provenance. |
stage | object | Optional | Production stage configuration. Defines whether the space is a production or non-production environment and its stage name (e.g., development, test, pre-production, production). |
compute | array<object> | Optional | List of compute resources associated with the space. Required for deployments. Each entry specifies a service instance (e.g., Watson Machine Learning) by CRN, GUID, name, and type. |
type | string | Optional | Space type. |
id, created_at, updated_at, status.
Consumers
ai_service→.space_id(optional)asset_promotion→.space_id(optional)autoai_experiment→.space_id(optional)common_core_connection→.space_id(optional)data_asset→.space_id(optional)model→.provider_config.watsonx_space_id(optional)model_tracking→.space_id(optional)package_extension→.space_id(optional)script_asset→.space_id(optional)service_provider→.deployment_space_id(optional)software_specification→.space_id(optional)wml_deployment→.space_id(optional)wml_function→.space_id(optional)wml_model→.space_id(optional)wml_script→.space_id(optional)