Skip to content

ADORe API Reference

Overview

The ADORe API provides comprehensive control over scenario management, model checking, bag recording, and ROS2 system integration. All endpoints return JSON responses with appropriate HTTP status codes.

Scenario Management

Start Scenario

POST /api/scenario/start

Start a scenario using either a file path or launch file content.

Request Body:

{
  "scenario": "path/to/scenario.launch.py" | "launch file content",
  "is_file": true | false
}

Response:

{
  "success": true,
  "message": "Scenario started successfully"
}

Stop Scenario

POST /api/scenario/stop

Stop the currently running scenario.

Response:

{
  "success": true,
  "message": "Scenario stopped"
}

Restart Scenario

POST /api/scenario/restart

Restart the current scenario (halts all processes first, then restarts).

Response:

{
  "success": true,
  "message": "Scenario restarted successfully"
}

Halt All Scenarios

POST /api/scenario/halt

Halt all running scenarios and ROS2 processes.

Response:

{
  "success": true,
  "message": "All scenarios halted"
}

Get Scenario Output

GET /api/scenario/output?lines=1000

Get stdout/stderr output from the running scenario.

Query Parameters: - lines: number of lines to return (default: 1000)

Response:

{
  "output": "scenario output text..."
}

Get Scenario Status

GET /api/scenario/status

Get current scenario status and details.

Response:

{
  "status": "running" | "idle" | "failed",
  "scenario": "current_scenario_name",
  "scenario_content": "launch file content",
  "loop_mode": true | false,
  "loop_delay": 0,
  "default_runtime": 60,
  "runtime": 45.2,
  "pid": 12345
}

Get Available Scenarios

GET /api/scenario/get

Get list of available scenario files.

Response:

{
  "scenarios": ["scenario1.launch.py", "scenario2.launch.py"]
}

Get Scenario Content

GET /api/scenario/content/<path:scenario_path>

Get the content of a specific scenario file.

Response:

{
  "success": true,
  "content": "scenario file content...",
  "path": "scenario1.launch.py"
}

Save Scenario

POST /api/scenario/save

Save a new scenario file.

Request Body:

{
  "name": "my_scenario.launch.py",
  "content": "scenario content..."
}

Response:

{
  "success": true,
  "message": "Scenario saved as my_scenario.launch.py"
}

Set Loop Mode

POST /api/scenario/loop

Configure loop mode for automatic scenario restarts.

Request Body:

{
  "enabled": true,
  "delay": 5,
  "runtime": 60
}

Response:

{
  "success": true,
  "message": "Loop mode enabled"
}

Model Checking Management

Start Online Model Checking

POST /api/model_check/online

Start online model checking session monitoring live ROS2 data.

Request Body:

{
  "config_file": "config/default.yaml",
  "duration": 60.0,
  "vehicle_id": 0
}

Response:

{
  "run_id": 12345,
  "message": "Model checking started successfully"
}

Get Model Check Results

GET /api/model_check/result/[run_id]

Get results of a specific model checking run.

Response:

{
  "run_id": 12345,
  "status": "completed" | "running" | "failed" | "cancelled",
  "mode": "online",
  "results": {
    "SUMMARY": {
      "total_propositions": 10,
      "passed": 8,
      "failed": 2,
      "success_rate": 0.8,
      "overall_result": "PASS"
    },
    "proposition_name": {
      "status": "pass" | "fail",
      "description": {...},
      "formula_description": "...",
      "result": 0.95
    }
  },
  "stdout": "model checking output..."
}

Cancel Model Check

POST /api/model_check/cancel/<run_id>

Cancel a running model checking job.

Response:

{
  "message": "Model checking cancelled successfully"
}

Download Model Check Results

GET /api/model_check/result/<run_id>/download

Download model checking results as JSON file.

Bag Recording Management

Start Bag Recording

POST /api/bag/start

Start bag recording with optional duration and topic selection.

Request Body:

{
  "duration": 60,
  "topics": ["/topic1", "/topic2"]
}

Response:

{
  "success": true,
  "message": "Recording started: scenario_20250721T143022Z",
  "bag_name": "scenario_20250721T143022Z",
  "bag_path": "/full/path/to/bag",
  "topics": ["/topic1", "/topic2"],
  "duration": 60
}

Stop Bag Recording

POST /api/bag/stop

Stop the currently running bag recording.

Response:

{
  "success": true,
  "message": "Recording stopped: scenario_20250721T143022Z",
  "bag_name": "scenario_20250721T143022Z",
  "relative_path": "bag_file_recordings/scenario_20250721T143022Z"
}

