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
header
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.
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)
search
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