Data API

The Digital.ai Data API service enables you to accurately assess your IT effectiveness and determine failure factors that could lead to an incident. The Data API service provides you with Change Failure Predictions and Change Credit Score APIs. The service provides details about indicators of a potential change failure, along with predictions of success or failure based on historical performance, current context, and quality checks. The use of Change Failure Predictions and Change Credit Score APIs enables Change Executives more informed decision-making within the source system.

Digital.ai manages the client credentials required for authenticating with the Data API using an API token. The source system will invoke the Data API to retrieve the following:

• Change Failure Predictions API: An AI-powered solution that analyzes change requests to predict failure probability and identify specific risk factors.
• Change Credit Score API: A sophisticated scoring system that evaluates and rates the reliability of teams, groups, or projects based on historical performance.

Key capabilities include:

• Predictive Analytics: Forecast potential change failures before they occur.
• Risk Assessment: Identify and quantify risk factors in your IT changes.
• Performance Scoring: Evaluate team and project performance through credit scoring.
• Historical Analysis: Leverage past data to improve future outcomes.

Authentication

API authentication is the process of verifying the identity of a user who is making an API request, usually treated like passwords.

Refer to Authentication to generate a token and authenticate.

Change Failure Predictions

The Change Failure Predictions API offers insights into the likelihood of change failure and the key risk factors contributing to it. By leveraging machine learning models it enables you to make informed decisions through predictions of change failure probabilities and associated risk scores. The API accepts business IDs as input and returns predicted outcomes, contributing features, and model information.

• REST API Endpoint and Details

  Details the endpoint URLs, HTTP methods, and structure for accessing the API services.

  • Endpoint: https://api.us.digital.ai/ml-inference/store/{project_name}/{model_name} or https://api.eu.digital.ai/ml-inference/store/{project_name}/{model_name}

  • Details:

    • Digital.ai Platform URL: https://api.us.digital.ai or https://api.eu.digital.ai
    • API Path: /ml-inference/store/{project_name}/{model_name}
    • Method: POST

• Path Parameters

  Describes the required and optional parameters that must be included in the API endpoint path.

  • project_name: Unique identifier of the initiative or project. For example, ChangeFailure.

  • model_name: Name of the model used in the project. For example, CatBoostClassifier.

    note

    The values of project_name and model_name are based on the subscription and are shared by Digital.ai.

• Request

  Specifies the structure and required fields for making a valid API request.

  Parameter	Type	Required	Description
  business_ids	Array	Yes	List of change IDs to analyze for failure prediction

  For example:

  {
    "business_ids": ["CHG1", "invalid_id"]
  }

• Response

  Explains the structure and fields included in the API response.

  Field	Description
  id	Object with name (usually "business_id") and value (the change ID)
  features	Array of feature objects: each has name, value, and feature_importance. The feature_importance value shows how much a feature influenced the prediction. High values highlight key risk drivers, while low or zero values indicate minimal impact
  predictions	Array of prediction objects: each has name (e.g., "probability_N", "probability_Y") and value
  ml_model_id	Identifier for the machine learning model used
  message	Status message (e.g., success or error)
  created_on	Timestamp of the response creation

  For example:

  [
  {
    "id": {
      "name": "business_id",
      "value": "CHG1"
    },
    "features": [
      {
        "name": "feature_1",
        "value": "feature_1_value",
        "feature_importance": 0.023064278053662977
      },
      {
        "name": "feature_2",
        "value": "feature_2_value",
        "feature_importance": 0.32746387262962945
      }
    ],
    "predictions": [
      {
        "name": "probability_N",
        "value": 0.6417114272690727
      },
      {
        "name": "probability_Y",
        "value": 0.35828857273092724
      }
    ],
    "ml_model_id": 42,
    "message": "Data retrieved successfully",
    "created_on": "2023-10-03T12:00:00Z",
  },
  {
    "id": {
      "name": "business_id",
      "value": null
    },
    "features": [
      {
        "name": "feature_1",
        "value": null,
        "feature_importance": null
      },
      {
        "name": "feature_2",
        "value": null,
        "feature_importance": null
      }
    ],
    "predictions": [
      {
        "name": "probability_N",
        "value": null,
      },
      {
        "name": "probability_Y",
        "value": null,  
      }
    ],
    "ml_model_id": 42,
    "message": "Business id not found",
    "created_on": null
  },
  ]

• Error Codes

  Lists possible error codes returned by the API and their meanings.

  Code	Message	Description
  200	Success	Response would include a JSON with the requested prediction values for the respective ID
  400	Invalid input	Project and/or model do not exist
  401	Issue with Authentication and displays one of the errors	Missing authentication credentials, Unauthorized access, or Invalid API token
  403	ML Inference Service is not enabled for your account	The ML Inference Service is not enabled for your account; contact support to enable access
  422	Invalid or issues with payload	The request payload is invalid or contains issues such as missing required fields or incorrect data types
  500	Unexpected error	An unexpected server error occurred while processing the request

Change Credit Score

The Change Credit Score API provides a credit score for a specified group or entity, along with the associated group name. This score is computed using historical data and contextual analysis, with which you can evaluate the reliability or risk profile of the group. The API takes dataset names as input and returns the credit score along with relevant metadata.

• REST API Endpoint and Details

  Details the endpoint URLs, HTTP methods, and structure for accessing the API services.

  • Endpoint: https://api.us.digital.ai/analytics/query/dataset/{dataset_name}?column_name=<column_name>&values=<value> or https://api.eu.digital.ai/analytics/query/dataset/{dataset_name}?column_name=<column_name>&values=<value>

  • Details:

    • Digital.ai Platform URL: https://api.us.digital.ai or https://api.eu.digital.ai
    • API Path: /analytics/query/dataset/{dataset_name}
    • Method: GET

• Parameters

  Describes the required parameters that must be included in the API endpoint path.

  • Path Parameter: Located within the endpoint’s path, before the '?' symbol. It is used to specify or access a particular resource directly.

    • dataset_name: The name of the dataset to query. This is used to identify the source of the data. For example, CHANGE_CREDIT_SCORE.

  • Query Parameters: Located after the '?' symbol in the endpoint URL. It is used to filter, sort, or modify the response data.

    • column_name: The column in the dataset to filter on. For example, BUSINESS_ID.
    • values: The value(s) to filter the specified column. For example, CHG12345.

• Response

  Explains the structure and fields included in the API response.

  Field	Description
  chg_id	The unique identifier for the change
  chg_name	The name of the change or group
  credit_score	The calculated credit score for the change or group

  For example:

  {
    "columns": ["chg_id", "chg_name","credit_score"],
    "result": [
      ["CHG12345", "chg1_name", 12.234],
      ["CHG12346", "chg2_name", 23.456]
    ]
  }

• Error Codes

  Lists possible error codes returned by the API and their meanings.

  Code	Message	Description
  200	Success	The request was successful, and the response contains the requested data
  400	Invalid input	The input provided in the request is invalid or does not meet the criteria
  404	No data found	The requested data could not be found in the dataset
  422	Validation Error	The input payload failed validation checks
  500	Error fetching data	An unexpected error occurred while processing the request