Skip to content

Integration

For advanced users, integrating directly with the Madrona API allows for customized control and automation of pipelines, profiles, and camera settings. This document provides a high-level overview of how one would interact directly with the Madrona API to manage pipelines and trigger specific behaviors.

For detailed API documentation, including OpenAPI specifications, please refer to the API Documentation tab in the navigation.

Pipeline Lifecycle

A pipeline can be started, stopped, and monitored directly through the API.

To start a pipeline, a request to /api/pipeline/<mx_id>/start should be made. To stop a pipeline, a request to /api/pipeline/<mx_id>/stop should be made.

Monitoring the status of a pipeline can be done by requesting /api/pipeline/statusListen. This endpoint provides Server-Sent Events (SSE) that stream real-time updates on the pipeline's status. The events are structured as CloudEvents. An example is provided below:

{
  "specversion": "1.0",
  "type": "madrona.pipeline.statuses",
  "source": "/api/pipeline/statusListen",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "time": "2024-06-01T12:00:00Z",
  "data": {
    "mx_id_1": {
        "running": true,
        "output_queue_size": 5,
        "input_queue_size": 3,
        "start_time": 1234567890
    }
  }
}

Regular polling of the pipeline status can also be done by requesting /api/pipeline/statuses or /api/pipeline/{mx_id}/status.

Pipeline Inputs

Communicating with a running pipeline—such as sending commands to take snapshots or update camera settings—is done by sending requests to the /api/pipeline/{mx_id}/input endpoint. This endpoint accepts JSON-formatted CloudEvents.

Depending on the active profile (e.g., CockpitViewer, RawRecorder, RTSPLiveStream), the pipeline listens for and processes the following CloudEvent type inputs.

madrona.snapshot.trigger

Triggers the pipeline to immediately capture and save a snapshot to disk. No data payload is required.

{
  "specversion": "1.0",
  "id": "9c4ee2d7-0650-40fd-84f5-ebaeb5ede23b",
  "source": "/my/custom/application",
  "type": "madrona.snapshot.trigger",
  "time": "2026-03-27T12:00:00.000Z"
}

madrona.snapshot.start

Enables the interval-based snapshot capture loop. The interval rate is determined by the profile configuration. No data payload is required.

{
  "specversion": "1.0",
  "id": "112d765c-3c31-434f-9340-daf8c441fa4b",
  "source": "/my/custom/application",
  "type": "madrona.snapshot.start",
  "time": "2026-03-27T12:00:00.000Z"
}

madrona.snapshot.stop

Disables the interval-based snapshot capture loop. No data payload is required.

{
  "specversion": "1.0",
  "id": "223d765c-3c31-434f-9340-daf8c441fa4c",
  "source": "/my/custom/application",
  "type": "madrona.snapshot.stop",
  "time": "2026-03-27T12:00:00.000Z"
}

madrona.camera.control

Updates specific camera settings (exposure, focus, white balance, etc.). - The subject must target the specific camera module (center, left, right, or stereo to apply to both left and right). - The data payload contains the desired state. Any omitted properties will remain unchanged.

{
  "specversion": "1.0",
  "id": "407d765c-3c31-434f-9340-daf8c441fa4e",
  "source": "/my/custom/application",
  "type": "madrona.camera.control",
  "time": "2026-03-27T12:00:00.000Z",
  "subject": "center",
  "data": {
    "exposure_auto": false,
    "exposure": 15000,
    "sensitivity": 800,
    "focus_auto": true,
    "white_balance_auto": false,
    "white_balance": 4600,
    "brightness": 2,
    "contrast": 1
  }
}

madrona.camera.controls

Requests the current state of all camera controls from the pipeline. No data payload is required. 

{
  "specversion": "1.0",
  "id": "558d765c-3c31-434f-9340-daf8c441fa4f",
  "source": "/my/custom/application",
  "type": "madrona.camera.controls",
  "time": "2026-03-27T12:00:00.000Z"
}

(The pipeline will subsequently broadcast a madrona.camera.controls response over the output SSE stream containing the configurations for the left, right, center, and stereo modules.)

Pipeline Outputs

While running, pipelines broadcast events regarding their status, logs, and actions. These can be listened to by connecting an SSE client to /api/pipeline/{mx_id}/output.

Common broadcast events include:

madrona.snapshot.taken

Fired every time an image is successfully saved to disk. The data property contains the absolute file path to the saved image.

{
  "specversion": "1.0",
  "id": "e1276c24-a31d-45b6-98dd-cb52f580b369",
  "source": "/madrona/profile/CockpitViewer",
  "type": "madrona.snapshot.taken",
  "time": "2026-03-27T12:00:05.526417+00:00",
  "data": "/tmp/madrona/snapshot-2026-03-27-12-00-05.jpg"
}

madrona.camera.controlled

Fired after a pipeline successfully applies an incoming madrona.camera.control command. The subject dictates which camera was updated, and the data contains the newly applied settings.

{
  "specversion": "1.0",
  "id": "f2386c24-a31d-45b6-98dd-cb52f580b370",
  "source": "/madrona/profile/CockpitViewer",
  "type": "madrona.camera.controlled",
  "time": "2026-03-27T12:00:01.064Z",
  "subject": "center",
  "data": {
    "exposure_auto": false,
    "exposure": 15000,
    "sensitivity": 800,
    "focus_auto": true,
    "white_balance_auto": false,
    "white_balance": 4600,
    "brightness": 2,
    "contrast": 1
  }
}

System Logs & Info

The pipeline also routes standard informational, warning, and error messages to the output stream. These are typically displayed inside the Madrona web UI pipeline console. - madrona.message.info - madrona.message.warning - madrona.message.error - madrona.message.exception (Includes traceback strings in the payload)