Create a new data mart

POST /v2/data_marts

Create a new data mart with the given database connection

Request

Request Body

DataMartRequest

name

string

Name of the data mart

description

string

Description of the data mart

service_instance_crn

string

Can be omitted if user token is used for authorization

internal_database

boolean

If `true` the internal database managed by AI OpenScale is provided for the user

database_configuration

DatabaseConfigurationRequest

Database configuration ignored if internal database is requested (`internal_database` is `true`)

database_type

Required *

string

name

string

instance_id

string

credentials

Required *

PrimaryStorageCredentials

location

object

database_discovery

string

Indicates if the database was discovered automatically or manually added by user through UI

Path Parameters

Query Parameters

force

boolean

force update of metadata and db credentials (assumption is that the new database is already prepared and populated)

Response

202 - response

metadata

Metadata

entity

object

429 - Too many requests for internal database. Please try again in a while.

trace

string

ID of the original request

errors

array

List all data marts

GET /v2/data_marts

The method returns the data mart configurations as an object.

Request

Response

200 - response

data_marts

array

Get data mart with the given id

GET /v2/data_marts/{data_mart_id}

Request

Response

200 - response

metadata

Metadata

entity

object

Update a data mart

PATCH /v2/data_marts/{data_mart_id}

Request

Request Body

Response

200 - Data Marts updated successfully

metadata

Metadata

entity

object

Delete a data mart

DELETE /v2/data_marts/{data_mart_id}

Request

Path Parameters

Query Parameters

force

boolean

Force hard delete

Response

202 - Accepted

List all data sets specified by the parameters

GET /v2/data_sets

Request

Path Parameters

Query Parameters

target.target_id

string

ID of the data set target (e.g. subscription ID.. )

target.target_type

type of the target

type

type of the data set

managed_by

string

ID of the managing entity (e.g. data mart id)

Response

200 - response

data_sets

array

Create a new data set

POST /v2/data_sets

Create a new data set

Request

Request Body

DataSetObjectRequest

data_mart_id

Required *

string

name

Required *

string

description

string

type

Required *

string

type of a data set

target

Required *

Target

target_type

Required *

string

Type of the target (e.g. subscription, ...)

target_id

Required *

string

ID of the data set target (e.g. subscription ID, ...)

schema_update_mode

string

data_schema

Required *

SparkStruct

type

Required *

string

fields

Required *

array

id

string

name

string

location

LocationTableName

table_name

string

Database table name

managed_by

string

Response

202 - response

metadata

Metadata

entity

DataSetObject

Get data set with the given id

GET /v2/data_sets/{data_set_id}

Request

Response

200 - response

metadata

Metadata

entity

DataSetObject

Delete a data set

DELETE /v2/data_sets/{data_set_id}

Request

Path Parameters

Query Parameters

force

boolean

Force hard delete. Table associated with the data set will be dropped.

Response

202 - Accepted

Update a data set

PATCH /v2/data_sets/{data_set_id}

Update the data set

Request

Request Body

PatchRequest

Response

200 - response

metadata

Metadata

entity

DataSetObject

Add new data set records

POST /v2/data_sets/{data_set_id}/records

Add new data set records

Request

Request Body

Path Parameters

Query Parameters

boolean

if not provided service will attempt to automatically detect header in the first line

skip

integer

skip number of rows from input

limit

integer

limit for number of processed input rows

delimiter

string

delimiter character for data provided as csv

on_error

string

expected behaviour on error

csv_max_line_length

number

maximum length of single line in bytes (default 10MB)

is_historical_data

boolean

specifies if the uploaded records are part of historical data

Response

202 - response

state

string

deleted_at

string

failure

GenericErrorResponse

List data set records

GET /v2/data_sets/{data_set_id}/records

List data set records

Request

Path Parameters

Query Parameters

start

string

return records with timestamp greater then or equal to `start` parameter

end

string

return records with timestamp lower then `end` parameter

limit

integer

limit for number of returned records. If the value is greater than 1000 than it will be truncated.

offset

integer

offset of returned records

includes

string

return records with only specified columns. Parameter must be specified as comma separated string.

annotations

array

return record annotations with given names

exclude_annotations

boolean

If there is no need to fetch annotations at all, set this parameter as true. There should be better performance.

filter

string