Get Bag Recording Status

GET /api/bag/status

Get current bag recording status.

Response:

{
  "status": "idle" | "recording" | "stopped" | "completed" | "failed",
  "bag_name": "scenario_20250721T143022Z",
  "bag_path": "/full/path/to/bag",
  "topics": ["all"] | ["/topic1", "/topic2"],
  "duration": 60,
  "runtime": 45.2,
  "pid": 12345
}

List Bag Recordings

GET /api/bag/list

List all recorded bag files.

Response:

{
  "success": true,
  "bags": [
    {
      "name": "scenario_20250721T143022Z",
      "path": "/full/path/to/bag",
      "relative_path": "bag_file_recordings/scenario_20250721T143022Z",
      "created": "2025-07-21T14:30:22",
      "size_mb": 125.4
    }
  ]
}

Get Bag Recording Output

GET /api/bag/output?lines=100

Get stdout/stderr output from the bag recording process.

Query Parameters: - lines: number of lines to return (default: 100)

Response:

{
  "output": "bag recording output text..."
}

Topic Management

Subscribe to Topic

GET /api/topic/subscribe?topic=/topic_name&limit=10&wait_timeout=1.0

Subscribe to a ROS2 topic and get recent messages.

Query Parameters: - topic: ROS2 topic name (required) - limit: maximum number of messages to return (default: 10) - wait_timeout: time to wait for messages if new subscriber (default: 1.0 seconds)

Response:

{
  "success": true,
  "topic": "/topic_name",
  "messages": [
    {
      "timestamp": 1642780800.0,
      "topic": "/topic_name",
      "datatype": "std_msgs/msg/String",
      "data": {"data": "hello world"}
    }
  ],
  "count": 1,
  "new_subscriber": true,
  "waited": 0.5
}

Publish to Topic

POST /api/topic/publish

Publish a message to a ROS2 topic.

Request Body:

{
  "topic": "/topic_name",
  "data": {"data": "hello world"},
  "datatype": "std_msgs/msg/String"
}

Response:

{
  "success": true,
  "message": "Message published to /topic_name",
  "topic": "/topic_name",
  "datatype": "std_msgs/msg/String"
}

List Active Topics

GET /api/topic/list

List all active ROS topics in the system and those being managed by the API.

Response:

{
  "success": true,
  "managed_topics": {
    "active_subscribers": 2,
    "active_publishers": 1,
    "subscriber_topics": ["/topic1", "/topic2"],
    "publisher_topics": ["/topic3"],
    "ros_available": true
  },
  "system_topics": ["/rosout", "/parameter_events", "/cmd_vel", "/scan"]
}

Get Topic Information

GET /api/topic/info/&lt;path:topic_name&gt;

Get detailed information about a specific ROS2 topic.

Response:

{
  "success": true,
  "topic": "/topic_name",
  "datatype": "std_msgs/msg/String",
  "managed": true
}

Position Management

Get Stored Positions

GET /api/positions/get

Get stored start and goal positions from the goal picker.

Response:

{
  "start": {
    "lat": 52.5200,
    "lng": 13.4050,
    "utm": {
      "easting": 606372,
      "northing": 5797172,
      "zone": 32,
      "hemisphere": "N"
    }
  },
  "goal": {
    "lat": 52.5300,
    "lng": 13.4150,
    "utm": {
      "easting": 606380,
      "northing": 5797058,
      "zone": 32,
      "hemisphere": "N"
    }
  }
}

Set Positions

POST /api/positions/set

Store start and/or goal positions.

Request Body:

{
  "start": {"lat": 52.5200, "lng": 13.4050},
  "goal": {"lat": 52.5300, "lng": 13.4150}
}

Response:

{
  "success": true,
  "message": "Positions stored successfully"
}

Clear Positions

POST /api/positions/clear

Clear all stored positions.

Response:

{
  "success": true,
  "message": "Positions cleared"
}

ROS2 System Information

Get ROS2 Nodes

GET /api/ros2/nodes

Get cached information about all ROS2 nodes.

Response:

{
  "nodes": {
    "/node_name": {
      "name": "/node_name",
      "topics": [...],
      "services": [...],
      "actions": [...]
    }
  },
  "count": 5,
  "last_updated": 1642780800.0
}

Get Running Nodes

GET /api/ros2/nodes/running

Get list of currently running ROS2 node names.

Response:

