One of the most common use cases for integrating with the Mangrove API is sending timeseries data from a frontline measurement system to your MRV environment in Mangrove for accounting and reporting. This cookbook walks you through the steps to do so.

Example Scenario

We will use the example of a SCADA database pushing meter measurements of carbon capture data to a CCS project developer’s own Mangrove account. This can happen on a daily basis, where the measurements collected throughout the day are sent to Mangrove in one scheduled push at the end of the day (midnight).
1

Pre-requisites

Before you begin, make sure you have the following:
  • Project ID: The unique identifier for the project you’re targeting.
  • API Credentials: A valid API token (usually a Bearer token).
    • The token must have Data Collection permissions with both read and write access.
2

Retrieve Event Type Slugs

Each event type in a Mangrove project has a unique slug. These are required when posting events.Endpoint to use: GET event types GET /v1/projects/{project_id}/event-types
Example
curl -X GET https://api.mangrovesystems.com/v1/projects/abc123/event-types \
-H "Authorization: Bearer YOUR_API_TOKEN"
Response
{
  "data": [
    {
      "slug": "co2-capture",
      "name": "CO2 Capture measurement",
      "updated_at": "2024-12-11T22:20:13.956Z",
      "data_point_types": [
        {
          "slug": "high-conc-co2-outflow-mass-flow-rate",
          "name": "High concentration CO₂ outflow mass flow rate",
          "value_type": "number",
          "unit": "g/s"
        },
        {
          "slug": "high-conc-co2-outflow-co2-mass-fraction",
          "name": "High concentration CO₂ outflow CO₂ mass fraction",
          "value_type": "number",
          "unit": "%"
        },
        {
          "slug": "high-conc-co2-outflow-temperature",
          "name": "High concentration CO₂ outflow temperature",
          "value_type": "number",
          "unit": "°C"
        },
        {
          "slug": "high-conc-co2-outflow-meter-status",
          "name": "CO2 Outflow Meter Status",
          "value_type": "string",
          "unit": null
        }
      ],
      "requires_locations": false
    },
    {
      "slug": "co2-injection",
      "name": "CO2 Injection Measurement",
      "updated_at": "2024-12-11T22:20:14.259Z",
      "data_point_types": [
        {
          "slug": "injected-co2-mass-flow-rate",
          "name": "Injected CO₂ mass flow rate",
          "value_type": "number",
          "unit": "lb/min"
        },
        {
          "slug": "injected-co2-co2-mass-fraction",
          "name": "Injected CO₂ CO₂ mass fraction",
          "value_type": "number",
          "unit": "%"
        },
        {
          "slug": "injected-co2-temperature",
          "name": "Injected CO₂ temperature",
          "value_type": "number",
          "unit": "°C"
        },
        {
          "slug": "injected-co2-meter-status",
          "name": "Injected CO2 Meter Status",
          "value_type": "string",
          "unit": null
        }
      ],
      "requires_locations": false
    }
    ...
    ]
}
Save the slugs (co2-capture,co2-injection) for your POST payload.
3

Retrieve Location IDs

Events must be associated with a specific location ID.Endpoint to use: GET project locations GET /v1/projects/{project_id}/locations
Example
curl -X GET https://api.mangrovesystems.com/v1/projects/abc123/locations \
-H "Authorization: Bearer YOUR_API_TOKEN"
Response
{
  "data": [
    {
      "id": "loc_axkmTgN2jFTZneTt",
      "lat": "29.67647855520935",
      "long": "-94.65051475551489",
      "name": "Injection Well A-123",
      "updated_at": "2024-12-13T13:25:18.844Z",
      "address": {
        ...
      }
    },
    ...
  ]
}
4

Send the Events

With event type slugs and location IDs in hand, you can now POST your timeseries data as events.Endpoint to use: POST event POST /v1/projects/{project_id}/eventsHeaders:
Headers
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN
Example Payload
  {
    "event": {
      "event_type": "co2-injection",
      "start_time": "2025-06-04T00:00:00.000Z",
      "end_time": "2025-06-04T00:14:59.000Z",
      "notes": "Sent from SCADA historian",
      "locations": [
        {"id": "loc_axkmTgN2jFTZneTt"},
        ... // if 2 locations are included, Mangrove takes the first location in the array as origin, and the 2nd as destination location. This is most applicable to transport events
      ],
      "data_points": [
        {
          "slug": "injected-co2-mass-flow-rate",
          "value": 2.28746
        },
        {
          "slug": "injected-co2-co2-mass-fraction",
          "value_type": 96.7
        },
        {
          "slug": "injected-co2-temperature",
          "value_type": "number",
          "unit": 66.34059
        },
        {
          "slug": "injected-co2-meter-status",
          "value": "ONLINE"
        }
      ]
    }
  }
5

Attach Evidence Files on Created Events

After events are created, you can associate evidence files (e.g., images, PDFs) with them.
This call must be made per event. Automate it by iterating over the list of event IDs created in Step 4.
Endpoint to use: POST evidence on an event POST /v1/events/{event_id}/evidence
Example
curl -X POST https://api.mangrovesystems.com/v1/events/event-123/evidence \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "file=@photo.jpg"
Response
{
  "id": "evidence-xyz",
  "file_name": "photo.jpg",
  "mime_type": "image/jpeg"
}