> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangrovesystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending time series data to Mangrove

> Send well-formed event data, associated with the right locations and evidence, for easy review and MRV accounting.

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.

<Card title="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).
</Card>

<Steps>
  <Step title="Pre-requisites">
    Before you begin, make sure you have the following:

    * Mangrove project ID: The unique identifier for the project you're targeting.
    * API Credentials: A valid API token (Bearer token).
      * The token must have Data Collection permissions with both read and write access.
  </Step>

  <Step title="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](/api-reference/events/get-event-types)
    `GET /v1/projects/{project_id}/event-types`

    ```bash Example theme={null}
    curl -X GET https://app.gomangrove.com/v1/projects/abc123/event-types \
    -H "Authorization: Bearer YOUR_API_TOKEN"
    ```

    ```json Response theme={null}
    {
      "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.
  </Step>

  <Step title="Retrieve Location IDs">
    Events must be associated with a specific location ID.

    Endpoint to use: [GET project locations](/api-reference/locations/get-all)
    `GET /v1/projects/{project_id}/locations`

    ```bash Example theme={null}
    curl -X GET https://api.mangrovesystems.com/v1/projects/abc123/locations \
    -H "Authorization: Bearer YOUR_API_TOKEN"
    ```

    ```json Response theme={null}
    {
      "data": [
        {
          "id": "loc_axkmTgN2jFTZneTt",
          "lat": "29.67647855520935",
          "long": "-94.65051475551489",
          "name": "Injection Well A-123",
          "updated_at": "2024-12-13T13:25:18.844Z",
          "address": {
            ...
          }
        },
        ...
      ]
    }

    ```
  </Step>

  <Step title="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](/api-reference/events/create)
    `POST /v1/projects/{project_id}/events`

    Headers:

    ```http Headers theme={null}
    Content-Type: application/json
    Authorization: Bearer YOUR_API_TOKEN
    ```

    ```json Example Payload theme={null}
      {
        "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"
            }
          ]
        }
      }
    ```
  </Step>

  <Step title="Attach Evidence Files on Created Events">
    After events are created, you can associate evidence files (e.g., images, PDFs) with them.

    <Note>
      This call must be made per event. Automate it by iterating over the list of event IDs created in Step 4.
    </Note>

    Endpoint to use: [POST evidence on an event](/api-reference/evidence/create)
    `POST /v1/events/{event_id}/evidence`

    ```bash Example theme={null}
    curl -X POST https://api.mangrovesystems.com/v1/events/event-123/evidence \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -F "file=@photo.jpg"
    ```

    ```json Response theme={null}
    {
      "id": "evidence-xyz",
      "file_name": "photo.jpg",
      "mime_type": "image/jpeg"
    }
    ```
  </Step>
</Steps>