{
  "running_nodes": ["/node1", "/node2", "/node3"],
  "count": 3
}

Get Node Information

GET /api/ros2/nodes/&lt;node_name&gt;

Get detailed information about a specific ROS2 node.

Response:

{
  "name": "/node_name",
  "topics": [
    {
      "topic": "/topic_name",
      "datatype": "std_msgs/msg/String",
      "role": "publisher" | "subscriber"
    }
  ],
  "services": [...],
  "actions": [...]
}

Get ROS2 Topics

GET /api/ros2/topics

Get information about all ROS2 topics.

Response:

{
  "topics": {
    "/topic_name": {
      "name": "/topic_name",
      "datatype": "std_msgs/msg/String",
      "publishers": ["/node1"],
      "subscribers": ["/node2", "/node3"]
    }
  },
  "count": 10,
  "last_updated": 1642780800.0
}

Get Topic Information

GET /api/ros2/topics/&lt;topic_name&gt;

Get detailed information about a specific ROS2 topic.

Response:

{
  "name": "/topic_name",
  "datatype": "std_msgs/msg/String",
  "publishers": ["/node1"],
  "subscribers": ["/node2", "/node3"]
}

Get ROS2 Datatypes

GET /api/ros2/datatypes

Get information about all ROS2 message datatypes.

Response:

{
  "datatypes": {
    "std_msgs/msg/String": {
      "name": "std_msgs/msg/String",
      "interface_text": "string data",
      "interface": [...],
      "topics": ["/topic1", "/topic2"]
    }
  },
  "count": 25,
  "last_updated": 1642780800.0
}

Get Datatype Information

GET /api/ros2/datatypes/&lt;datatype_name&gt;

Get detailed information about a specific ROS2 datatype.

Response:

{
  "name": "std_msgs/msg/String",
  "interface_text": "string data",
  "interface": [...],
  "topics": ["/topic1", "/topic2"]
}

Get ROS2 Graph

GET /api/ros2/graph

Get ROS2 computation graph data.

Response:

{
  "graph": {
    "nodes": [...],
    "edges": [...],
    "metadata": {...}
  },
  "last_updated": 1642780800.0
}

Get ROS2 Status

GET /api/ros2/status

Get ROS2 API worker status and cache statistics.

Response:

{
  "worker_running": true,
  "last_updated": {
    "nodes": 1642780800.0,
    "topics": 1642780801.0,
    "datatypes": 1642780802.0
  },
  "cache_stats": {
    "nodes": 5,
    "topics": 10,
    "datatypes": 25
  }
}

Refresh ROS2 Cache

POST /api/ros2/refresh

Force refresh of ROS2 system cache.

Response:

{
  "message": "Cache refreshed successfully"
}

System Status

Get API Status

GET /api/status

Get overall API status and feature availability.

Response:

{
  "adore_api": "running",
  "model_checker_available": true,
  "ros_marshaller_available": true,
  "bag_recording_available": true
}

Error Handling

All endpoints return appropriate HTTP status codes:

  • 200 OK: Successful operation
  • 400 Bad Request: Invalid request parameters or body
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server error

Error responses include a descriptive message:

{
  "success": false,
  "message": "Error description"
}

Continuous Monitoring API

The continuous monitoring API enables real-time proposition checking against live ROS2 data streams.

Start Continuous Monitoring

POST /api/model_checker/continuous/start

Start a continuous monitoring session.

Request Body:

{
  "config_file": "config/default.yaml",
  "vehicle_id": 0
}

Response:

{
  "session_id": "abc123",
  "status": "running",
  "message": "Continuous monitoring started"
}

Stop Continuous Monitoring

POST /api/model_checker/continuous/stop

Stop the active continuous monitoring session.

Response:

{
  "status": "stopped",
  "message": "Monitoring stopped"
}

Get Continuous Monitoring Status

GET /api/model_checker/continuous/status

Get the status of the current continuous monitoring session.

Response:

{
  "running": true,
  "session_id": "abc123",
  "uptime_s": 42.3,
  "messages_processed": 1200,
  "active_propositions": 10
}

Get Live Violations

GET /api/model_checker/continuous/violations

Get current violation events from the running monitoring session.

Response:

{
  "violations": [
    {
      "proposition": "SAFE_DISTANCE",
      "timestamp": 1642780800.0,
      "value": 0.42,
      "threshold": 0.5,
      "severity": "warning"
    }
  ],
  "count": 1,
  "session_id": "abc123"
}

Get Filtered Violations (excluding disabled propositions)

