{ "openapi":"3.0.0", "info":{ "title":"REST API Reference for AI Services", "version":"2026.10.29", "description":"The REST API for AI and ML services allow you to create data sources, train models based on the configured data sources, and make predictions based on a customer's usage pattern. You use these APIs for applying and configuring different services.", "x-summary":"The REST API for AI and ML services allow you to create data sources, train models based on the configured data sources, and make predictions based on a customer's usage pattern." }, "paths":{ "/data/collect":{ "post":{ "tags":[ "Data Collection and Management" ], "summary":"Collect Data from Source", "description":"Collects data from your data source, such as a database, and stores it in an object file.", "operationId":"collectData", "requestBody":{ "$ref":"#/components/requestBodies/CollectRequest" }, "responses":{ "200":{ "$ref":"#/components/responses/200_CollectResponse" }, "400":{ "$ref":"#/components/responses/400" }, "401":{ "$ref":"#/components/responses/401" }, "403":{ "$ref":"#/components/responses/403" }, "404":{ "$ref":"#/components/responses/404" }, "405":{ "$ref":"#/components/responses/405" }, "409":{ "$ref":"#/components/responses/409" }, "500":{ "$ref":"#/components/responses/500" }, "501":{ "$ref":"#/components/responses/501" }, "503":{ "$ref":"#/components/responses/503" } }, "x-internal-id":"data-collect-post", "x-filename-id":"data-collect-post" } }, "/data/fetch":{ "post":{ "tags":[ "Data Collection and Management" ], "summary":"Fetch Data from Cache", "description":"Retrieves the specified data from your data set and sends it to the client.", "operationId":"fetchData", "requestBody":{ "$ref":"#/components/requestBodies/FetchRequest" }, "responses":{ "200":{ "$ref":"#/components/responses/200_FetchResponse" }, "400":{ "$ref":"#/components/responses/400" }, "401":{ "$ref":"#/components/responses/401" }, "403":{ "$ref":"#/components/responses/403" }, "404":{ "$ref":"#/components/responses/404" }, "405":{ "$ref":"#/components/responses/405" }, "409":{ "$ref":"#/components/responses/409" }, "500":{ "$ref":"#/components/responses/500" }, "501":{ "$ref":"#/components/responses/501" }, "503":{ "$ref":"#/components/responses/503" } }, "x-internal-id":"data-fetch-post", "x-filename-id":"data-fetch-post" } }, "/data/cache":{ "post":{ "tags":[ "Data Collection and Management" ], "summary":"Cache Persisted Data", "description":"Caches the specified data for use when required.

In the request body, the contents of additional_data depend on the storage_type value:

", "operationId":"cacheData", "requestBody":{ "$ref":"#/components/requestBodies/CacheRequest" }, "responses":{ "200":{ "$ref":"#/components/responses/200_CacheResponse" }, "400":{ "$ref":"#/components/responses/400" }, "401":{ "$ref":"#/components/responses/401" }, "403":{ "$ref":"#/components/responses/403" }, "404":{ "$ref":"#/components/responses/404" }, "405":{ "$ref":"#/components/responses/405" }, "409":{ "$ref":"#/components/responses/409" }, "500":{ "$ref":"#/components/responses/500" }, "501":{ "$ref":"#/components/responses/501" }, "503":{ "$ref":"#/components/responses/503" } }, "x-internal-id":"data-cache-post", "x-filename-id":"data-cache-post" } }, "/utility/train":{ "post":{ "tags":[ "Model Training" ], "summary":"Train the Model", "description":"Trains the model based on the configurations set by you and the data acquired by the data service.

In the request body, the contents of additional_data depend on the storage_type value:

", "operationId":"trainModel", "requestBody":{ "$ref":"#/components/requestBodies/TrainRequest" }, "responses":{ "200":{ "$ref":"#/components/responses/200_TrainResponse" }, "400":{ "$ref":"#/components/responses/400" }, "401":{ "$ref":"#/components/responses/401" }, "403":{ "$ref":"#/components/responses/403" }, "404":{ "$ref":"#/components/responses/404" }, "405":{ "$ref":"#/components/responses/405" }, "409":{ "$ref":"#/components/responses/409" }, "500":{ "$ref":"#/components/responses/500" }, "501":{ "$ref":"#/components/responses/501" }, "503":{ "$ref":"#/components/responses/503" } }, "x-internal-id":"utility-train-post", "x-filename-id":"utility-train-post" } }, "/health":{ "get":{ "tags":[ "Billing Agent" ], "summary":"Get Service Health", "operationId":"getHealth", "responses":{ "200":{ "description":"The request was completed successfully. If the system throws a runtime error, the response code 200 is returned alongside the error message in the response body.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/HealthResponse" }, "example":{ "status":"ok", "mcp_url_configured":true, "idcs_enabled":false } } } } }, "description":"The endpoint returns the service's liveness status and indicates whether the deployment configures the MCP URL and enables IDCS authentication.", "x-internal-id":"health-get", "x-filename-id":"health-get" } }, "/ready":{ "get":{ "tags":[ "Billing Agent" ], "summary":"Get Service Readiness", "operationId":"getReadiness", "responses":{ "200":{ "description":"The request was completed successfully. If the system throws a runtime error, the response code 200 is returned alongside the error message in the response body.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ReadyResponse" } } } }, "503":{ "$ref":"#/components/responses/Starting" } }, "description":"The endpoint returns the service's readiness status after application startup completes.", "x-internal-id":"ready-get", "x-filename-id":"ready-get" } }, "/capabilities":{ "get":{ "tags":[ "Billing Agent" ], "summary":"Get Supported Billing Capabilities", "operationId":"getCapabilities", "responses":{ "200":{ "description":"The request was completed successfully. If the system throws a runtime error, the response code 200 is returned alongside the error message in the response body.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/CapabilitiesResponse" } } } } }, "description":"The endpoint returns the supported billing capabilities, MCP tools and resources, and guardrails.", "x-internal-id":"capabilities-get", "x-filename-id":"capabilities-get" } }, "/invoke/chat":{ "post":{ "tags":[ "Billing Agent" ], "summary":"Submit a Billing Care Chat Request", "description":"The endpoint submits a Billing Care chat request through the hosted integration route. The /chat endpoint provides an equivalent compatibility alias.", "operationId":"invokeChat", "parameters":[ { "$ref":"#/components/parameters/SessionId" } ], "security":[ { }, { "bearerAuth":[ ] } ], "requestBody":{ "required":true, "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ChatRequest" }, "example":{ "message":"Show my latest bill.", "account_id":"0.0.0.1+-account+12345" } } } }, "responses":{ "200":{ "$ref":"#/components/responses/ChatResult" }, "401":{ "$ref":"#/components/responses/Unauthorized" }, "422":{ "$ref":"#/components/responses/ValidationError" }, "502":{ "$ref":"#/components/responses/UpstreamFailure" }, "503":{ "$ref":"#/components/responses/ServiceUnavailable" } }, "x-internal-id":"invoke-chat-post", "x-filename-id":"invoke-chat-post" } }, "/chat":{ "post":{ "tags":[ "Billing Agent" ], "summary":"Submit a Billing Care Chat Request (Compatibility Alias)", "description":"The endpoint submits a Billing Care chat request through the compatibility route. The /invoke/chat endpoint provides equivalent functionality.", "operationId":"chat", "parameters":[ { "$ref":"#/components/parameters/SessionId" } ], "security":[ { }, { "bearerAuth":[ ] } ], "requestBody":{ "required":true, "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ChatRequest" } } } }, "responses":{ "200":{ "$ref":"#/components/responses/ChatResult" }, "401":{ "$ref":"#/components/responses/Unauthorized" }, "422":{ "$ref":"#/components/responses/ValidationError" }, "502":{ "$ref":"#/components/responses/UpstreamFailure" }, "503":{ "$ref":"#/components/responses/ServiceUnavailable" } }, "x-internal-id":"chat-post", "x-filename-id":"chat-post" } }, "/utility/predict":{ "post":{ "tags":[ "Prediction Service" ], "summary":"Get Predictions", "description":"Creates a prediction for an account using the specified algorithm.", "operationId":"predictService", "requestBody":{ "$ref":"#/components/requestBodies/PredictRequest" }, "responses":{ "200":{ "$ref":"#/components/responses/200_PredictResponse" }, "400":{ "$ref":"#/components/responses/400" }, "401":{ "$ref":"#/components/responses/401" }, "403":{ "$ref":"#/components/responses/403" }, "404":{ "$ref":"#/components/responses/404" }, "405":{ "$ref":"#/components/responses/405" }, "409":{ "$ref":"#/components/responses/409" }, "500":{ "$ref":"#/components/responses/500" }, "501":{ "$ref":"#/components/responses/501" }, "503":{ "$ref":"#/components/responses/503" } }, "x-mcp":{ "tool":{ "name":"predict-service", "display-name":"Predict Service", "description":"Generate predictions from requested model names for account_id or msisdn", "category":"read", "confirmation":{ "required":false }, "safety":{ "dangerous":false, "reversible":true, "impact":"low" } } }, "x-internal-id":"utility-predict-post", "x-filename-id":"utility-predict-post" } } }, "components":{ "schemas":{ "CacheRequest":{ "description":"Input request parameters", "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Specifies the input parameters for the request.", "required":[ "required_data", "storage_type" ], "properties":{ "required_data":{ "description":"Specifies the data to retrieve.", "type":"array", "items":{ "type":"string" } }, "storage_type":{ "description":"Specifies the type of storage that contains the data.", "type":"string" }, "additional_data":{ "description":"Provides additional criteria used to filter the data.", "type":"object" } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "CacheRequest":"#/components/schemas/CacheRequest" } } }, "FetchRequest":{ "description":"Input request parameters", "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "required":[ "required_data" ], "properties":{ "required_data":{ "description":"Specifies the data to retrieve.", "type":"array", "items":{ "type":"string" } }, "additional_data":{ "description":"Provides additional criteria used to filter the data.", "type":"object" } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "FetchRequest":"#/components/schemas/FetchRequest" } } }, "CollectRequest":{ "description":"Input request parameters", "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Specifies the input parameters for the request.", "required":[ "data_source_type", "query_builder", "tech_choice", "delta_data" ], "properties":{ "data_source_type":{ "description":"Specifies the list of data sources.", "type":"array", "items":{ "type":"string" } }, "query_builder":{ "description":"Specifies the list of queries and their join conditions.", "type":"object", "items":{ "$ref":"#/components/schemas/QueryBuilder" } }, "storage_details":{ "description":"Specifies the data storage location and connection details.", "type":"object", "items":{ "$ref":"#/components/schemas/StorageDetails" } }, "tech_choice":{ "description":"Specifies the third-party library to use for data collection - spark, dataflow, or datascience.", "type":"string" }, "delta_data":{ "description":"Indicates whether newly fetched data should be appended to existing data. Set this to true if you need to append the training data. Set this to false if you want to fetch complete data without appending anything.", "type":"boolean", "enum":[ true, false ] } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "CollectRequest":"#/components/schemas/CollectRequest" } } }, "QueryBuilder":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Specifies the queries and their join conditions.", "required":[ "queries" ], "properties":{ "queries":{ "description":"Specifies the list of queries.", "type":"array", "items":{ "$ref":"#/components/schemas/QueryList" } }, "join_condition":{ "description":"Specifies the join conditions used to construct the queries. This is an optional input which can be used to join the data from two queries.", "type":"array", "items":{ "$ref":"#/components/schemas/JoinConditions" } } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "QueryBuilder":"#/components/schemas/QueryBuilder" } } }, "QueryList":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Specifies the list of queries to run.", "required":[ "name", "query" ], "properties":{ "name":{ "description":"Specifies the query name, which serves as a unique identifier.", "type":"string" }, "query":{ "description":"Specifies the query to run.", "type":"string" } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "QueryList":"#/components/schemas/QueryList" } } }, "JoinConditions":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"List of join conditions used to combine queries.", "required":[ "name", "join" ], "properties":{ "name":{ "description":"Specifies the query name, which serves as a unique identifier.", "type":"string" }, "join":{ "description":"Specifies the names of the queries to join.", "type":"array", "items":{ "type":"string" } }, "join_type":{ "description":"Specifies the join type to use instead of the default (natural join).", "type":"string" }, "join_column":{ "description":"Specifies the column used to join the queries.", "type":"array", "items":{ "type":"string" } } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "JoinConditions":"#/components/schemas/JoinConditions" } } }, "StorageDetails":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Specifies the storage location and connection details.", "required":[ "output_file_type" ], "properties":{ "path":{ "description":"Specifies the storage path where the data is saved.", "type":"string" }, "output_file_type":{ "description":"Specifies the file type to use when storing the data: json, csv, or pickle.", "type":"string" }, "storage_type":{ "description":"Specifies the type of storage to use: pvc or object_storage.", "type":"string" }, "storage_connection_details":{ "description":"Specifies the connection parameters for the storage location.", "type":"array", "items":{ "type":"object" } } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "StorageDetails":"#/components/schemas/StorageDetails" } } }, "CollectResponse":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Specifies the output returned by the operation.", "required":[ "status" ], "properties":{ "status":{ "description":"Indicates the status of the data being fetched from the data source.", "type":"string" } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "CollectResponse":"#/components/schemas/CollectResponse" } } }, "FetchResponse":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Specifies the output returned by the operation.", "required":[ "data" ], "properties":{ "data":{ "description":"Returns the data retrieved from storage.", "type":"object" } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "FetchResponse":"#/components/schemas/FetchResponse" } } }, "CacheResponse":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Specifies the output returned by the operation.", "required":[ "status" ], "properties":{ "status":{ "description":"Indicates the current status of the service.", "type":"string" } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "CacheResponse":"#/components/schemas/CacheResponse" } } }, "Extensible":{ "type":"object", "description":"Base extensible schema for use with TM Forum Open APIs. When used in a schema, the entity must be extended by specifying `@type`.", "properties":{ "@type":{ "type":"string", "description":"When subclassing, specifies the extensible name of the subclass." }, "@baseType":{ "type":"string", "description":"Specifies the superclass while subclassing." }, "@schemaLocation":{ "type":"string", "description":"Provides a URI to the JSON Schema file that defines additional attributes and relationships." } }, "required":[ "@type" ] }, "Error":{ "discriminator":{ "propertyName":"@type", "mapping":{ "Error":"#/components/schemas/Error" } }, "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Indicates an error response from the API, usually accompanied by an HTTP status code (3xx, 4xx, or 5xx).", "required":[ "code", "reason" ], "properties":{ "code":{ "type":"string", "description":"Provides application-specific details, as defined by the API or a common list." }, "reason":{ "type":"string", "description":"Provides an explanation of the error to display to the client user." }, "message":{ "type":"string", "description":"Provides additional error details and recommended corrective actions to display to the client user." }, "status":{ "type":"string", "description":"Specifies the extended HTTP error code." }, "referenceError":{ "type":"string", "description":"Provides a URI to documentation that describes the error." } } } ], "description":"Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)" }, "TrainRequest":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Specifies the input parameters for the request.", "required":[ "algorithm", "storage_details", "sample" ], "properties":{ "algorithm":{ "type":"array", "description":"Specifies the list of algorithms to train.", "items":{ "$ref":"#/components/schemas/Algorithms" } }, "storage_details":{ "type":"array", "description":"Provides the storage location and access details for the stored data.", "items":{ "$ref":"#/components/schemas/StorageDetails" } }, "sample":{ "type":"boolean", "description":"Indicates whether to apply sample preprocessing. Set this to true to use the default preprocessing script. Set this to false to use the sample script specified in the trainUtilityProcessor.preprocessScript key of your values.yaml file.", "enum":[ true, false ] } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "TrainRequest":"#/components/schemas/TrainRequest" } } }, "Algorithms":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Defines an algorithm and its training configuration.", "required":[ "algo", "model_dir", "model_name" ], "properties":{ "algo":{ "type":"string", "description":"Specifies the algorithm name.", "enum":[ "knn", "dnn", "cosine", "dnn_mh", "xgboost" ] }, "model_dir":{ "type":"string", "description":"Specifies the path to store the model files. This field accepts only alphanumeric and underscore (_) characters." }, "model_name":{ "type":"string", "description":"Specifies the name under which the model is stored." }, "hyper_parameters":{ "type":"object", "description":"Specifies hyperparameters to override the default values. Available parameters vary by algorithm." } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "Algorithms":"#/components/schemas/Algorithms" } } }, "TrainResponse":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Specifies the output returned by the operation.", "required":[ "status" ], "properties":{ "status":{ "type":"string", "description":"Indicates the current status of the service." } } } ], "discriminator":{ "propertyName":"@type", "mapping":{ "TrainResponse":"#/components/schemas/TrainResponse" } } }, "ChatRequest":{ "type":"object", "required":[ "message" ], "properties":{ "message":{ "type":"string", "minLength":1, "description":"Specifies the customer's billing or payment question." }, "session_id":{ "type":[ "string", "null" ], "description":"Specifies the optional session ID. The X-Session-Id header takes precedence when the request supplies it." }, "account_id":{ "type":[ "string", "null" ], "description":"Specifies the optional Billing Care account reference or POID." }, "previous_messages":{ "type":[ "array", "null" ], "description":"Specifies the optional conversation history.", "items":{ "$ref":"#/components/schemas/PreviousMessage" } }, "conversation_messages":{ "type":[ "array", "null" ], "description":"Specifies the optional legacy conversation history as [role, content] pairs.", "items":{ "type":"array", "minItems":2, "maxItems":2, "prefixItems":[ { "type":"string" }, { "type":"string" } ] } }, "operation_payload":{ "type":[ "object", "null" ], "additionalProperties":true, "description":"The service accepts this field for compatibility. The API does not support write operations." }, "confirmed":{ "type":"boolean", "default":false, "description":"The service accepts this field for compatibility. The API does not support write operations." }, "user_role":{ "type":"string", "default":"customer", "description":"The service accepts this field for compatibility." } } }, "PreviousMessage":{ "type":"object", "required":[ "role", "content" ], "properties":{ "role":{ "type":"string", "minLength":1, "example":"user" }, "content":{ "type":"string", "minLength":1, "example":"What was my previous bill?" } } }, "ChatResponse":{ "type":"object", "required":[ "status", "response_text", "session_id" ], "properties":{ "status":{ "type":"string", "enum":[ "ok", "error" ] }, "agent":{ "type":"string", "example":"billing_care_agent" }, "intent":{ "type":"string", "description":"Specifies the intent that the service returns in certain validation responses." }, "response_format":{ "type":"string", "enum":[ "string", "list", "table" ] }, "response_text":{ "type":"string", "description":"Specifies the customer-facing answer, which always ends with the AI-generated-response disclosure." }, "follow_up_questions":{ "type":"array", "items":{ "type":"string" } }, "account_id":{ "type":"string", "description":"Specifies the account's display ID when the service resolves an account." }, "requested_account_id":{ "type":"string", "description":"Specifies the account reference that the service uses to process the request." }, "session_id":{ "type":"string" } } }, "HealthResponse":{ "type":"object", "required":[ "status", "mcp_url_configured", "idcs_enabled" ], "properties":{ "status":{ "type":"string", "const":"ok" }, "mcp_url_configured":{ "type":"boolean" }, "idcs_enabled":{ "type":"boolean" } } }, "ReadyResponse":{ "type":"object", "required":[ "status", "mcp_url_configured", "agent_initialized", "idcs_enabled" ], "properties":{ "status":{ "type":"string", "const":"ready" }, "mcp_url_configured":{ "type":"boolean" }, "agent_initialized":{ "type":"boolean" }, "idcs_enabled":{ "type":"boolean" } } }, "CapabilitiesResponse":{ "type":"object", "required":[ "supported_intents", "supported_usecases", "read_only_mcp_tools", "read_only_mcp_resources", "guardrails" ], "properties":{ "invoice_alias":{ "type":[ "string", "null" ] }, "invoice_status":{ "type":"string" }, "supported_intents":{ "type":"array", "items":{ "type":"string" } }, "supported_usecases":{ "type":"array", "items":{ "type":"string" } }, "controlled_write_intents":{ "type":"array", "items":{ "type":"string" } }, "read_only_mcp_tools":{ "type":"array", "items":{ "type":"string" } }, "read_only_mcp_resources":{ "type":"array", "items":{ "type":"string" } }, "blocked_mcp_tools":{ "type":"string" }, "guardrails":{ "type":"array", "items":{ "type":"string" } } } }, "ErrorResponse":{ "type":"object", "required":[ "detail" ], "properties":{ "detail":{ "type":"string" } } }, "ValidationErrorResponse":{ "type":"object", "required":[ "detail" ], "properties":{ "detail":{ "type":"array", "items":{ "type":"object", "required":[ "loc", "msg", "type" ], "properties":{ "loc":{ "type":"array", "items":{ "oneOf":[ { "type":"string" }, { "type":"integer" } ] } }, "msg":{ "type":"string" }, "type":{ "type":"string" } } } } } }, "PredictRequest":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Specifies the input parameters for the request.", "properties":{ "account_id":{ "description":"Specifies the customer account ID.", "type":"string" }, "msisdn":{ "description":"Specifies the customer's MSISDN.", "type":"string" }, "model_names":{ "description":"Lists the algorithms to use for the prediction service - knn, dnn, or cosine.", "type":"array", "items":{ "type":"string" } } }, "required":[ "model_names" ] } ], "additionalProperties":true }, "PredictResponse":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Returns the result output.", "required":[ "status", "predictions" ], "properties":{ "status":{ "description":"Indicates the current status of the service.", "type":"string" }, "predictions":{ "description":"Recommendations returned by each algorithm.", "type":"array", "items":{ "$ref":"#/components/schemas/PredictionDetails" } } }, "additionalProperties":true } ], "additionalProperties":true, "discriminator":{ "propertyName":"@type", "mapping":{ "PredictResponse":"#/components/schemas/PredictResponse" } } }, "PredictionDetails":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Provides the details for a recommendation.", "required":[ "top_results" ], "properties":{ "algorithm":{ "description":"Specifies the algorithm used to generate the recommendation.", "type":"string" }, "top_results":{ "description":"Lists the recommendation results.", "type":"array", "items":{ "$ref":"#/components/schemas/ResultDetails" } } }, "additionalProperties":true } ], "additionalProperties":true, "discriminator":{ "propertyName":"@type", "mapping":{ "PredictionDetails":"#/components/schemas/PredictionDetails" } } }, "ResultDetails":{ "allOf":[ { "$ref":"#/components/schemas/Extensible" }, { "type":"object", "description":"Lists the predicted outcomes.", "properties":{ "prediction":{ "description":"Returns the next best offer.", "type":"string" }, "probability_or_distance":{ "description":"Indicates the confidence score or distance for the recommendation.", "type":"number" } }, "additionalProperties":true } ], "additionalProperties":true, "discriminator":{ "propertyName":"@type", "mapping":{ "ResultDetails":"#/components/schemas/ResultDetails" } } } }, "requestBodies":{ "CollectRequest":{ "description":"Collects data from your data source, such as a database, and stores it in an object file.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/CollectRequest" }, "examples":{ "CollectRequest":{ "$ref":"#/components/examples/CollectRequest" } } } } }, "FetchRequest":{ "description":"Retrieves the specified data from your data set and sends it to the client.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/FetchRequest" }, "examples":{ "FetchRequest":{ "$ref":"#/components/examples/FetchRequest" } } } } }, "CacheRequest":{ "description":"Caches the specified data for use when required.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/CacheRequest" }, "examples":{ "CacheRequest":{ "$ref":"#/components/examples/CacheRequest" } } } } }, "TrainRequest":{ "description":"Trains models according to the provided configuration.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/TrainRequest" }, "examples":{ "TrainRequest":{ "$ref":"#/components/examples/TrainRequest" } } } } }, "PredictRequest":{ "description":"Provides a customer identifier and algorithms for generating next-best-offer recommendations.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/PredictRequest" }, "examples":{ "PredictRequestWithAccountId":{ "$ref":"#/components/examples/PredictRequestWithAccountId" }, "PredictRequestWithMSISDN":{ "$ref":"#/components/examples/PredictRequestWithMSISDN" } } } } } }, "responses":{ "400":{ "description":"The server received a bad request.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/Error" } } } }, "401":{ "description":"The request is not authorized.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/Error" } } } }, "403":{ "description":"The request is forbidden.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/Error" } } } }, "404":{ "description":"The resource was not found.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/Error" } } } }, "405":{ "description":"The method is not allowed.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/Error" } } } }, "409":{ "description":"The server received a conflict.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/Error" } } } }, "500":{ "description":"The system has received an Internal Server Error.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/Error" } } } }, "501":{ "description":"The service was not implemented.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/Error" } } } }, "503":{ "description":"The service is not available.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/Error" } } } }, "200_FetchResponse":{ "description":"The request was completed successfully. If the system throws a runtime error, the response code 200 is returned alongside the error message in the response body.", "content":{ "application/json":{ "schema":{ "type":"array", "items":{ "$ref":"#/components/schemas/FetchResponse" } } } } }, "200_CollectResponse":{ "description":"The request was completed successfully. If the system throws a runtime error, the response code 200 is returned alongside the error message in the response body.", "content":{ "application/json":{ "schema":{ "type":"array", "items":{ "$ref":"#/components/schemas/CollectResponse" } } } } }, "200_CacheResponse":{ "description":"The request was completed successfully. If the system throws a runtime error, the response code 200 is returned alongside the error message in the response body.", "content":{ "application/json":{ "schema":{ "type":"array", "items":{ "$ref":"#/components/schemas/CacheResponse" } } } } }, "200_TrainResponse":{ "description":"The request was completed successfully. If the system throws a runtime error, the response code 200 is returned alongside the error message in the response body.", "content":{ "application/json":{ "schema":{ "type":"array", "items":{ "$ref":"#/components/schemas/TrainResponse" } } } } }, "ChatResult":{ "description":"The request was completed successfully. If the system throws a runtime error, the response code 200 is returned alongside the error message in the response body. If a request asks for another account's bill details, the response body contains status: error instead of an HTTP error response.", "headers":{ "X-Session-Id":{ "description":"Specifies the active conversation's session ID.", "schema":{ "type":"string" } } }, "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ChatResponse" }, "examples":{ "successfulBillSummary":{ "summary":"Successful Bill Response", "value":{ "status":"ok", "agent":"billing_care_agent", "response_format":"string", "response_text":"Account ID: 12345\n\nYour latest bill is $42.50.\n\n---\n*This response was automatically generated by an AI agent.*", "account_id":"12345", "session_id":"8db4c9d7", "requested_account_id":"0.0.0.1+-account+12345" } }, "accountMismatch":{ "summary":"Bill Details Requested for Another Account", "value":{ "status":"error", "intent":"bill_detail_lookup", "response_text":"I can only provide bill details for the current account. Please check the bill and try again.\n\n---\n*This response was automatically generated by an AI agent.*", "session_id":"8db4c9d7" } } } } } }, "Unauthorized":{ "description":"The request does not include a valid bearer token, which the deployment requires when IDCS authentication is enabled.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ErrorResponse" } } } }, "ValidationError":{ "description":"The request contains an invalid body or header.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ValidationErrorResponse" } } } }, "Starting":{ "description":"The service is unavailable because application startup has not completed.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ErrorResponse" }, "example":{ "detail":"Application is starting" } } } }, "UpstreamFailure":{ "description":"The billing agent could not process the request.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ErrorResponse" }, "example":{ "detail":"We couldn't process your request right now. Please try again shortly." } } } }, "ServiceUnavailable":{ "description":"The billing agent is temporarily unavailable.", "content":{ "application/json":{ "schema":{ "$ref":"#/components/schemas/ErrorResponse" }, "example":{ "detail":"Billing service is temporarily unavailable. Please try again shortly." } } } }, "200_PredictResponse":{ "description":"The request was completed successfully. If the system throws a runtime error, the response code 200 is returned alongside the error message in the response body.", "content":{ "application/json":{ "schema":{ "type":"array", "items":{ "$ref":"#/components/schemas/PredictResponse" } } } } } }, "examples":{ "FetchRequest":{ "description":"Request payload for the Fetch API operation.", "value":{ "@type":"FetchRequest", "required_data":[ "RequiredDataName-SubscriberData" ], "additional_data":{ "account_id":"2479437", "sample":"true" } } }, "CacheRequest":{ "description":"Request payload for the Cache API operation.", "value":{ "@type":"CacheRequest", "storage_type":"object_storage", "required_data":[ "RequiredDataName-SubscriberData" ] } }, "CollectRequest":{ "description":"Request payload for the Collect API operation.", "value":{ "@type":"CollectRequest", "data_source_type":[ "oracledb", "prometheus" ], "delta_data":false, "tech_choice":[ "spark" ], "storage_details":[ { "@type":"StorageDetails", "path":"/mnt/sample/new/", "output_file_type":"df", "storage_type":"pvc" } ], "query_builder":[ { "@type":"QueryBuilder", "queries":[ { "@type":"QueryList", "name":"account_data", "query":"select a.poid_id0 as acct_cd, a.currency as crncy_cd, b.country as cntry_name, b.state as state_name, b.city as city_name from account_t a left join account_nameinfo_t b on b.obj_id0 = a.poid_id0 where b.country <> 'null'" }, { "@type":"QueryList", "name":"balance_group_data", "query":"select d.poid_id0 as bal_grp_cd, d.ACCOUNT_OBJ_ID0 as acct_cd, b.rec_id2 as acct_bal_typ_cd, b.VALID_TO as bal_expry_dt, e.VALID_FROM as bal_begin_dt, e.CURRENT_BAL as bal_amt, e.GRANTED_BAL as orgnl_bkt_amt, e.GRANTOR_OBJ_ID0 as prod_sbrp_cd, e.GRANTOR_OBJ_TYPE as prod_sbrp_typ_cd from bal_grp_t d left join bal_grp_sub_bals_t e on e.obj_id0 = d.poid_id0 inner join (select rec_id2, max(valid_to) as valid_to from bal_grp_sub_bals_t group by rec_id2) b on e.rec_id2 = b.rec_id2 and e.valid_to = b.valid_to" }, { "@type":"QueryList", "name":"service_data", "query":"select ACCOUNT_OBJ_ID0 as acct_cd, BAL_GRP_OBJ_ID0 as bal_grp_cd, poid_id0 as ser_srvc_cd, poid_type as ser_srvc_typ_cd, name as ser_srvc_name from service_t where poid_type not like '%/pcm_client' and poid_type not like '%/admin_client'" }, { "@type":"QueryList", "name":"purchased_product_data", "query":"select ACCOUNT_OBJ_ID0 as acct_cd, CYCLE_START_T as cycl_strt_dt, CYCLE_END_T as cycl_end_dt, PLAN_OBJ_ID0 as prod_ofr_cd, PRODUCT_OBJ_ID0 as prod_spec_cd, POID_ID0 as prod_sbrp_cd, PURCHASE_START_T as prod_sbrp_strt_dt, PURCHASE_END_T as prod_sbrp_end_dt, SERVICE_OBJ_ID0 as ser_srvc_cd, DEAL_OBJ_ID0 as deal_cd from purchased_product_t" }, { "@type":"QueryList", "name":"product_data", "query":"select poid_id0 as prod_spec_cd, name as shrt_name, permitted from product_t" }, { "@type":"QueryList", "name":"deal_data", "query":"select d.poid_id0 as deal_cd, d.permitted, d.name, p.PRODUCT_OBJ_ID0 as prod_spec_cd from deal_t d left join deal_products_t p on p.obj_id0 = d.poid_id0" }, { "@type":"QueryList", "name":"plan_data", "query":"select distinct p.POID_ID0 as prod_ofr_cd, p.NAME as prod_ofr_name, d.PERMITTED as srvc_typ_cd, pd.DEAL_OBJ_ID0 as deal_cd from PLAN_T p left join PLAN_SERVICES_DEALS_T pd on pd.OBJ_ID0 = p.POID_ID0 left join DEAL_T d on d.POID_ID0 = pd.DEAL_OBJ_ID0" }, { "@type":"QueryList", "name":"rate_data", "query":"select r.POID_ID0 as prod_ofr_price_cd, r.RATE_PLAN_OBJ_ID0 as prod_ofr_price_typ_cd, rp.PRODUCT_OBJ_ID0 as prod_spec_cd, rp.EVENT_TYPE as evt_typ_cd, rb.ELEMENT_ID as elmnt_cd, rb.SCALED_AMOUNT as scaled_amt from rate_t r left join rate_plan_t rp on rp.POID_ID0 = r.RATE_PLAN_OBJ_ID0 left join rate_bal_impacts_t rb on rb.obj_id0 = r.POID_ID0" }, { "@type":"QueryList", "name":"event_data", "query":"select i.ACCOUNT_OBJ_ID0 as acct_cd, i.OFFERING_OBJ_ID0 as prod_ofr_cd, i.PRODUCT_OBJ_ID0 as prod_spec_cd, i.RESOURCE_ID as acct_bal_typ_cd, e.SERVICE_OBJ_TYPE as service_type, sum(e.net_quantity) as usage from event_t e left join event_bal_impacts_t i on i.OBJ_ID0 = e.POID_ID0 where i.OFFERING_OBJ_ID0 <> 0 group by i.ACCOUNT_OBJ_ID0, i.OFFERING_OBJ_ID0, i.PRODUCT_OBJ_ID0, i.RESOURCE_ID, e.SERVICE_OBJ_TYPE" }, { "@type":"QueryList", "name":"deal_data_2", "query":"select i.ACCOUNT_OBJ_ID0 as acct_cd, i.OFFERING_OBJ_ID0 as prod_ofr_cd, p.DEAL_OBJ_ID0 as deal_cd from event_bal_impacts_t i left join event_t e on i.OBJ_ID0 = e.POID_ID0 left join purchased_product_t p on p.POID_ID0 = i.OFFERING_OBJ_ID0 where e.POID_TYPE = '/event/billing/product/fee/cycle/cycle_forward_monthly' and i.OFFERING_OBJ_ID0 <> 0" }, { "@type":"QueryList", "name":"over_usage_data", "query":"select i.ACCOUNT_OBJ_ID0 as acct_cd, i.OFFERING_OBJ_ID0 as prod_ofr_cd, i.PRODUCT_OBJ_ID0 as prod_spec_cd, EXTRACT(MONTH FROM (TO_DATE('01/01/1970', 'dd/mm/yyyy') + e.CREATED_T/86400)) as MONTH, EXTRACT(YEAR FROM (TO_DATE('01/01/1970', 'dd/mm/yyyy') + e.CREATED_T/86400)) as YEAR, e.SERVICE_OBJ_ID0 as srvc_cd, sum(i.AMOUNT) as amt, sum (e.NET_QUANTITY) / ABS(NULLIF(rb.SCALED_AMOUNT, 0)) as USAGE_OVER_GRANT from event_bal_impacts_t i left join event_t e on i.OBJ_ID0 = e.POID_ID0 left join rate_plan_t rp on rp.PRODUCT_OBJ_ID0 = i.PRODUCT_OBJ_ID0 left join rate_t r on rp.POID_ID0 = r.RATE_PLAN_OBJ_ID0 left join rate_bal_impacts_t rb on rb.obj_id0 = r.poid_id0 where rp.event_type = '/event/billing/product/fee/cycle/cycle_forward_monthly' and e.POID_TYPE like '/event/session%' and e.service_obj_type <> '/service/pcm_client' and i.OFFERING_OBJ_ID0 <> 0 group by i.ACCOUNT_OBJ_ID0, i.OFFERING_OBJ_ID0, e.SERVICE_OBJ_ID0, i.PRODUCT_OBJ_ID0, rb.SCALED_AMOUNT, EXTRACT(MONTH FROM (TO_DATE('01/01/1970', 'dd/mm/yyyy') + e.CREATED_T/86400)), EXTRACT(YEAR FROM (TO_DATE('01/01/1970', 'dd/mm/yyyy') + e.CREATED_T/86400))" }, { "@type":"QueryList", "name":"usage_data", "query":"select i.ACCOUNT_OBJ_ID0 as acct_cd, i.OFFERING_OBJ_ID0 as prod_ofr_cd, i.PRODUCT_OBJ_ID0 as prod_spec_cd, i.RESOURCE_ID as acct_bal_typ_cd, EXTRACT(MONTH FROM (TO_DATE('01/01/1970', 'dd/mm/yyyy') + e.CREATED_T/86400)) as MONTH, EXTRACT(YEAR FROM (TO_DATE('01/01/1970', 'dd/mm/yyyy') + e.CREATED_T/86400)) as YEAR, e.SERVICE_OBJ_ID0 as srvc_cd, substr(e.SERVICE_OBJ_TYPE, instr (e.SERVICE_OBJ_TYPE, '/', -1) + 1) as ser_srvc_name, sum (e.NET_QUANTITY) / ABS(NULLIF(rb.SCALED_AMOUNT, 0)) as USAGE from event_bal_impacts_t i left join event_t e on i.OBJ_ID0 = e.POID_ID0 left join rate_plan_t rp on rp.PRODUCT_OBJ_ID0 = i.PRODUCT_OBJ_ID0 left join rate_t r on rp.POID_ID0 = r.RATE_PLAN_OBJ_ID0 left join rate_bal_impacts_t rb on rb.obj_id0 = r.poid_id0 where rp.event_type = '/event/billing/product/fee/cycle/cycle_forward_monthly' and e.POID_TYPE like '/event/session%' and i.RESOURCE_ID <> 840 and e.service_obj_type <> '/service/pcm_client' and i.OFFERING_OBJ_ID0 <> 0 group by i.ACCOUNT_OBJ_ID0, i.OFFERING_OBJ_ID0, e.SERVICE_OBJ_ID0, i.PRODUCT_OBJ_ID0, rb.SCALED_AMOUNT, e.SERVICE_OBJ_TYPE, i.RESOURCE_ID, EXTRACT(MONTH FROM (TO_DATE('01/01/1970', 'dd/mm/yyyy') + e.CREATED_T/86400)), EXTRACT(YEAR FROM (TO_DATE('01/01/1970', 'dd/mm/yyyy') + e.CREATED_T/86400))" } ], "join_condition":[ { "@type":"JoinConditions", "name":"joined_query", "join":[ "serv_query", "freq_query" ] }, { "@type":"JoinConditions", "name":"left_join_1", "join":[ "event_query", "acc_info_query" ], "join_type":"left", "join_column":"acct_cd" } ] }, { "@type":"QueryBuilder", "queries":[ { "@type":"QueryList", "name":"aiml_data_service_request_total", "query":"2026-03-15T00:00:00Z|2026-03-17T01:00:00Z|30s" } ] } ] } }, "TrainRequest":{ "description":"Request payload for the Train API operation.", "value":{ "@type":"TrainRequest", "algorithm":[ { "@type":"Algorithms", "algo":"xgboost", "model_dir":"model/", "model_name":"churn_rf", "hyper_parameters":{ } } ], "storage_details":[ { "@type":"StorageDetails", "storage_type":"pvc", "additional_details":{ "path":"/mnt/data_services/", "file_type":"json" }, "required_data":[ "acc_query", "over_usage_query" ] } ], "sample":true } }, "PredictRequestWithAccountId":{ "description":"Specifies a recommendation request that uses account_id as the input identifier.", "value":{ "@type":"PredictRequest", "account_id":"2479437", "model_names":[ "recommend_knn", "nbo", "anomaly", "ece_outage", "rec_new" ] } }, "PredictRequestWithMSISDN":{ "description":"Specifies a recommendation request that uses MSISDN as the input.", "value":{ "@type":"PredictRequest", "msisdn":"+1234567890", "model_names":[ "recommend_knn", "nbo", "anomaly", "ece_outage", "rec_new" ] } } }, "parameters":{ "SessionId":{ "name":"X-Session-Id", "in":"header", "required":false, "description":"Specifies the existing session's ID. The response returns the active session's ID in the X-Session-Id header and the response body.", "schema":{ "type":"string" } } }, "securitySchemes":{ "bearerAuth":{ "type":"http", "scheme":"bearer", "bearerFormat":"JWT", "description":"The deployment requires bearer authentication only when it enables IDCS authentication." } } }, "tags":[ { "name":"Billing Agent" }, { "name":"Data Collection and Management", "description":"The operations from the Data Collection and Management category." }, { "name":"Model Training", "description":"The operations from the Model Training category." }, { "name":"Prediction Service", "description":"The operations from the Prediction Service category." } ], "security":[ ], "x-mcp":{ "server":{ "name":"Predict Utility MCP Server", "version":"1.0.0", "capabilities":{ "tools":true, "resources":false, "prompts":true }, "description":"Specifies the MCP server for prediction orchestrator operations." }, "prompts":[ { "name":"prediction-request-triage", "description":"Specifies the right prediction operation and request shape based on your intent.", "arguments":{ "type":"object", "properties":{ "intent":{ "type":"string", "description":"Specifies your prediction request." } }, "required":[ "intent" ] }, "messages":[ { "role":"assistant", "content":{ "type":"text", "text":"You have access to a prediction tool for generating model results.\n\nGuidelines:\n- Use predict-service for prediction requests.\n- Include model_names and exactly one customer identifier: account_id or msisdn.\n- Treat this as a read operation; do not ask for confirmation unless the user request is ambiguous.\n" } }, { "role":"user", "content":{ "type":"text", "text":"User request: {{intent}}" } } ], "toolHints":{ "prefer":[ "predict-service" ] } } ] } }