feat(api): add Notification schema and document notification streams

gns3server/api/responses.py

@@ -0,0 +1,41 @@
+#
+# Copyright (C) 2026 GNS3 Technologies Inc.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from typing import Any
+
+from fastapi.responses import JSONResponse
+
+from gns3server import schemas
+
+NDJSON_MEDIA_TYPE = "application/x-ndjson"
+
+
+class NDJSONResponse(JSONResponse):
+    """
+    Only used as the response_class of streaming routes to publish the application/x-ndjson media type
+    and the schema of the streamed objects in the OpenAPI document.
+    """
+
+    media_type = NDJSON_MEDIA_TYPE
+
+
+NOTIFICATION_STREAM_RESPONSES: dict[int | str, dict[str, Any]] = {
+    200: {
+        "model": schemas.Notification,
+        "description": "Stream of notifications, one JSON object per line. "
+        "Each line is a Notification, the first one is a ping and then a ping is sent at least every 5 seconds.",
+    }
+}

gns3server/api/routes/controller/controller.py

@@ -30,6 +30,7 @@ from websockets.exceptions import ConnectionClosed, WebSocketException
 
 from gns3server import schemas
 from gns3server.agent.web_wireshark.stats import collect_webwireshark_stats
+from gns3server.api.responses import NDJSON_MEDIA_TYPE, NOTIFICATION_STREAM_RESPONSES, NDJSONResponse
 from gns3server.config import Config
 from gns3server.controller import Controller
 from gns3server.controller.controller_error import ControllerError, ControllerForbiddenError
@@ -254,10 +255,19 @@ async def statistics() -> dict:
     }
 
 
-@router.get("/notifications", dependencies=[Depends(get_current_active_user)])
+@router.get(
+    "/notifications",
+    dependencies=[Depends(get_current_active_user)],
+    response_class=NDJSONResponse,
+    responses=NOTIFICATION_STREAM_RESPONSES,
+)
 async def controller_http_notifications(request: Request) -> StreamingResponse:
     """
-    Receive controller notifications about the controller from HTTP stream.
+    Receive controller notifications from an HTTP stream of newline delimited JSON objects (see the Notification schema).
+
+    The same messages are available as WebSocket text frames on `/v3/notifications/ws`.
+    Controller actions: `compute.*`, `template.*`, `project.created`, `project.updated`, `project.opened`,
+    `project.closed`, `project.deleted`, `settings.updated`, `log.*` and `ping`.
     """
 
     from gns3server.api.server import app
@@ -274,7 +284,7 @@ async def controller_http_notifications(request: Request) -> StreamingResponse:
         finally:
             log.info(f"Client {client} has disconnected from controller HTTP notification stream")
 
-    return StreamingResponse(event_stream(), media_type="application/json")
+    return StreamingResponse(event_stream(), media_type=NDJSON_MEDIA_TYPE)
 
 
 @router.websocket("/notifications/ws")
@@ -282,7 +292,8 @@ async def controller_ws_notifications(
     websocket: WebSocket, current_user: schemas.User = Depends(get_current_active_user_from_websocket)
 ) -> None:
     """
-    Receive project notifications about the controller from WebSocket.
+    Receive controller notifications from a WebSocket, one Notification JSON object per text frame.
+    Same messages as the HTTP stream `/v3/notifications`.
     """
 
     if current_user is None:

gns3server/api/routes/controller/projects.py

@@ -40,6 +40,7 @@ from fastapi.responses import FileResponse, StreamingResponse
 from websockets.exceptions import ConnectionClosed, WebSocketException
 
 from gns3server import schemas
+from gns3server.api.responses import NDJSON_MEDIA_TYPE, NOTIFICATION_STREAM_RESPONSES, NDJSONResponse
 from gns3server.controller import Controller, marker_replay
 from gns3server.controller.controller_error import ControllerBadRequestError, ControllerError
 from gns3server.controller.export_project import export_project as export_controller_project
@@ -523,10 +524,20 @@ async def load_project(path: str = Body(..., embed=True)) -> schemas.Project:
     return project.asdict()
 
 
-@router.get("/{project_id}/notifications", dependencies=[Depends(has_privilege("Project.Audit"))])
+@router.get(
+    "/{project_id}/notifications",
+    dependencies=[Depends(has_privilege("Project.Audit"))],
+    response_class=NDJSONResponse,
+    responses=NOTIFICATION_STREAM_RESPONSES,
+)
 async def project_http_notifications(project_id: UUID) -> StreamingResponse:
     """
-    Receive project notifications about the controller from HTTP stream.
+    Receive project notifications from an HTTP stream of newline delimited JSON objects (see the Notification schema).
+
+    The same messages are available as WebSocket text frames on `/v3/projects/{project_id}/notifications/ws`.
+    Marker events (`marker.match`) are not sent here, they are only available on
+    `/v3/projects/{project_id}/notifications/markers/ws`.
+    Project actions: `node.*`, `link.*`, `drawing.*`, `project.updated`, `snapshot.restored`, `log.*` and `ping`.
 
     Required privilege: Project.Audit
     """
@@ -555,7 +566,7 @@ async def project_http_notifications(project_id: UUID) -> StreamingResponse:
                     log.info(f"Project '{project.id}' is automatically closing due to no client listening")
                     await project.close()
 
-    return StreamingResponse(event_stream(), media_type="application/json")
+    return StreamingResponse(event_stream(), media_type=NDJSON_MEDIA_TYPE)
 
 
 @router.websocket("/{project_id}/notifications/ws")
@@ -565,7 +576,8 @@ async def project_ws_notifications(
     current_user: schemas.User = Depends(has_privilege_on_websocket("Project.Audit")),
 ) -> None:
     """
-    Receive project notifications about the controller from WebSocket.
+    Receive project notifications from a WebSocket, one Notification JSON object per text frame.
+    Same messages as the HTTP stream `/v3/projects/{project_id}/notifications`.
 
     Required privilege: Project.Audit
     """
@@ -603,8 +615,8 @@ async def project_marker_ws_notifications(
     current_user: schemas.User = Depends(has_privilege_on_websocket("Project.Audit")),
 ) -> None:
     """
-    Receive marker notifications (e.g. marker.match) for a project on a
-    dedicated WebSocket, separate from the main project stream so high-frequency
+    Receive marker notifications (`marker.match`, see the Notification schema) for a project on a
+    dedicated WebSocket, one JSON object per text frame, separate from the main project stream so high-frequency
     marker.matches do not block topology events (node.*/link.*).
 
     Required privilege: Project.Audit

gns3server/api/server.py

@@ -76,7 +76,14 @@ def get_application() -> FastAPI:
     application = FastAPI(
         lifespan=tasks.lifespan,
         title="GNS3 controller API",
-        description="This page describes the public controller API for GNS3",
+        description="This page describes the public controller API for GNS3.\n\n"
+        "## Notification streams\n\n"
+        "Notifications are available as HTTP streams of newline delimited JSON objects (`GET /v3/notifications` and "
+        "`GET /v3/projects/{project_id}/notifications`) and as WebSockets sending one JSON object per text frame "
+        "(`/v3/notifications/ws`, `/v3/projects/{project_id}/notifications/ws` and "
+        "`/v3/projects/{project_id}/notifications/markers/ws`). "
+        "OpenAPI cannot describe WebSocket routes, they carry the same `Notification` messages as the HTTP streams. "
+        "Marker events (`marker.match`) are only sent on the markers WebSocket.",
         version="3.0.0",
         docs_url=None,
         redoc_url=None,