Only return records that match given filters. There are two types of filters, separated by commas: * normal filter (multiple are possible), {field_name}:{op}:{value} — filter records directly * joining filter (only a single one is possible), {data_set_id}.{field_name}:{op}:{value} — join a data set by transaction_id (the user must ensure it's provided!) and filter by this data set's records' field. Will fail if the user hasn't provided transaction_id for both data sets' records. Filters of different types can be mixed. They are partly compatible with the ones in POST /v2/data_sets/{data_set_id}/distributions.

Available operators: | op | meaning | example | code equivalent | |:----:|:---------------------------:|:------------------:|:------------------------:| | eq | equality | field:eq:value | field == value | | gt | greater than | field:gt:value | field > value | | gte | greater or equal | field:gte:value | field >= value | | lt | less than | field:lt:value | field < value | | lte | less or equal | field:lte:value | field <= value | | like | matching a simple pattern* | field:like:pattern | pattern.match(field) | | in | is contained in list | field:in:a;b;c | [a,b,c].contains(field) | | null | is null | field:null | field value == null | | nonnull | is not null | field:nonnull | field value != null |

    • "%" means "one or more character", "_" means "any single character", other characters have their usual, literal meaning (e.g. "|" means character "|")

include_total_count

boolean

If total_count should be included. It can have performance impact if total_count is calculated.

order

string

return records in order specified. There are two patterns. The first is random sampling, the other is sorting per column.

seed

number

return repeatable result for random sampling. Value must be between 0.0 and 1.0, inclusive. Also you can get sampled records in pagination manner by specifying `limit` and `offset`.

format

What JSON format to use on output.

binary_format

string

Binary data presentation format. By default, the binary field value is encoded to base64 string. If reference is chosen, every binary field is moved to the references section with value set to an uri to the particular field within the record that can be GET in a separate request.

Response

200 - response

Update data set records

PATCH /v2/data_sets/{data_set_id}/records

Update data set records

Request

Request Body

PatchRequest

Response

202 - response

state

string

deleted_at

string

failure

GenericErrorResponse

Get a specific data set record with the given id

GET /v2/data_sets/{data_set_id}/records/{record_id}

Get a specific record in a data set

Request

Response

200 - response

metadata

Metadata

entity

DataRecord

Update a specific record in a data set

PATCH /v2/data_sets/{data_set_id}/records/{record_id}

Update a specific record in a data set

Request

Request Body

PatchRequest

Response

200 - response

metadata

Metadata

entity

DataRecord

Get value of a field in a given record

GET /v2/data_sets/{data_set_id}/records/{record_id}/{field_name}

Get value of a field in a given record

Request

Response

200 - field_name value. If field_name column is of binary type, its content type is obtained from field_name.metadata column or defaults to application/octet-stream. For other db column types, the result is json in a form: {field_name: field_value}

404 - if either record_id or field_name is invalid

Get data set records using record_id or transaction_id

GET /v2/data_set_records

Get data set records with specific record_id or transaction_id

Request

Path Parameters

Query Parameters

record_id

one or more record id values that should be matched

transaction_id

one or more transaction id values that should be matched

data_set_type

Required *

a (single) data set type

start

string

beginning of the time range

end

string

end of the time range

offset

integer

offset of returned explanations

limit

integer

Maximum number of elements returned

Response

200 - response

data_set_records

array

Get status of a specific request

GET /v2/data_sets/{data_set_id}/requests/{request_id}

Get status of a specific request

Request

Response

200 - response

state

string

deleted_at

string

failure

GenericErrorResponse

add new data distributions

POST /v2/data_sets/{data_set_id}/distributions

add new data distributions

Request

Request Body

DataDistributionRequest

start

Required *

string

start datetime in ISO format

end

Required *

string

end datetime in ISO format

dataset

Required *

string

type of a data set

limit

number

limit for number of rows, by default it is 50,000 (max possible limit is 50,000)

group

Required *

array

names of columns to be grouped

filter

string

Filters defined by user in format: {field_name}:{op}:{value}. Partly compatible with filters in "filter" parameter of GET /v2/data_sets/{data_set_id}/records.

Possible filter operators:

  • eq - equals (numeric, string)
  • gt - greater than (numeric)
  • gte - greater than or equal (numeric)
  • lt - lower than (numeric)
  • lte - lower than or equal (numeric)
  • in - value in a set (numeric, string)
  • field:null (a no-argument filter) - value is null (any nullable)
  • field:exists (a no-argument filter) - value is not null (any column)

agg

DataDistributionAgg

Definition of aggregations, by default 'count'.

Aggregations can be one of:

  • count
  • <column_name>:sum
  • <column_name>:min
  • <column_name>:max
  • <column_name>:avg
  • <column_name>:stddev

max_bins

number

max number of bins which will be generated for data

Path Parameters

Query Parameters

nocache

boolean

force columns data refresh

Response

202 - response

metadata

Metadata

entity

object

Data distribution creation request

Delete data distributions

DELETE /v2/data_sets/{data_set_id}/distributions

Delete data distribution

Request

Response

204 - Deleted

Get a specific data distribution

GET /v2/data_sets/{data_set_id}/distributions/{data_distribution_id}

Get a specific data distribution

Request

Response

200 - response

metadata

Metadata

entity

object

Data distribution creation request

List available monitors

GET /v2/monitor_definitions

List available monitors

Request

Path Parameters

Query Parameters

name

string

comma-separated list of names

type

string

Either of `service` or `user` can be specified. `service` is corresponding to monitor definitions managed by IBM, and `user` is corresponding to those of managed by users.

Response

200 - response

monitor_definitions

array

Add custom monitor

POST /v2/monitor_definitions

Add custom monitor

Request

Request Body

MonitorRequest

name

Required *

string

Monitor UI label (must be unique).

description

string

Long monitoring description presented in monitoring catalog.

metrics

Required *

array

A list of metric definition.

tags

Required *

array

Available tags.

applies_to

ApplicabilitySelection

input_data_type

array

problem_type

array

target_type

array

parameters_schema

object

JSON schema that will be used to validate monitoring parameters when enabled

managed_by

string

schedule

MonitorInstanceSchedule

The schedule used to control how frequently the target is monitored. The maximum frequency is once every 30 minutes. Defaults to once every hour if not specified.

repeat_interval

Required *

integer

The interval to monitor the target.

repeat_unit

Required *

string

The type of interval to monitor the target.

start_time

object

Definition of first run time for scheduled activity; either absolute or relative the the moment of activation

repeat_type

string

The type of interval to monitor the target.

status

string

The status of scheduler to trigger new evaluation based on configuration

schedules

object

A set of schedules used to control how frequently the target is monitored for online and batch deployment type.

online

object

The schedule used to control how frequently the target is monitored. The maximum frequency is once every 30 minutes. Defaults to once every hour if not specified.

batch

object

The schedule used to control how frequently the target is monitored. The maximum frequency is once every 30 minutes. Defaults to once every hour if not specified.

monitor_runtime

MonitorRuntime

Field to specify if scheduler should be created or not.

type

Required *

string

when either `service` or `custom_metrics_provider` is specified, scheduler gets created. `service` is for OOTB, `custom_metrics_provider` is for custom metric integrated.

Response

201 - response

metadata

Metadata

entity

Monitor

Get a specific monitor definition

GET /v2/monitor_definitions/{monitor_definition_id}

Get a specific monitor definition

Request

Response

200 - response

metadata

Metadata

entity

Monitor

Update the monitor definition

PUT /v2/monitor_definitions/{monitor_definition_id}

Update a monitor definition

Request

Request Body

MonitorRequest

name

Required *

string

Monitor UI label (must be unique).

description

string

Long monitoring description presented in monitoring catalog.

metrics

Required *

array

A list of metric definition.

tags

Required *

array

Available tags.

applies_to

ApplicabilitySelection

input_data_type

array

problem_type

array

target_type

array

parameters_schema

object

JSON schema that will be used to validate monitoring parameters when enabled

managed_by

string

schedule

MonitorInstanceSchedule

The schedule used to control how frequently the target is monitored. The maximum frequency is once every 30 minutes. Defaults to once every hour if not specified.

repeat_interval

Required *

integer

The interval to monitor the target.

repeat_unit

Required *

string

The type of interval to monitor the target.

start_time

object

Definition of first run time for scheduled activity; either absolute or relative the the moment of activation

repeat_type

string

The type of interval to monitor the target.

status

string

The status of scheduler to trigger new evaluation based on configuration

schedules

object

A set of schedules used to control how frequently the target is monitored for online and batch deployment type.

online

object

The schedule used to control how frequently the target is monitored. The maximum frequency is once every 30 minutes. Defaults to once every hour if not specified.

batch

object

The schedule used to control how frequently the target is monitored. The maximum frequency is once every 30 minutes. Defaults to once every hour if not specified.

monitor_runtime

MonitorRuntime

Field to specify if scheduler should be created or not.

type

Required *

string

when either `service` or `custom_metrics_provider` is specified, scheduler gets created. `service` is for OOTB, `custom_metrics_provider` is for custom metric integrated.

Response

200 - response

metadata

Metadata

entity

Monitor

Update a monitor definition

PATCH /v2/monitor_definitions/{monitor_definition_id}

Update a monitor definition

Request

Request Body

Response

200 - Monitor updated successfully

metadata

Metadata

entity

Monitor

Delete a monitor definition

DELETE /v2/monitor_definitions/{monitor_definition_id}

Delete a monitor definition, backing up table specific to monitor

Request

Path Parameters

Query Parameters

force

boolean

Force hard delete. Table specific to this monitor will be dropped from data mart.

Response

204 - Removes the Custom Monitor

List service providers

GET /v2/service_providers

List associated Machine Learning service instances

Request

Path Parameters

Query Parameters

show_deleted

boolean

show also resources pending delete

service_type

string

Type of service

instance_id

string

comma-separated list of IDs

operational_space_id

string

comma-separated list of IDs

deployment_space_id

string

comma-separated list of IDs

integrated_project_id

string

comma-separated list of IDs

Response

200 - response

service_providers

array

Add service provider

POST /v2/service_providers

Associate external Machine Learning service instance with the OpenScale DataMart

Request

Request Body

ServiceProviderRequestObjectMk2

name

Required *

string

Name of the ML service instance

description

string

service_type

Required *

string

machine learning service type (azure_machine_learning_studio is a preferred alias for azure_machine_learning and should be used in new service bindings)

credentials

Required *

MLCredentials

request_headers

object

map header name to header value

operational_space_id

string

Reference to Operational Space

deployment_space_id

string

Reference to V2 Space ID

integrated_project_id

string

Project ID

group_ids

array

Access control list of group id of Cloud Pak for Data (Only available for OpenScale on Cloud Pak for Data >= 4.0.6 with ENABLE_GROUP_AUTH being true)

user_ids

array

Access control list of user id of Cloud Pak for Data (Only available for OpenScale on Cloud Pak for Data >= 4.0.6 with ENABLE_GROUP_AUTH being true)

Response

201 - response

metadata

Metadata

entity

object

Get a specific service provider

GET /v2/service_providers/{service_provider_id}

Get the associated Machine Learning service provider details

Request

Response

200 - response

metadata

Metadata

entity

object

Delete a service provider

DELETE /v2/service_providers/{service_provider_id}

Detach Machine Learning service provider

Request

Path Parameters

Query Parameters

force

boolean

Force hard delete

Response

202 - Accepted

Update a service provider

PATCH /v2/service_providers/{service_provider_id}

Update existing service provider

Request

Request Body

PatchRequest

Response

200 - response

metadata

Metadata

entity

object

List subscriptions

GET /v2/subscriptions

List subscriptions

Request

Path Parameters

Query Parameters

data_mart_id

string

comma-separated list of IDs

service_provider_id

string

comma-separated list of IDs

asset.asset_id

string

comma-separated list of IDs

asset.asset_type

string

comma-separated list of types

asset.foundational_model_id

string

comma-separated list of IDs

deployment.deployment_id

string

comma-separated list of IDs

deployment.deployment_type

string

comma-separated list of types

integration_reference.integrated_system_id

string

comma-separated list of IDs

integration_reference.external_id

string

comma-separated list of IDs

risk_evaluation_status.state

string

comma-separated list of states

service_provider.operational_space_id

string

comma-separated list of operational space ids (property of service provider object)

service_provider.deployment_space_id

string

comma-separated list of deployment space ids (property of service provider object)

service_provider.integrated_project_id

string

comma-separated list of integrated project ids (property of service provider object)

pre_production_reference_id

string

comma-separated list of IDs

Response

200 - response

subscriptions

array

Add a new subscription

POST /v2/subscriptions

Add a new subscription to the model deployment

Request

Request Body

SubscriptionRequest

data_mart_id

Required *

string

service_provider_id

Required *

string

asset

Required *

Asset

asset_id

Required *

string

url

string

name

string

asset_type

Required *

string

asset_rn

string

Asset Resource Name (used for integration with 3rd party ML engines)

created_at

string

problem_type

string

model_type

string

runtime_environment

string

input_data_type

string

foundational_model_id

string

locale

object

represents languages used in both input and output of the model

asset_properties

AssetPropertiesRequest

Additional asset properties (subject of discovery if not provided when creating the subscription)

training_data_reference

TrainingDataReference

training_data_schema

SparkStruct

input_data_schema

SparkStruct

output_data_schema

SparkStruct

input_token_count_field

string

Field with this name will be given modeling_role `input-token-count`

output_token_count_field

string

Field with this name will be given modeling_role `output-token-count`

label_column

string

labels

array

dashboard_configuration

object

predicted_target_field

string

Field with this name will be given modeling_role `decoded-target`

prediction_field

string

Field with this name will be given modeling_role `prediction`

transaction_id_field

string

Field with this name will have `transaction_id_key` metadata set to true

feature_fields

array

Fields to be given modeling_role feature

categorical_fields

array

Fields to be given metadata `measure` of value `discrete`

context_fields

array

Contexts fields with this name will be given `prompt_role` as `context_field` used in Retrieval-Augmented Generation.

question_field

string

Question field with this name will be given `prompt_role` as `question_field` used in Retrieval-Augmented Generation.

probability_fields

array

Fields to be given modeling_role `class_probability` (for columns of double data type) or `probability` (for column of array data type)

prediction_names

array

Prediction names for multiple output models

deployment

Required *

AssetDeploymentRequest

deployment_id

Required *

string

deployment_rn

string

Deployment Resource Name (used for integration with 3rd party ML engines)

url

string

name

Required *

string

description

string

deployment_type

Required *

string

Deployment type

created_at

string

scoring_endpoint

ScoringEndpointRequest

Definition of scoring endpoint in custom_machine_learning

risk_evaluation_status

RiskEvaluationStatus

state

Required *

string

comment

string

Optional comment to the evaluation

evaluated_by

string

Author of the evaluation

evaluated_at

string

Time of the evaluation

analytics_engine

AnalyticsEngine

type

Required *

string

Type of analytics engine. e.g. spark

integrated_system_id

string

id of the Integrated System

credentials

object

Credentials to override credentials in integration_reference

parameters

object

Additional parameters (e.g. max_num_executors, min_num_executors, executor_cores, executor_memory, driver_cores, driver_memory)

data_sources

DataSourceCollection

Response

202 - response

metadata

Metadata

entity

object

Get a specific subscription

GET /v2/subscriptions/{subscription_id}

Get a specific subscription

Request

Response

200 - response

metadata

Metadata

entity

object

Update a subscription

PATCH /v2/subscriptions/{subscription_id}

Update existing asset (from ML service instance) subscription

Request

Request Body

PatchRequest

Response

200 - response

metadata

Metadata

entity

object

Delete a subscription

DELETE /v2/subscriptions/{subscription_id}

Delete a subscription

Request

Path Parameters

Query Parameters

force

boolean

Force hard delete. All data for records and metrics associated to the subscription will be deleted.

Response

202 - Stops monitoring of an asset and deletes all collected observations

Derive model schemas from the training data.

POST /v2/subscriptions/{subscription_id}/schemas

Derive model schemas from the training data. Only "structured" input data type is supported. If the input_data_type field in the subscription (subscription -> entity -> asset -> input_data_type) is not "structured", an error will be returned.

Request

Request Body

SchemaInferenceRequest

input_data

ScoreDataRecords

Array of score data object. If multiple score data objects are included, the "fields" array (if any) for score purposes will always be taken from the first score data object.

training_data_reference

InputDataReference

InputDataReference is the same as TrainingDataReference except that neither location nor connection is required. This is needed for the Schemas API and to avoid updating existing APIs.

type

Required *

string

Type of the storage

location

TrainingDataReferenceLocation

training data set location

connection

TrainingDataReferenceConnection

training data set connection credentials

name

string

Response

201 - Schemas created successfully

file_asset_metadata

FileAssetMetadata

File data asset metadata

subscription

SubscriptionResponse

Create a table for specified data set type

POST /v2/subscriptions/{subscription_id}/tables/{dataset_type}

Current supported dataset_type is feedback. The body of request should be json object (an empty object `{}` is fine).

Request

Request Body

Path Parameters

subscription_id

Required *

Unique subscription ID

dataset_type

Required *

data set type of subscription

Query Parameters

Response

202 - Creating dataset table is posted successfully.

metadata

Metadata

entity

DataSetObject

GET /v2/subscriptions/{subscription_id}/configuration_synchronization

Get status of triggered configuration synchronization

Request

Response

200 - Get current status of config synchronization

configurations

array

Trigger configuration synchronization from pre-production to production model

PUT /v2/subscriptions/{subscription_id}/configuration_synchronization

Trigger configuration synchronization based on `pre_production_reference_id` in `subscription`.

Request

Request Body

monitor definition id to be excluded from configuration synchronization should be passed as array

exclude_monitors

array

Path Parameters

Query Parameters

force

boolean

a flag to synchronize forcely

Response

202 - Triggered to synchronize configuration.

configurations

array

Computes the bias mitigation/remediation for the specified model

POST /v2/subscriptions/{subscription_id}/predictions

Computes the bias mitigation/remediation for the specified model. The fairness monitoring debias request payload details must be valid.

Request

Request Body

FairnessMonitoringRemediationRequest

fields

array

The fields to process debias scoring

values

Required *

array

The values associated to the fields

Response

200 - Accepted

fields

array

The fields of the model processed debias scoring.

values

array

The values associated to the fields.

List monitor instances

GET /v2/monitor_instances

List monitor instances

Request

Path Parameters

Query Parameters

data_mart_id

string

comma-separated list of IDs

monitor_definition_id

string

comma-separated list of IDs

target.target_id

string

comma-separated list of IDs

target.target_type

string

comma-separated list of types

Response

200 - Monitor instances listed successfully

monitor_instances

array

Create a new monitor instance

POST /v2/monitor_instances

Create a new monitor instance

Request

Request Body

MonitorInstance

data_mart_id

Required *

string

monitor_definition_id

Required *

string

target

Required *

Target

target_type

Required *

string

Type of the target (e.g. subscription, ...)

target_id

Required *

string

ID of the data set target (e.g. subscription ID, ...)

parameters

MonitorInstanceParameters

Monitoring parameters consistent with the `parameters_schema` from the monitor definition

thresholds

array

schedule

MonitorInstanceSchedule

The schedule used to control how frequently the target is monitored. The maximum frequency is once every 30 minutes. Defaults to once every hour if not specified.

repeat_interval

Required *

integer

The interval to monitor the target.

repeat_unit

Required *

string

The type of interval to monitor the target.

start_time

object

Definition of first run time for scheduled activity; either absolute or relative the the moment of activation

repeat_type

string

The type of interval to monitor the target.

status

string

The status of scheduler to trigger new evaluation based on configuration

schedule_id

string

managed_by

string

unprocessed_records

RecordsCountSummary

Summary about records count

count

Required *

integer

type

Required *

string

The type of records time

timestamp

string

timestamp of last consumed record (only for unprocessed_records)

failure

GenericErrorResponse

total_records

object

Summary about records count

count

Required *

integer

type

Required *

string

The type of records time

timestamp

string

timestamp of last consumed record (only for unprocessed_records)

failure

GenericErrorResponse

value

string

Path Parameters

Query Parameters

skip_scheduler

boolean

prevent schedule creation for this monitor instance

Response

200 - Monitoring enabled successfully

metadata

Metadata

entity

object

202 - Monitoring configuration started

Get monitor instance details

GET /v2/monitor_instances/{monitor_instance_id}

Get monitor instance details

Request

Path Parameters

Query Parameters

expand

string

comma-separated list of fields (supported fields are unprocessed_records and total_records)

Response

200 - Monitoring details retrieved successfully

metadata

Metadata

entity

object

Update a monitor instance

PATCH /v2/monitor_instances/{monitor_instance_id}

Update a monitor instance

Request

Request Body

PatchRequest

Path Parameters

Query Parameters

update_metadata_only

boolean

Flag that allows to control if the underlying actions related to the monitor reconfiguration should be triggered

Response

200 - Monitoring updated successfully

metadata

Metadata

entity

object

202 - Monitoring update started

Delete a monitor instance

DELETE /v2/monitor_instances/{monitor_instance_id}

Delete a monitor instance

Request

Path Parameters

Query Parameters

force

boolean

Force hard delete. All metrics for this monitor instance will be deleted from the data mart

Response

202 - Monitoring disabled successfully

Trigger monitoring run

POST /v2/monitor_instances/{monitor_instance_id}/runs

Trigger monitoring run

Request

Request Body

MonitoringRunRequest

triggered_by

string

An identifier representing the source that triggered the run request (optional). One of: event, scheduler, user, webhook.

parameters

MonitorInstanceParameters

Monitoring parameters consistent with the `parameters_schema` from the monitor definition

expiration_date

string

The timestamp when the monitoring run was created with expiry date (in the format YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss.sssZ, matching the date-time format as specified by RFC 3339).

Response

201 - Monitoring run triggered

metadata

Metadata

entity

MonitoringRunEntity

List monitoring runs

GET /v2/monitor_instances/{monitor_instance_id}/runs

List monitoring runs

Request

Path Parameters

Query Parameters

start

string

The page token indicating where to start paging from.

limit

integer

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

Response

200 - Got history of monitoring runs

runs

array

A page from a collection of monitoring runs.

first

CollectionUrlModel

prev

CollectionUrlModel

next

CollectionUrlModel

last

CollectionUrlModel

limit

integer

The number of monitoring runs requested to be returned.

total_count

integer

The total number of monitoring runs available.

Get monitoring run details

GET /v2/monitor_instances/{monitor_instance_id}/runs/{monitoring_run_id}

Get monitoring run details

Request

Response

200 - Got monitoring run details

metadata

Metadata

entity

MonitoringRunEntity

Update existing monitoring run details

PATCH /v2/monitor_instances/{monitor_instance_id}/runs/{monitoring_run_id}

Update existing monitoring run details

Request

Request Body

Response

200 - Monitoring run updated successfully

metadata

Metadata

entity

MonitoringRunEntity

Publish measurement data to OpenScale

POST /v2/monitor_instances/{monitor_instance_id}/measurements

Publish measurement data to OpenScale

Request

Request Body

MonitorMeasurementRequestCollection

Response

202 - Asset observation registered successfully

Query measurements from OpenScale DataMart.

GET /v2/monitor_instances/{monitor_instance_id}/measurements

Query measurements from OpenScale DataMart. It is required to either provide a `start end` or `run_id` parameter.

Request

Path Parameters

Query Parameters

start

Required *

string

Beginning of the time range

end

Required *

string

End of the time range

run_id

string

Comma delimited list of measurement run_id

filter

string

Filter expression can consist of any metric tag or a common column of string type followed by filter name and optionally a value, all delimited by colon. Supported filters are: `in`, `eq`, `null` and `exists`. Sample filters are: `filter=region:in:[us,pl],segment:eq:sales` or `filter=region:null,segment:exists`.

limit

integer

Maximum number of measurements returned

offset

integer

Offset of measurements returned

Response

200 - Measurements data queried successfully. For measurement POSTed with v1, value of `issue_count` and `run_id` property will be `null`.

start

string

Beginning of the time range

end

string

End of the time range

limit

integer

Maximum number of measurements returned

offset

integer

Offset of measurements returned

measurements

array

Get measurement data from OpenScale DataMart.

GET /v2/monitor_instances/{monitor_instance_id}/measurements/{measurement_id}

Get measurement data from OpenScale DataMart. If metric_id is specified, sources associated with given metric id are filtered.

Request

Path Parameters

Query Parameters

metric_id

string

Comma delimited list of metric_id.

Response

200 - Measurement data retrieved successfully

metadata

Metadata

entity

object

Query for the recent measurement

GET /v2/measurements

Query for the recent measurement grouped by the monitoring target (subscription).

Request

Path Parameters

Query Parameters

target_id

Comma separated ID of the monitoring target (subscription)

target_type

Type of the monitoring target (subscription)

monitor_definition_id

Comma separated ID of the monitor definition

filter

string

Filter expression can consist of any metric tag or a common column of string type followed by filter name and optionally a value, all delimited by colon and prepended with `monitor_definition_id.` string. Supported filters are: `in`, `eq`, `null` and `exists`. Sample filters are: `monitor_definition_id.filter=region:in:[us,pl],monitor_definition_id.segment:eq:sales` or `filter=monitor_definition_id.region:null,monitor_definition_id.segment:exists`. Every monitor_definition_id can have own set of filters.

recent_count

integer

Number of measurements (per target) to be returned

format

string

Format of the returned data. `full` format compared to `compact` is additive and contains `sources` part.

Response

200 - Measurements data queried successfully

measurements

array

Query monitor instance metrics from OpenScale DataMart.

GET /v2/monitor_instances/{monitor_instance_id}/metrics

Query monitor instance metrics from OpenScale DataMart. See <a href="https://github.ibm.com/aiopenscale/aios-datamart-service-api/wiki/1.3.-Metrics-Query-Language">Metrics Query Language documentation</a>.

Request

Path Parameters

Query Parameters

start

Required *

string

Calculations inclusive, internally floored to achieve full interval. If interval is vulnerable to time zone, the calculated value depends on a backend db engine: PostgreSQL respects time zone and DB2 use UTC time. Calculated value is returned in response.

end

Required *

string

Calculations exclusive, internally ceiled to achieve full interval. If interval is vulnerable to time zone, the calculated value depends on a backend db engine: PostgreSQL respects time zone and DB2 use UTC time. Calculated value is returned in response.

interval

string

Time unit in which metrics are grouped and aggregated, interval by interval

filter

string

Filter expression can consist of any metric tag or a common column of string type followed by filter name and optionally a value, all delimited by colon. Supported filters are: `in`, `eq`, `null` and `exists`. Sample filters are: `filter=region:in:[us,pl],segment:eq:sales` or `filter=region:null,segment:exists`.

group

string

Comma delimited list constructed from metric tags, e.g. `group=region,segment` to group metrics before aggregations

agg

Required *

string

Comma delimited function list constructed from metric name and function, e.g. `agg=metric_name:count,:last` that defines aggregations

Response

200 - Metric data queried successfully

start

string

Floored to full interval

end

string

Ceiled to full interval

interval

string

monitor_definition_id

string

groups

array

Get User Preferences

GET /v2/user_preferences

Get User Preferences

Request

Response

200 - response

Update User Preferences

PATCH /v2/user_preferences

Update User Preferences

Request

Request Body

Response

200 - User Preferences updated successfully

Get a specific user preference

GET /v2/user_preferences/{user_preference_key}

Get a specific user preference

Request

Response

200 - response

Update the user preference

PUT /v2/user_preferences/{user_preference_key}

Update the user preference

Request

Request Body

Response

200 - key in User Preferences updated successfully

Delete the user preference

DELETE /v2/user_preferences/{user_preference_key}

Delete the user preference

Request

Response

204 - Deleted

List integrated systems

GET /v2/integrated_systems

List integrated systems

Request

Path Parameters

Query Parameters

type

comma-separated list of type for the integrated system

Response

200 - Integrated Systems returned successfully

integrated_systems

array

Create a new integrated system

POST /v2/integrated_systems

Create a new integrated system

Request

Request Body

IntegratedSystem

name

Required *

string

The name of the Integrated System.

type

Required *

string

description

Required *

string

The description of the Integrated System.

credentials

Required *

object

The credentials for the Integrated System

connection

object

The additional connection information for the Integrated System

group_ids

array

Access control list of group id of Cloud Pak for Data (Only available for open_pages type and OpenScale on Cloud Pak for Data >= 4.0.6 with ENABLE_GROUP_AUTH being true)

user_ids

array

Access control list of user id of Cloud Pak for Data (Only available for open_pages type and OpenScale on Cloud Pak for Data >= 4.0.6 with ENABLE_GROUP_AUTH being true)

parameters

object

Additional parameters

Response

201 - Integrated System successfully created.

metadata

Metadata

entity

IntegratedSystem

Integrated System definition

Get a specific integrated system

GET /v2/integrated_systems/{integrated_system_id}

Get a specific integrated system

Request

Response

200 - Integrated System details retrieved successfully

metadata

Metadata

entity

IntegratedSystem

Integrated System definition

Update an integrated system

PATCH /v2/integrated_systems/{integrated_system_id}

Update an integrated system

Request

Request Body

Response

200 - Integrated System updated successfully

metadata

Metadata

entity

IntegratedSystem

Integrated System definition

Delete an integrated system

DELETE /v2/integrated_systems/{integrated_system_id}

Delete an integrated system

Request

Response

204 - Integrated System deleted successfully.

List Operational Spaces

GET /v2/operational_spaces

List Operational Spaces

Request

Response

200 - Operational Spaces returned successfully

operational_spaces

array

Create an operational space

POST /v2/operational_spaces

Create an operational space

Request

Request Body

OperationalSpace

name

Required *

string

The name of the Operational Space.

description

string

The description of the Operational Space.

Response

201 - Operational Space successfully created.

metadata

Metadata

entity

OperationalSpace

Operational Space definition

Get an operational space

GET /v2/operational_spaces/{operational_space_id}

Get an operational space

Request

Response

200 - Operational Space details retrieved successfully

metadata

Metadata

entity

OperationalSpace

Operational Space definition

Update an operational space

PATCH /v2/operational_spaces/{operational_space_id}

Update an operational space

Request

Request Body

Response

200 - Operational Space updated successfully

metadata

Metadata

entity

OperationalSpace

Operational Space definition

Delete an operational space

DELETE /v2/operational_spaces/{operational_space_id}

Delete an operational space

Request

Response

204 - Operational Space deleted successfully.

Compute explanations

POST /v2/explanation_tasks

Submit tasks for computing explanation of predictions

Request

Request Body

ExplanationTaskRequest

scoring_ids

array

IDs of the scoring transaction

input_rows

array

List of scoring transactions

explanation_types

array

Types of explanations to generate

subscription_id

string

Unique subscription ID

Response

202 - Explanation request submitted successfully

metadata

PostExplanationTaskResponseMetadata

Metadata of post explanation tasks response

List all explanations

GET /v2/explanation_tasks

List of all the computed explanations

Request

Path Parameters

Query Parameters

subscription_id

Required *

Unique subscription ID

offset

integer

offset of the explanations to return

limit

integer

Maximum number of explanations to return

scoring_id

string

ID of the scoring transaction

status

string

Status of the explanation task

Response

200 - Explanations successfully retrieved

total_count

integer

Total number of computed explanations

limit

integer

Maximum number of returned explanations

offset

integer

Offset of returned explanations

explanation_fields

array

The list of explanation fields

explanation_values

array

The list of explanation values

Get explanation

GET /v2/explanation_tasks/{explanation_task_id}

Get explanation for the given explanation task id

Request

Response

200 - Explanation successfully retrieved

metadata

GetExplanationTaskResponseMetadata

Metadata of get explanation task response

entity

GetExplanationTaskResponseEntity

Entity of get explanation task response

Upload drift_v2 archive for a given subscription

PUT /v2/monitoring_services/drift_v2/archives

This API is used to upload the drift_v2 archive necessary to configure the Drift v2 monitor.

Request

Request Body

Path Parameters

Query Parameters

subscription_id

Required *

string

The id of the subscription.

archive_name

string

The name of the archive being uploaded.

Response

200 - The archive was uploaded successfully.

401 - The user is not authorized to perform the action.

500 - Internal server error.

Get drift v2 archive for a given subscription

GET /v2/monitoring_services/drift_v2/archives

This API is used to download the drift_v2 Archives.

Request

Path Parameters

Query Parameters

subscription_id

Required *

string

The id of the subscription.

archive_id

string

The id of the archive to be downloaded. It will download the latest baseline archive by default.

Response

200 - The archive was retrieved successfully.

401 - The user is not authorized to perform the action.

404 - The archive was not found.

500 - Internal server error.

Get drift archive metadata for a given subscription

HEAD /v2/monitoring_services/drift_v2/archives

Request

Path Parameters

Query Parameters

subscription_id

Required *

string

The id of the subscription.

archive_id

string

The id of the archive to be downloaded. It will download the latest baseline archive by default.

Response

200 - The archive was retrieved successfully.

401 - The user is not authorized to perform the action.

404 - The archive was not found.

500 - Internal server error.

Upload Drift archives.

POST /v2/monitoring_services/drift/data_marts/{data_mart_id}/subscriptions/{subscription_id}/archives

API to upload drift archive such as the Drift Detection Model.

Request

Request Body

Path Parameters

Query Parameters

archive_name

string

The name of the archive being uploaded.

enable_data_drift

boolean

Flag to enable/disable data drift.

enable_model_drift

boolean

Flag to enable/disable model drift.

Response

200 - The archive was uploaded successfully.

401 - The user is not authorized to perform the action.

500 - Internal server error.

Retrieves the Drift archives.

GET /v2/monitoring_services/drift/monitor_instances/{monitor_instance_id}/archives

API to retrieve the Drift archives.

Request

Response

200 - The archive was retrieved successfully.

401 - The user is not authorized to perform the action.

404 - The archive was not found.

500 - Internal server error.

Retrieves the Drift archive metadata.

HEAD /v2/monitoring_services/drift/monitor_instances/{monitor_instance_id}/archives

API to retrieve the Drift archive metadata.

Request

Response

200 - The archive metadata was retrieved successfully.

401 - The user is not authorized to perform the action.

404 - The archive metadata was not found.

500 - Internal server error.

Upload explainability configuration archive.

PUT /v2/monitoring_services/explainability/archives

API to upload explainability configuration archive containing the explainability artifacts. The api can also be used to update the archive.

Request

Request Body

Path Parameters

Query Parameters

subscription_id

Required *

Unique subscription ID

Response

200 - The archive was uploaded successfully.

401 - The user is not authorized to perform the action.

500 - Internal server error.

Upload explainability configuration archive.

POST /v2/monitoring_services/explainability/archives

API to upload explainability configuration archive containing the explainability artifacts. The api can also be used to update the archive.

Request

Request Body

Path Parameters

Query Parameters

subscription_id

Required *

Unique subscription ID

Response

200 - The archive was uploaded successfully.

401 - The user is not authorized to perform the action.

500 - Internal server error.

Download the Explainability configuration archive.

GET /v2/monitoring_services/explainability/archives

API to download the Explainability archive.

Request

Path Parameters

Query Parameters

subscription_id

Required *

Unique subscription ID

Response

200 - The archive was retrieved successfully.

401 - The user is not authorized to perform the action.

404 - The archive was not found.

500 - Internal server error.

Parse a given file and extract the schema in Spark StructType format.

POST /v2/spark_schemas

API to consume a file such as CSV and returns the schema in Spark StructType format.

Request

Request Body

Response

200 - The given file was successfully parsed.

type

string

fields

array

id

string

name

string

Uploads the test data and triggers a monitor run for risk evaluation.

POST /v2/monitoring_services/mrm/monitor_instances/{monitor_instance_id}/risk_evaluations

Uploads the test data and triggers a monitor run for risk evaluation.

Request

Request Body

Path Parameters

monitor_instance_id

Required *

string

The monitor instance ID.

Query Parameters

test_data_set_name

string

The name of the test CSV file being uploaded.

publish_metrics

string

Flag to decide whether to send evaluated metrics to OpenPages.

publish_lineage

string

Flag to decide whether a lineage event should be published to an integrated system.

publish_fact

string

Flag to decide whether Fact metadata should be published to an integrated system.

includes_model_output

string

Boolean flag to indicate whether the data being uploaded contains scored output or not.

delimiter

string

The delimiter to be used for CSV/Dynamic CSV files.

evaluation_tests

string

Comma separated list of monitor tests to run

Response

202 - Request accepted for risk evaluations.

evaluation_id

string

The unique ID for the MRM evaluation.

evaluation_date

string

The date time stamp in UTC ISO format for the MRM evaluation.

publish_metrics

string

Flag to decide whether to send evaluated metrics to OpenPages.

evaluation_tests

string

Comma separated list of monitor tests to run.

evaluation_start_time

string

Time stamp of the evaluation.

status

object

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Cancels the risk evaluations run.

PUT /v2/monitoring_services/mrm/monitor_instances/{monitor_instance_id}/risk_evaluations

Cancels the risk evaluations run.

Request

Request Body

PutRiskEvaluation

cancel_run

string

Path Parameters

monitor_instance_id

Required *

string

The monitor instance ID.

Query Parameters

Response

200 - Risk evaluation run canceled successfully.

metadata

object

entity

MonitoringRunEntity

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Returns the status of the risk evaluation.

GET /v2/monitoring_services/mrm/monitor_instances/{monitor_instance_id}/risk_evaluations

Returns the status of the risk evaluation.

Request

Path Parameters

monitor_instance_id

Required *

string

The monitor instance ID.

Query Parameters

Response

200 - Gets the latest risk evaluations runs detail.

metadata

object

entity

MonitoringRunEntity

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Publishes the chosen metrics to the integrated system reference.

PUT /v2/monitoring_services/mrm/monitor_instances/{monitor_instance_id}/runs/{monitoring_run_id}/integrated_system_metrics

Publishes the chosen metrics to the integrated system reference.

Request

Request Body

IntegratedSystemMetrics

metrics

array

send_report

boolean

Path Parameters

monitor_instance_id

Required *

string

The monitor instance ID.

monitoring_run_id

Required *

string

The monitoring run ID.

Query Parameters

Response

202 - Request to publish the chosen metrics to the integrated system reference accepted.

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Returns the risk evaluation report in a PDF format.

GET /v2/monitoring_services/mrm/monitor_instances/{monitor_instance_id}/runs/{monitoring_run_id}/risk_evaluation_report

Returns the risk evaluation report in a PDF format.

Request

Path Parameters

monitor_instance_id

Required *

string

The monitor instance ID.

monitoring_run_id

Required *

string

The monitoring run ID.

Query Parameters

Response

200 - Successfully returned the risk evaluation report in a PDF format.

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Returns the risk evaluation status of all subscriptions in a given service instance.

GET /v2/subscriptions/risk_evaluation_status

Returns the risk evaluation status of all subscriptions in a given service instance.

Request

Path Parameters

Query Parameters

data_mart_id

string

The data mart ID.

Response

200 - Successfully fetched the risk evaluation status.

risk_evaluation_status

array

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Updates the risk evaluation status for the given subscription.

PUT /v2/subscriptions/{subscription_id}/risk_evaluation_status

Updates the risk evaluation status for the given subscription.

Request

Request Body

MrmUpdateRiskEvaluationStatusEntity

state

string

Path Parameters

subscription_id

Required *

string

The subscription ID.

Query Parameters

Response

200 - Updated risk evaluation status of the subscription successfully.

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Gets risk evaluation status for the given subscription.

GET /v2/subscriptions/{subscription_id}/risk_evaluation_status

Gets risk evaluation status for the given subscription.

Request

Path Parameters

subscription_id

Required *

string

The subscription ID.

Query Parameters

Response

200 - Fetched risk evaluation status of the subscription successfully.

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Performs the setup activities in Openscale for a given prompt template asset.

POST /v2/prompt_setup

Performs the service provider creation, subscription creation and monitors configuration for the given prompt template asset.

Request

Request Body

PromptSetupRequest

label_column

Required *

string

The name of the column containing the ground truth or actual labels.

operational_space_id

Required *

string

The rank of the environment in which the monitoring is happening. Accepted values are `development`, `pre_production`, `production`.

problem_type

Required *

string

The task type to monitor for the given prompt template asset.

classification_type

string

The classification type `binary`/`multiclass` applicable only for `classification` problem (task) type.

input_data_type

Required *

string

The input data type.

context_fields

array

The list of prompt variables containing the context. Applicable only for Retrieval-Augmented Generation problem type.

question_field

string

The prompt variable containing the question. Applicable only for Retrieval-Augmented Generation problem type.

meta_fields

array

The list of meta-fields for the prompt.

monitors

object

monitor_definition_id

object

Path Parameters

Query Parameters

prompt_template_asset_id

Required *

The GUID of the prompt template asset.

project_id

The GUID of the project.

space_id

The GUID of the space.

deployment_id

The GUID of the deployment.

Response

202 - Prompt setup request accepted successfully.

prompt_template_asset_id

string

project_id

string

space_id

string

deployment_id

string

service_provider_id

string

subscription_id

string

mrm_monitor_instance_id

string

The MRM monitor instance ID.

start_time

string

The date-timestamp when the prompt setup was started.

end_time

string

The date-timestamp when the prompt setup ended.

status

PromptSetupResponseStatus

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Gets the status of the prompt setup for the given prompt template asset.

GET /v2/prompt_setup

Gets the status of the prompt setup for the given prompt template asset.

Request

Path Parameters

Query Parameters

prompt_template_asset_id

Required *

The GUID of the prompt template asset.

project_id

The GUID of the project.

space_id

The GUID of the space.

deployment_id

The GUID of the deployment.

Response

200 - The status of the prompt setup returned successfully.

prompt_template_asset_id

string

project_id

string

space_id

string

deployment_id

string

service_provider_id

string

subscription_id

string

mrm_monitor_instance_id

string

The MRM monitor instance ID.

start_time

string

The date-timestamp when the prompt setup was started.

end_time

string

The date-timestamp when the prompt setup ended.

status

PromptSetupResponseStatus

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Sets the users email notification preference in the MRM monitor instance of a given model subscription.

PUT /v2/monitoring_services/mrm/monitor_instances/{monitor_instance_id}/risk_notifications

Sets the users email notification preference in the MRM monitor instance of a given model subscription.

Request

Request Body

RiskNotificationPreferencesRequest

notification_enabled

boolean

notification_frequency

string

notification_emails

array

Path Parameters

monitor_instance_id

Required *

string

The monitor instance ID.

Query Parameters

Response

200 - Notification preferences updated successfully.

metadata

object

entity

object

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Gets the users email notification preferences for a given model subscription.

GET /v2/monitoring_services/mrm/monitor_instances/{monitor_instance_id}/risk_notifications

Gets the users email notification preferences for a given model subscription.

Request

Path Parameters

monitor_instance_id

Required *

string

The monitor instance ID.

Query Parameters

Response

200 - Notification preferences returned successfully.

metadata

object

entity

object

400 - Bad Request.

401 - Unauthorized.

500 - Internal Server Error.

Runs detections on a given input text.

POST /ml/v1/text/detection

Text Detection endpoint. Supports natural language inputs and returns the result of enabled detectors. You can specify any combination of HAP, PII, Prompt Safety Risk, topic relevance, Granite Guardian, Keyword and Regex detectors. Each detector is configurable independently and at least one detector is mandatory in the request.

Bring Your Own Risk (BYOR): The Granite Guardian detector supports custom risk definitions. When using BYOR, provide both `risk_name` (up to 50 characters) and `risk_definition` (up to 200 characters), both UTF-8 encoded.

Request

Request Body

TextDetectionContentRequest

input

Required *

string

The text to be examined.

detectors

Required *

TextDetectionContentDetectors

The detectors to use, these can be IBM provided `HAP` or `PII` detectors or a custom content detector.

hap

object

The definition of a `Hate and profanity` (HAP) text detector.

pii

object

The definition of a `Personal identifiable information` (PII) text detector.

topic_relevance

object

The definition of a `topic relevance` (off_topic) text detector.

prompt_safety_risk

object

The definition of two level prompt injection text detector.

granite_guardian

object

The definition of a `Granite Guardian` text detector.

Bring Your Own Risk (BYOR): You can define custom risks by providing both `risk_name` and `risk_definition`. When using BYOR, `risk_name` can be any custom string (up to 50 characters), and `risk_definition` must describe what the custom risk entails (up to 200 characters). Both must be UTF-8 encoded.

⚠️ Note: When using custom risks with BYOR, `threshold` is optional. The API response will include a warning stating: "For custom risks, it is the responsibility of the caller to test and validate response accuracy."

keyword

object

The definition of a `keyword` text detector.

regex

object

The definition of a `regex` text detector.

Path Parameters

Query Parameters

Response

200 - success.

detections

array

The text that was detected.

warnings

array

Warning messages related to the detection request. This field is included when using custom risks with BYOR in Granite Guardian.

400 - Bad request, the response body should contain the reason.

trace

string

An identifier that can be used to trace the request.

errors

array

The list of errors.

401 - Unauthorized.

trace

string

An identifier that can be used to trace the request.

status_code

integer

errors

array

The list of errors.

403 - Forbidden, an authentication error including trying to access an unauthorized watsonx.gov service instance.

404 - The specified resource was not found.

500 - Internal Server Error.

trace

string

An identifier that can be used to trace the request.

status_code

integer

errors

array

The list of errors.

Detection task on input content based on context documents.

POST /ml/v1/text/detection/context

This operation supports `context relevance` and `faithfulness` (or `groundedness`). The `input` is analyzed, along with the context information, and the model will return any detections that it found.

Request

Request Body

TextDetectionContextRequest

From a content, detect text using a detection model.

input

Required *

string

The text to be examined.

detectors

Required *

TextDetectionContextDetectors

The detectors to use, `context_relevance` and `faithfulness` is supported.

⚠️ Deprecated Feature Warning `granite_guardian` is deprecated and will be removed in the future releases.

granite_guardian

object

The definition of a `Granite Guardian` text detector.

context_relevance

object

The definition of `context relevance` text detector.

faithfulness

object

The definition of `faithfulness`(or `groundedness`) text detector.

context_type

Required *

string

The type of the context.

context

Required *

object

Context documents.

Response

200 - Successful operation

detections

array

The text that was detected.

400 - Bad request, the response body should contain the reason.

trace

string

An identifier that can be used to trace the request.

errors

array

The list of errors.

401 - Unauthorized.

trace

string

An identifier that can be used to trace the request.

status_code

integer

errors

array

The list of errors.

403 - Forbidden, an authentication error including trying to access an unauthorized watsonx.gov service instance.

404 - The specified resource was not found.

500 - Internal Server Error.

Detection task performing detection on prompt and generated text.

POST /ml/v1/text/detection/generated

This operation supports `answer relevance`. The `prompt` is analyzed along with the `generated text` and the model will return any detections that it found.

Request

Request Body

TextDetectionGeneratedRequest

From a content, detect text using a detection model.

prompt

Required *

string

The text prompt.

generated_text

Required *

string

The generated text.

detectors

Required *

TextDetectionGeneratedDetectors

The detectors to use, only `answer_relevance` is supported.

⚠️ Deprecated Feature Warning `granite_guardian` is deprecated and will be removed in the future releases.

granite_guardian

object

The definition of a `Granite Guardian` text detector.

answer_relevance

object

The definition of `answer_relevance` text detector.

Response

200 - Successful operation

detections

array

The text that was detected.\n

400 - Bad request, the response body should contain the reason.

trace

string

An identifier that can be used to trace the request.

errors

array

The list of errors.

401 - Unauthorized.

trace

string

An identifier that can be used to trace the request.

status_code

integer

errors

array

The list of errors.

403 - Forbidden, an authentication error including trying to access an unauthorized watsonx.gov service instance.

404 - The specified resource was not found.

500 - Internal Server Error.

Detection task performing function calling hallucination detection.

POST /ml/v1/text/detection/chat

This operation supports `function calling hallucination`. The `input` is analyzed along with the `messages` and `tools` and the model will return any detections that it found with respect to the tool calls made.

Request

Request Body

TextDetectionChatRequest

From a content, detect text using a detection model.

messages

array

tools

array

Tool functions that may be invoked.

detectors

TextDetectionChatDetectors

The detectors to use, only granite_guardian is supported.

granite_guardian

object

The definition of a `Granite Guardian` text detector.

Response

200 - Successful operation

detections

array

The text that was detected.\n

400 - Bad request, the response body should contain the reason.

trace

string

An identifier that can be used to trace the request.

errors

array

The list of errors.

401 - Unauthorized.

trace

string

An identifier that can be used to trace the request.

status_code

integer

errors

array

The list of errors.

403 - Forbidden, an authentication error including trying to access an unauthorized watsonx.gov service instance.

404 - The specified resource was not found.

500 - Internal Server Error.

Get all detectors

GET /guardrails_manager/v2/detectors

Retrieves all detectors including both built-in detectors (from detector_template.json) and custom detectors (from CAMs)

Request

Response

200 - Successfully retrieved all detectors

detectors

array

List of built-in detectors from detector_template.json

custom_detectors

array

List of custom detectors from CAMs

401 - Unauthorized - Authentication required

403 - Forbidden - User doesn't have permission to view detectors

500 - Internal server error

Create a detector

POST /guardrails_manager/v2/detectors

Creates a new detector with custom endpoint URL and configuration.

Request

Request Body

CreateDetectorRequest

name

Required *

string

Name of the detector

description

string

Description of the detector

url

Required *

string

URL endpoint for the detector

auth_method

Required *

string

Authentication method for the detector endpoint

direction

Required *

array

Direction(s) where the detector applies (input, output, or both)

detector_properties

array

Configurable properties for the detector

parameters

array

Parameters that can be passed to the detector

Path Parameters

Query Parameters

inventory_id

Required *

string

CAMS inventory ID (UUID format)

Response

201 - Detector created successfully

entity

Detector

A detector (either built-in or custom)

metadata

object

Metadata about the detector (empty for built-in detectors, populated for custom detectors)

400 - Bad request - Invalid input or validation error

401 - Unauthorized - Authentication required

403 - Forbidden - User doesn't have permission to create detectors

500 - Internal server error

Get a detector by ID

GET /guardrails_manager/v2/detectors/{id}

Retrieves a specific custom detector by its ID

Request

Path Parameters

id

Required *

string

The UUID of the detector to retrieve

Query Parameters

inventory_id

Required *

string

CAMS inventory ID (UUID format)

Response

200 - Detector retrieved successfully

entity

Detector

A detector (either built-in or custom)

metadata

object

Metadata about the detector (empty for built-in detectors, populated for custom detectors)

400 - Bad request - Invalid input or validation error

401 - Unauthorized - Authentication required

403 - Forbidden - User doesn't have permission to view detectors

404 - Detector not found

500 - Internal server error

Delete a detector

DELETE /guardrails_manager/v2/detectors/{id}

Deletes a custom detector by its unique identifier

Request

Path Parameters

id

Required *

string

The UUID of the detector to delete

Query Parameters

inventory_id

Required *

string

CAMS inventory ID (UUID format)

Response

204 - Detector deleted successfully (no content)

400 - Bad request - Invalid detector ID

401 - Unauthorized - Authentication required

403 - Forbidden - User doesn't have permission to delete this detector

404 - Detector not found

500 - Internal server error

Enforce a policy

POST /guardrails_manager/v2/enforce/{id}

Executes a policy by ID to detect and apply actions on the provided text based on configured detectors

Request

Request Body

EnforceRequest

text

Required *

string

The text content to be analyzed by the policy detectors

direction

Required *

string

Direction of the text flow (input or output)

detectors_properties

Required *

object

Optional properties for detectors, keyed by detector name

Path Parameters

id

Required *

string

The UUID of the policy to enforce

Query Parameters

inventory_id

Required *

string

CAMS inventory ID (UUID format)

Response

200 - Policy enforced successfully

entity

EnforceResponseEntity

Entity containing the enforcement results

metadata

object

Metadata about the enforcement

400 - Bad request - Invalid input or validation error

401 - Unauthorized - Authentication required

403 - Forbidden - User doesn't have permission to enforce policies

404 - Policy not found

500 - Internal server error

Get all policies

GET /guardrails_manager/v2/policies

Retrieves a list of all policies with optional search and filtering by policy type

Request

Path Parameters

Query Parameters

inventory_id

Required *

string

CAMS inventory ID (UUID format)

policytype

Required *

string

Filter policies by type (publish for active, draft for inactive)

string

Search term to filter policies by name or description

Response

200 - Policies retrieved successfully

policies

array

List of policies

400 - Bad request - Invalid query parameters

401 - Unauthorized - Authentication required

403 - Forbidden - User doesn't have permission to view policies

500 - Internal server error

Create a policy

POST /guardrails_manager/v2/policies

Creates a new policy with detector and action configurations for input and output directions

Request

Request Body

PolicyResponsePrototype

name

Required *

string

Name of the policy

description

string

Description of the policy

block_message

string

Message to display when content is blocked

mask_character

string

Character to use for masking (e.g., "*")

input

Required *

array

Detector configurations for input direction

output

Required *

array

Detector configurations for output direction

policy_status

Required *

string

Status of the policy (publish for active, draft for inactive)

tags

array

Tags for categorizing the policy

Path Parameters

Query Parameters

inventory_id

Required *

string

CAMS inventory ID (UUID format)

Response

201 - Policy created successfully

entity

PolicyEntity

Policy entity containing all policy details

metadata

PolicyMetadata

Metadata about the policy

400 - Bad request - Invalid input or validation error

401 - Unauthorized - Authentication required

403 - Forbidden - User doesn't have permission to create policies

500 - Internal server error

Get a policy by ID

GET /guardrails_manager/v2/policies/{id}

Retrieves a specific policy by its unique identifier

Request

Path Parameters

id

Required *

string

Unique identifier for the policy (UUID format)

Query Parameters

inventory_id

Required *

string

CAMS inventory ID (UUID format)

Response

200 - Policy retrieved successfully

entity

PolicyEntity

Policy entity containing all policy details

metadata

PolicyMetadata

Metadata about the policy

400 - Bad request - Invalid input or validation error

401 - Unauthorized - Authentication required

403 - Forbidden - User doesn't have permission to view this policy

404 - Policy not found

500 - Internal server error

Update a policy

PUT /guardrails_manager/v2/policies/{id}

Updates an existing policy with new detector and action configurations

Request

Request Body

PolicyResponsePrototype

name

Required *

string

Name of the policy

description

string

Description of the policy

block_message

string

Message to display when content is blocked

mask_character

string

Character to use for masking (e.g., "*")

input

Required *

array

Detector configurations for input direction

output

Required *

array

Detector configurations for output direction

policy_status

Required *

string

Status of the policy (publish for active, draft for inactive)

tags

array

Tags for categorizing the policy

Path Parameters

id

Required *

string

Unique identifier for the policy (UUID format)

Query Parameters

inventory_id

Required *

string

CAMS inventory ID (UUID format)

Response

200 - Policy updated successfully

entity

PolicyEntity

Policy entity containing all policy details

metadata

PolicyMetadata

Metadata about the policy

400 - Bad request - Invalid input or validation error

401 - Unauthorized - Authentication required

403 - Forbidden - User doesn't have permission to update this policy

404 - Policy not found

500 - Internal server error

Delete a policy

DELETE /guardrails_manager/v2/policies/{id}

Deletes a policy by its unique identifier

Request

Path Parameters

id

Required *

string

Unique identifier for the policy (UUID format)

Query Parameters

inventory_id

Required *

string

CAMS inventory ID (UUID format)

Response

204 - Policy deleted successfully (no content)

400 - Bad request - Invalid policy ID

401 - Unauthorized - Authentication required

403 - Forbidden - User doesn't have permission to delete this policy

404 - Policy not found

500 - Internal server error

Get policy history

GET /guardrails_manager/v2/policies/{id}/history

Retrieves the full revision history of a policy, showing how its detector configurations, actions, and status have changed over time

Request

Path Parameters

id

Required *

string

Unique identifier for the policy (UUID format)

Query Parameters

inventory_id

Required *

string

CAMS inventory ID (UUID format)

Response

200 - Policy history retrieved successfully

history

array

Ordered list of history events, oldest first

400 - Bad request - Invalid policy ID or query parameters

401 - Unauthorized - Authentication required

403 - Forbidden - User doesn't have permission to view this policy's history

404 - Policy not found

500 - Internal server error