GET /api/model_checker/continuous/violations/filtered

Returns violations excluding any propositions disabled via the /api/model_checker/continuous/disabled endpoint.

Response: Same shape as /violations.

Set Disabled Propositions

POST /api/model_checker/continuous/disabled

Suppress specific propositions from violation output.

Request Body:

{
  "disabled_propositions": ["PROP_NAME_A", "PROP_NAME_B"]
}

Response:

{ "ok": true }

Get Continuous Results

GET /api/model_checker/continuous/results

Get the aggregated results from the current or most recently completed continuous session.

Response:

{
  "results": {
    "SUMMARY": {
      "total_propositions": 10,
      "passed": 8,
      "failed": 2,
      "success_rate": 0.8,
      "overall_result": "FAIL"
    },
    "PROP_NAME": {
      "status": "fail",
      "description": { "title": "...", "description": "..." },
      "formula_description": "...",
      "result": 0.43,
      "statistics": {
        "duration_s": 42.3,
        "messages_processed": 1200,
        "violation_count": 3,
        "safety_grade": "C, 3.0"
      }
    }
  }
}

Model Checker Configuration API

List Configs

GET /api/model_checker/configs

List all available YAML configuration files.

Response:

{
  "configs": [
    { "name": "default.yaml", "size": 2048, "modified": "2025-07-01T12:00:00Z" }
  ]
}

Get Config

GET /api/model_checker/configs/<name>

Read a specific configuration file.

Response:

{ "name": "default.yaml", "content": "# yaml content..." }

Save Config

POST /api/model_checker/configs

Create or overwrite a configuration file.

Request Body:

{ "name": "my_config.yaml", "content": "# yaml content..." }

Delete Config

DELETE /api/model_checker/configs/<name>

Delete a configuration file.

Model Checker History API

List Run History

GET /api/model_checker/history

List all completed model checking runs.

Response:

{
  "runs": [
    {
      "run_id": 1,
      "status": "completed",
      "overall_result": "PASS",
      "config_file": "config/default.yaml",
      "completed_at": "2025-07-01T12:00:00Z"
    }
  ]
}

Get Run Log

GET /api/model_checker/history/<run_id>/log

Retrieve the log output for a specific historical run.

Response:

{ "log": "full log text..." }

Model Checker Log Stream

Stream API Logs

GET /api/model_checker/logs/stream

Server-Sent Events stream of all API log output. Connect with EventSource.

Event format:

{ "text": "log line", "stream": "stdout", "time": "14:30:00" }

ROS Topics Extended API

Measure Topic Rate

POST /api/topic/hz

Run ros2 topic hz -w 10 for a topic and return the output (waits up to 12 seconds for window of 10 messages).

Request Body:

{ "topic": "/your/topic" }

Response:

{ "success": true, "topic": "/your/topic", "output": "average rate: 10.000\n..." }

Echo One Message

POST /api/topic/echo

Receive a single message from a topic (ros2 topic echo --once) and return it as raw text.

Request Body:

{ "topic": "/your/topic" }

Response:

{ "success": true, "topic": "/your/topic", "raw": "header:\n  stamp: ..." }

Stream Topic (SSE)

GET /api/topic/stream?topic=<topic_name>

Server-Sent Events stream of ros2 topic echo output for continuous observation.

Query Parameters: - topic: the ROS 2 topic name (required)

Event format:

{ "text": "line from ros2 topic echo", "time": "14:30:00" }

ROS Workspace API

Workspace Status

GET /api/ros_workspace/status

Returns the current state of the ros2_workspace directory.

Response:

{
  "workspace_dir": "/path/to/ros2_workspace",
  "workspace_exists": true,
  "makefile_exists": true,
  "build_dir_exists": true,
  "install_dir_exists": true,
  "running": { "clean": false, "build": false }
}

Clean Workspace

POST /api/ros_workspace/clean

Runs make clean inside the ros2_workspace directory. Output is streamed via /api/ros_workspace/log/stream.

Response:

{ "success": true, "message": "make clean started" }

Build Workspace

POST /api/ros_workspace/build

Runs make build inside the ros2_workspace directory. Output is streamed via /api/ros_workspace/log/stream.

Response:

{ "success": true, "message": "make build started" }

Workspace Build Log Stream (SSE)

GET /api/ros_workspace/log/stream

Server-Sent Events stream of stdout/stderr from make clean or make build invocations.

Event format:

{ "text": "log line", "stream": "stdout", "time": "14:30:00" }