--- title: "CARMA-IMS API Integration" slug: "carma-ims-api-integration" updated: 2026-10-27T23:12:37Z published: 2026-10-27T23:12:37Z canonical: "ims-handbook.cenosco.com/carma-ims-api-integration" --- > ## Documentation Index > Fetch the complete documentation index at: https://ims-handbook.cenosco.com/llms.txt > Use this file to discover all available pages before exploring further. # CARMA - IMS API Integration Your title goes hereCARMA is a SHELL Organization Internal Application driven to provide Analytics with Corrosion Predictions and Risk Modelling for Safety and Operation optimization for SHELL assets. This overview explains the core reason for the interaction between CARMA and IMS sharing the data across the applications for the better cause of improvising Safety and Operation optimization. ## ### ## Scope Sharing the Overall Sensor Corrosions, Forecasted Corrosion, Forecasted Wall Thickness, and Life of CML data with IMS from CARMA via Production API’s. ## System Overview CARMA is a Machine Learning/Data Science Driven application built on C3.AI platform using Azure Cloud Services. APIs built are user account and token-based accessible with no involvement of any third-party suite for communication. ## Glossary API = Application Programming Interface CARMA = Corrosion And Risk Modelling Analytics IMS = Integrity Management System CML = Condition Monitoring Location C3.AI = A platform on which the application is built ## ## Requirements | Number | Name | Description | Rationale | | --- | --- | --- | --- | | | | | | | **CARMA API** | | | | | CARMA-IMS-001 | CARMA API | The CARMA application shall provide an API that allows IMS to access data | The CARMA application makes prediction on the status of piping and equipment that will be beneficial to optimize the Risk Based Inspection process that is housed in IMS. Direct access to the information on CARMA will streamline the use of its data. | | CARMA-IMS-001 | JSON Format | The CARMA API shall receive and send data in JSON format | JSON format is a standard for sending and receiving objective data. | | CARMA-IMS-002 | Production URL | https://shell-carma-prime.c3iot.ai/api/1/carma/prime | | | CARMA-IMS-003 | Sensor Field | The sensor associated with a CML shall be transmitted as a list of sensors | There can be more than one sensor at a CML, therefore the field shall always be treated as a list of sensors. | | CARMA-IMS-004 | Data Access Hierarchy | Data can be accessed by providing the data hierarchy in appendix A | We need a common hierarchy for finding asset data. | | CARMA-IMS-005 | CARMA Data Response | The response shall provide the data in appendix B | Reference: Appendix B | | CARMA-IMS-006 | Error Messages | The API shall provide clear error messages if an exception occurs | Providing what field is in error or missing will improve debugging. | | | | | | | **IMS API** | | | | | CARMA-IMS-101 | IMS API | IMS application shall provide an API that allows CARMA to access data | IMS contains asset information that CARMA uses for corrosion prediction. Direct access to the IMS application will automate data extraction. | | CARMA-IMS-101 | Test URL | https://ims-datalake-test.shell.com | | | CARMA-IMS-102 | Production URL | https://ims-datalake.shell.com | | | CARMA-IMS-103 | JSON Format | The IMS API shall receive and send data in JSON format | JSON format is a standard for sending and receiving objective data. | | CARMA-IMS-104 | Provide Static Information | The IMS API shall provide static design and process information | CARMA would like to extract this information directly from IMS instead of relying on SMEs to provide info. See Appendix C. | | CARMA-IMS-105 | Data Access Hierarchy | Data can be accessed by providing the data hierarchy in Appendix A | We need a common hierarchy for finding asset data. | | CARMA-IMS-106 | IMS Data Response | The response shall provide the data in appendix C | Reference: Appendix C | | CARMA-IMS-007 | Error Messages | The API shall provide clear error messages if an exception occurs | Providing that field is in error or missing will improve debugging. | ## Asset Hierarchy Both APIs will use the following hierarchy to search for data associated with a specific asset location: Site / Production Unit / Unit / Equipment / Circuit / Subcircuit / CML ## CARMA Response Data The CARMA API will make the following data available: Position – Operating Position of the Sensor in the CML ShortTermCarmaCR – Average predicted short-term LongTermCarmaCR – Average predicted corrosion rate long-term CurrentCarmaCR – The latest/last Predicted Corrosion rate value CustomCarmaCR – User Specified duration for average corrosion rate (Default – 2 Years) CRUnit – Unit of the Corrosion Rate value SpanOfCR – Duration for user-defined corrosion rate SpanUnit – Unit of defined corrosion rate duration (Day, Month, Year) ## IMS Response Data The IMS API will make the following data available if it exists in the IMS system: - Corrosion Loop - Fluid - Minimum allowable wall thickness - Pipe diameter - Pipe material - Nominal pipe thickness - Last measured thickness - FLOC - Nominal temperature - Nominal pressure ## Technical Overview ### API action getCarmaCorrosions #### API Scope The scope is to Provide the Corrosion and other data to the IMS end users via the IMS Application UI. #### API Details #### **API endpoint Name**: CarmaPredictionApi **Action name:** action=getCarmaCorrosions **API PROD URL**: [https://shell-carma-prime.c3iot.ai/api/1/carma/prime](https://shell-carma-prime.c3iot.ai/api/1/carma/prime) **Example FINAL URL:** [https://shell-carma-prime.c3iot.ai/api/1/carma/prime/CarmaPredictionApi?action=getCarmaCorrosions](https://shell-carma-prime.c3iot.ai/api/1/carma/prime/CarmaPredictionApi?action=getCarmaCorrosions) **API Method**: POST #### **API Payload** - spec – contains the elements of the Payload - equipment – equipment Id for the selected CML in IMS - circuit – Circuit Id for the selected CML in IMS - subCircuit – SubCircuit Id for the selected CML in IMS - cml – ID for the selected CML in IMS - start – Start Date from which the Predicted Corrosion Rates are to be averaged. - end – End Date till which the Predicted Corrosion Rates are to be averaged. - site – The site ID for the selected CML in IMS - plant – The Plant ID for the selected CML in IMS - Interval – The Interval the data needs to be fetched for the averaging. #### **API Response** - equipment – equipment ID for the selected CML in IMS - circuit – Circuit ID for the selected CML in IMS - subCircuit – SubCircuit ID for the selected CML in IMS - cml – Condition Monitoring Location ID to which the response is populated. - start – Start Date from which the Predicted Corrosion Rates are to be averaged. - end – End Date till which the Predicted Corrosion Rates are to be averaged. - site – The site ID for the selected CML in IMS - plant – The Plant ID for the selected CML in IMS - Interval – The Interval the data needs to be fetched for the averaging. - sensors – Contains the list of Sensors that are tagged under the response CML. - Sensor – Sensor ID tagged under the CML. - Position – Operating Position of the Sensor in the CML - Status – “Success”, “Error” describing if the CR fetch on the sensor was successful or failed letting the user know if is it good to use. - CorrosionRates – The list of Corrosion Rates for the Tagged Sensor under the CML - ShortTermCarmaCR – The Average Predicted Corrosion rate value of the Sensor for the tagged CML for the Predefined Specified duration (6 Months) - LongTermCarmaCR – The Average Predicted Corrosion rate value of the Sensor for the tagged CML for the whole operating duration of sensor available in CARMA (2-5 Years) - CurrentCarmaCR – The latest/last Predicted Corrosion rate value of the Sensor for the tagged CML ( 1 Day) - CustomCarmaCR – The Average Predicted Corrosion rate value of the Sensor for the tagged CML for the User Specified duration. (Default – 2 Years) - CRUnit – Unit of the Corrosion Rate value - SpanOfCR – The Predefined or User-defined duration for which the Corrosion Rate is averaged out. - SpanUnit – Unit of the duration (Day, Month, Year) #### **API Error** - errorMessage: The Reason for the Error is that the API is not giving the expected answer. - equipment: The Equipment ID to which the Error is generated. - circuit: The circuit ID to which the Error is generated. - subCircuit: The subCircuit ID to which the Error is generated. - cml: The cml ID to which the Error is generated. #### API Access IMS to raise or note any preparations to be done to access the API. ### API action getAvailableCML #### API Scope The scope is to Provide the available Carma CML data to the IMS end users via the IMS Application UI. #### API Details #### **API endpoint Name**: CarmaPredictionApi **Action name:** action=getAvailableCML **API PROD URL**: [https://shell-carma-prime.c3iot.ai/api/1/carma/prime](https://shell-carma-prime.c3iot.ai/api/1/carma/prime) **Example FINAL URL:** [https://shell-carma-prime.c3iot.ai/api/1/carma/prime/CarmaPredictionApi?action=getAvailableCML](https://shell-carma-prime.c3iot.ai/api/1/carma/prime/CarmaPredictionApi?action=getAvailableCML) **API Method**: POST #### **API Payload** - site – The site id for the selected CML in IMS - limit – The limit of total data - offset – The offset limit of total data #### Request Example ![A screenshot of a computer Description automatically generated](https://cdn.document360.io/e492a0e0-a4ba-4aca-8fc6-76b95f91fdf3/Images/Documentation/carma-temp-image-1430t82t.png?sv=2026-02-06&spr=https&st=2026-10-28T18%3A18%3A43Z&se=2026-10-28T19%3A18%3A43Z&sr=c&sp=r&sig=CBDCc1TQOJA6aZy4%2BmO5DUl6nUPmzISkxBkbfMXqSLw%3D) #### Response Example ![A screenshot of a computer Description automatically generated](https://cdn.document360.io/e492a0e0-a4ba-4aca-8fc6-76b95f91fdf3/Images/Documentation/carma-temp-image-2wg8tvmx.png?sv=2026-02-06&spr=https&st=2026-10-28T18%3A18%3A43Z&se=2026-10-28T19%3A18%3A43Z&sr=c&sp=r&sig=CBDCc1TQOJA6aZy4%2BmO5DUl6nUPmzISkxBkbfMXqSLw%3D) #### API Access IMS picks up data and updates CMLs in IMS that has CARMA.