feat: add response models for endpoints returning untyped objects

gns3server/api/routes/controller/acl.py

@@ -80,7 +80,11 @@ def _iter_route_paths(routes: Sequence[BaseRoute], prefix: str = "", include_mou
                 yield from _iter_route_paths(mounted_routes, _join_paths(prefix, route.path), include_mounted_routes)
 
 
-@router.get("/endpoints", dependencies=[Depends(has_privilege("ACE.Audit"))])
+@router.get(
+    "/endpoints",
+    response_model=List[schemas.ACEEndpoint],
+    dependencies=[Depends(has_privilege("ACE.Audit"))],
+)
 async def endpoints(
     users_repo: UsersRepository = Depends(get_repository(UsersRepository)),
     rbac_repo: RbacRepository = Depends(get_repository(RbacRepository)),

gns3server/api/routes/controller/api_keys.py

@@ -50,12 +50,12 @@ def _generate_api_key(api_key_id: UUID | None = None) -> tuple[str, str, str, UU
     return raw_key, key_hash, key_prefix, api_key_id
 
 
-@router.post("", status_code=status.HTTP_201_CREATED)
+@router.post("", response_model=schemas.ApiKeyCreated, status_code=status.HTTP_201_CREATED)
 async def create_api_key(
     api_key_data: schemas.ApiKeyCreate,
     current_user: schemas.User = Depends(get_current_active_user),
     api_keys_repo: ApiKeysRepository = Depends(get_repository(ApiKeysRepository)),
-) -> dict:
+) -> schemas.ApiKeyCreated:
     """Create a new API key. The full key is returned only once."""
 
     raw_key, key_hash, key_prefix, new_key_id = _generate_api_key()
@@ -66,42 +66,42 @@ async def create_api_key(
         key_hash=key_hash,
         key_prefix=key_prefix,
     )
-    return {
-        "api_key_id": str(db_key.api_key_id),
-        "api_key": raw_key,
-        "name": db_key.name,
-        "key_prefix": db_key.key_prefix,
-        "created_at": db_key.created_at.isoformat() if db_key.created_at else None,
-    }
+    return schemas.ApiKeyCreated(
+        api_key_id=db_key.api_key_id,
+        api_key=raw_key,
+        name=db_key.name,
+        key_prefix=db_key.key_prefix,
+        created_at=db_key.created_at.isoformat() if db_key.created_at else None,
+    )
 
 
-@router.get("")
+@router.get("", response_model=list[schemas.ApiKey])
 async def list_api_keys(
     current_user: schemas.User = Depends(get_current_active_user),
     api_keys_repo: ApiKeysRepository = Depends(get_repository(ApiKeysRepository)),
-) -> list[dict]:
+) -> list[schemas.ApiKey]:
     """List all API keys for the current user."""
 
     keys = await api_keys_repo.get_api_keys_by_user(current_user.user_id)
     return [
-        {
-            "api_key_id": str(k.api_key_id),
-            "name": k.name,
-            "key_prefix": k.key_prefix,
-            "created_at": k.created_at.isoformat() if k.created_at else None,
-            "last_used_at": k.last_used_at.isoformat() if k.last_used_at else None,
-            "revoked": k.revoked,
-        }
+        schemas.ApiKey(
+            api_key_id=k.api_key_id,
+            name=k.name,
+            key_prefix=k.key_prefix,
+            created_at=k.created_at.isoformat() if k.created_at else None,
+            last_used_at=k.last_used_at.isoformat() if k.last_used_at else None,
+            revoked=k.revoked,
+        )
         for k in keys
     ]
 
 
-@router.post("/{api_key_id}/revoke", status_code=status.HTTP_200_OK)
+@router.post("/{api_key_id}/revoke", response_model=schemas.ApiKeyMessage, status_code=status.HTTP_200_OK)
 async def revoke_api_key(
     api_key_id: UUID,
     current_user: schemas.User = Depends(get_current_active_user),
     api_keys_repo: ApiKeysRepository = Depends(get_repository(ApiKeysRepository)),
-) -> dict:
+) -> schemas.ApiKeyMessage:
     """Revoke an API key. It will immediately stop working, but can be restored."""
 
     key = await api_keys_repo.get_api_key(api_key_id)
@@ -111,15 +111,15 @@ async def revoke_api_key(
         raise HTTPException(status_code=403, detail="Cannot modify another user's API key")
 
     await api_keys_repo.revoke_api_key(api_key_id)
-    return {"message": f"API key '{key.name}' revoked"}
+    return schemas.ApiKeyMessage(message=f"API key '{key.name}' revoked")
 
 
-@router.post("/{api_key_id}/restore", status_code=status.HTTP_200_OK)
+@router.post("/{api_key_id}/restore", response_model=schemas.ApiKeyMessage, status_code=status.HTTP_200_OK)
 async def restore_api_key(
     api_key_id: UUID,
     current_user: schemas.User = Depends(get_current_active_user),
     api_keys_repo: ApiKeysRepository = Depends(get_repository(ApiKeysRepository)),
-) -> dict:
+) -> schemas.ApiKeyMessage:
     """Restore a previously revoked API key."""
 
     key = await api_keys_repo.get_api_key(api_key_id)
@@ -129,7 +129,7 @@ async def restore_api_key(
         raise HTTPException(status_code=403, detail="Cannot modify another user's API key")
 
     await api_keys_repo.restore_api_key(api_key_id)
-    return {"message": f"API key '{key.name}' restored"}
+    return schemas.ApiKeyMessage(message=f"API key '{key.name}' restored")
 
 
 @router.delete("/{api_key_id}", status_code=status.HTTP_204_NO_CONTENT)

gns3server/api/routes/controller/appliances.py

@@ -82,6 +82,8 @@ def get_appliance(appliance_id: UUID) -> schemas.Appliance:
 
 @router.post(
     "/{appliance_id}/version",
+    response_model=schemas.Appliance,
+    response_model_exclude_unset=True,
     status_code=status.HTTP_201_CREATED,
     dependencies=[Depends(has_privilege("Appliance.Allocate"))],
 )

gns3server/api/routes/controller/computes.py

@@ -212,7 +212,7 @@ async def vmware_vms(compute_id: Union[str, UUID]) -> List[schemas.ComputeVMware
     return result
 
 
-@router.post("/{compute_id}/dynamips/auto_idlepc")
+@router.post("/{compute_id}/dynamips/auto_idlepc", response_model=schemas.IdlePC)
 async def dynamips_autoidlepc(compute_id: Union[str, UUID], auto_idle_pc: schemas.AutoIdlePC):
     """
     Find a suitable Idle-PC value for a given IOS image. This may take a few minutes.

gns3server/api/routes/controller/controller.py

@@ -161,7 +161,12 @@ async def update_iou_license(iou_license: schemas.IOULicense) -> schemas.IOULice
     return current_iou_license
 
 
-@router.get("/statistics", dependencies=[Depends(get_current_active_user)])
+@router.get(
+    "/statistics",
+    response_model=schemas.ServerStatistics,
+    response_model_exclude_unset=True,
+    dependencies=[Depends(get_current_active_user)],
+)
 async def statistics() -> dict:
     """
     Return server statistics including compute resources, projects, and nodes.

gns3server/api/routes/controller/gns3vm.py

@@ -30,7 +30,7 @@ from gns3server.controller import Controller
 router = APIRouter()
 
 
-@router.get("/engines")
+@router.get("/engines", response_model=List[schemas.GNS3VMEngineInfo])
 async def get_engines() -> List[dict]:
     """
     Return the list of supported engines for the GNS3VM.
@@ -40,7 +40,7 @@ async def get_engines() -> List[dict]:
     return gns3_vm.engine_list()
 
 
-@router.get("/engines/{engine}/vms")
+@router.get("/engines/{engine}/vms", response_model=List[schemas.GNS3VMInfo])
 async def get_vms(engine: str) -> List[dict]:
     """
     Return all the available VMs for a specific virtualization engine.

gns3server/api/routes/controller/images.py

@@ -327,7 +327,12 @@ async def prune_images(
     )
 
 
-@router.post("/install", status_code=status.HTTP_200_OK, dependencies=[Depends(has_privilege("Image.Allocate"))])
+@router.post(
+    "/install",
+    response_model=schemas.ImageInstallResult,
+    status_code=status.HTTP_200_OK,
+    dependencies=[Depends(has_privilege("Image.Allocate"))],
+)
 async def install_images(
     images_repo: ImagesRepository = Depends(get_repository(ImagesRepository)),
     templates_repo: TemplatesRepository = Depends(get_repository(TemplatesRepository)),

gns3server/api/routes/controller/links.py

@@ -20,7 +20,7 @@ API routes for links.
 
 import logging
 import os
-from typing import Any, List, Union
+from typing import Any, Dict, List, Union
 from uuid import UUID, uuid4
 
 import aiohttp
@@ -123,7 +123,12 @@ async def create_link(project_id: UUID, link_create: schemas.LinkCreate) -> sche
     return link.asdict()
 
 
-@router.get("/{link_id}/available_filters", dependencies=[Depends(has_privilege("Link.Audit"))])
+@router.get(
+    "/{link_id}/available_filters",
+    response_model=List[schemas.LinkFilterInfo],
+    response_model_exclude_unset=True,
+    dependencies=[Depends(has_privilege("Link.Audit"))],
+)
 async def get_filters(link: Link = Depends(dep_link)) -> List[dict]:
     """
     Return all filters available for a given link.
@@ -253,6 +258,7 @@ async def stop_capture(link: Link = Depends(dep_link)) -> None:
 
 @router.post(
     "/{link_id}/capture/wireshark/restart",
+    response_model=schemas.LinkWiresharkRestart,
     status_code=status.HTTP_200_OK,
     dependencies=[Depends(has_privilege("Link.Capture"))],
 )
@@ -405,7 +411,12 @@ async def web_wireshark_websocket(
             pass
 
 
-@router.get("/{link_id}/markers", dependencies=[Depends(has_privilege("Link.Audit"))])
+@router.get(
+    "/{link_id}/markers",
+    response_model=Dict[str, schemas.Marker],
+    response_model_exclude_unset=True,
+    dependencies=[Depends(has_privilege("Link.Audit"))],
+)
 async def get_markers(link: Link = Depends(dep_link)) -> dict:
     """
     Return all traffic-insight markers configured on this link.
@@ -417,7 +428,11 @@ async def get_markers(link: Link = Depends(dep_link)) -> dict:
 
 
 @router.post(
-    "/{link_id}/markers", status_code=status.HTTP_201_CREATED, dependencies=[Depends(has_privilege("Link.Modify"))]
+    "/{link_id}/markers",
+    response_model=schemas.Marker,
+    response_model_exclude_unset=True,
+    status_code=status.HTTP_201_CREATED,
+    dependencies=[Depends(has_privilege("Link.Modify"))],
 )
 async def create_marker(marker_data: schemas.MarkerCreate, link: Link = Depends(dep_link)) -> dict:
     """
@@ -462,7 +477,12 @@ async def delete_marker(marker_name: str, link: Link = Depends(dep_link)) -> Non
     await link.stop_marker(marker_name)
 
 
-@router.put("/{link_id}/markers/{marker_name}", dependencies=[Depends(has_privilege("Link.Modify"))])
+@router.put(
+    "/{link_id}/markers/{marker_name}",
+    response_model=schemas.Marker,
+    response_model_exclude_unset=True,
+    dependencies=[Depends(has_privilege("Link.Modify"))],
+)
 async def update_marker(marker_name: str, marker_data: schemas.MarkerUpdate, link: Link = Depends(dep_link)) -> dict:
     """
     Update a traffic-insight marker (change BPF, tag, or enabled).

gns3server/api/routes/controller/nodes.py

@@ -447,7 +447,11 @@ async def get_node_links(node: Node = Depends(dep_node)) -> List[schemas.Link]:
     return links
 
 
-@router.get("/{node_id}/dynamips/auto_idlepc", dependencies=[Depends(has_privilege("Node.Audit"))])
+@router.get(
+    "/{node_id}/dynamips/auto_idlepc",
+    response_model=schemas.IdlePC,
+    dependencies=[Depends(has_privilege("Node.Audit"))],
+)
 async def auto_idlepc(node: Node = Depends(dep_node)) -> dict:
     """
     Compute an Idle-PC value for a Dynamips node

gns3server/api/routes/controller/projects.py

@@ -31,7 +31,7 @@ import gns3server.utils.zipfile_zstd as zipfile
 
 log = logging.getLogger()
 
-from typing import Any, List, Optional
+from typing import Any, Dict, List, Optional
 from uuid import UUID
 
 from fastapi import APIRouter, Body, Depends, HTTPException, Query, Request, WebSocket, WebSocketDisconnect, status
@@ -199,7 +199,9 @@ async def delete_project(
     await rbac_repo.delete_all_ace_starting_with_path(f"/projects/{project.id}")
 
 
-@router.get("/{project_id}/stats", dependencies=[Depends(has_privilege("Project.Audit"))])
+@router.get(
+    "/{project_id}/stats", response_model=schemas.ProjectStats, dependencies=[Depends(has_privilege("Project.Audit"))]
+)
 def get_project_stats(project: Project = Depends(dep_project)) -> dict:
     """
     Return a project statistics.
@@ -210,7 +212,12 @@ def get_project_stats(project: Project = Depends(dep_project)) -> dict:
     return project.stats()
 
 
-@router.get("/{project_id}/markers", dependencies=[Depends(has_privilege("Project.Audit"))])
+@router.get(
+    "/{project_id}/markers",
+    response_model=Dict[str, schemas.ProjectMarker],
+    response_model_exclude_unset=True,
+    dependencies=[Depends(has_privilege("Project.Audit"))],
+)
 def get_project_markers(project: Project = Depends(dep_project)) -> dict:
     """
     Return all traffic-insight markers across every link in the project.
@@ -241,6 +248,7 @@ async def _replay_response(awaitable):
 
 @router.get(
     "/{project_id}/markers/tags/{tag}/replay/range",
+    response_model=schemas.ReplayTimeline,
     dependencies=[Depends(has_privilege("Project.Audit"))],
 )
 async def replay_tag_range(
@@ -281,6 +289,7 @@ async def replay_tag_range(
 
 @router.get(
     "/{project_id}/markers/tags/{tag}/replay/frames",
+    response_model=schemas.ReplayFrames,
     dependencies=[Depends(has_privilege("Project.Audit"))],
 )
 async def replay_tag_frames(
@@ -321,6 +330,8 @@ async def replay_tag_frames(
 
 @router.get(
     "/{project_id}/markers/tags/{tag}/replay/frame/detail",
+    response_model=schemas.ReplayFrameDetail,
+    response_model_exclude_unset=True,
     dependencies=[Depends(has_privilege("Project.Audit"))],
 )
 async def replay_tag_frame_detail(
@@ -359,7 +370,12 @@ async def replay_tag_frame_detail(
 # ---------------------------------------------------------------------------
 
 
-@router.get("/{project_id}/marker-definitions", dependencies=[Depends(has_privilege("Project.Audit"))])
+@router.get(
+    "/{project_id}/marker-definitions",
+    response_model=Dict[str, schemas.MarkerDefinitionWithLinks],
+    response_model_exclude_unset=True,
+    dependencies=[Depends(has_privilege("Project.Audit"))],
+)
 def get_marker_definitions(project: Project = Depends(dep_project)) -> dict:
     """
     Return all project-level marker definitions with their bound link IDs.
@@ -381,6 +397,8 @@ def get_marker_definitions(project: Project = Depends(dep_project)) -> dict:
 
 @router.post(
     "/{project_id}/marker-definitions",
+    response_model=schemas.MarkerDefinition,
+    response_model_exclude_unset=True,
     status_code=status.HTTP_201_CREATED,
     dependencies=[Depends(has_privilege("Project.Modify"))],
 )
@@ -408,7 +426,12 @@ async def create_marker_definition(
     return project.marker_definitions.get(name, {})
 
 
-@router.put("/{project_id}/marker-definitions/{def_name}", dependencies=[Depends(has_privilege("Project.Modify"))])
+@router.put(
+    "/{project_id}/marker-definitions/{def_name}",
+    response_model=schemas.MarkerDefinition,
+    response_model_exclude_unset=True,
+    dependencies=[Depends(has_privilege("Project.Modify"))],
+)
 async def update_marker_definition(
     def_name: str, def_data: schemas.MarkerDefinitionCreate, project: Project = Depends(dep_project)
 ) -> dict:

gns3server/api/routes/controller/symbols.py

@@ -21,7 +21,7 @@ API routes for symbols.
 
 import logging
 import os
-from typing import List
+from typing import Dict, List
 
 from fastapi import APIRouter, Depends, Request, Response, status
 from fastapi.responses import FileResponse
@@ -39,7 +39,7 @@ log = logging.getLogger(__name__)
 router = APIRouter()
 
 
-@router.get("", dependencies=[Depends(has_privilege("Symbol.Audit"))])
+@router.get("", response_model=List[schemas.SymbolInfo], dependencies=[Depends(has_privilege("Symbol.Audit"))])
 def get_symbols() -> List[dict]:
     """
     Return all symbols.
@@ -78,6 +78,7 @@ async def get_symbol(symbol_id: str, request: Request) -> Response:
 
 @router.get(
     "/{symbol_id:path}/dimensions",
+    response_model=schemas.SymbolDimensions,
     responses={404: {"model": schemas.ErrorMessage, "description": "Could not find symbol"}},
     dependencies=[Depends(has_privilege("Symbol.Audit"))],
 )
@@ -97,7 +98,11 @@ async def get_symbol_dimensions(symbol_id: str) -> dict:
         raise ControllerNotFoundError(f"Could not get symbol file: {e}")
 
 
-@router.get("/default_symbols", dependencies=[Depends(has_privilege("Symbol.Audit"))])
+@router.get(
+    "/default_symbols",
+    response_model=Dict[str, Dict[str, str]],
+    dependencies=[Depends(has_privilege("Symbol.Audit"))],
+)
 def get_default_symbols() -> dict:
     """
     Return all default symbols.

gns3server/schemas/__init__.py

@@ -26,10 +26,20 @@ from .controller.computes import (
     ComputeUpdate,
     ComputeVirtualBoxVM,
     ComputeVMwareVM,
+    IdlePC,
 )
 from .controller.drawings import Drawing
-from .controller.gns3vm import GNS3VM
-from .controller.images import Image, ImageSyncJob, ImageSyncRequest, ImageType, ImageUpload
+from .controller.gns3vm import GNS3VM, GNS3VMEngineInfo, GNS3VMInfo
+from .controller.images import (
+    Image,
+    ImageInstallCreated,
+    ImageInstallResult,
+    ImageInstallSkipped,
+    ImageSyncJob,
+    ImageSyncRequest,
+    ImageType,
+    ImageUpload,
+)
 
 # Controller schemas
 from .controller.links import (
@@ -37,10 +47,17 @@ from .controller.links import (
     Link,
     LinkCapture,
     LinkCreate,
+    LinkFilterInfo,
+    LinkFilterParameter,
     LinkUpdate,
+    LinkWiresharkRestart,
+    Marker,
     MarkerCreate,
+    MarkerDefinition,
     MarkerDefinitionCreate,
+    MarkerDefinitionWithLinks,
     MarkerUpdate,
+    ProjectMarker,
     UDPPortInfo,
 )
 from .controller.nodes import Node, NodeCapture, NodeCreate, NodeDuplicate, NodeUpdate
@@ -51,6 +68,7 @@ from .controller.projects import (
     ProjectCreate,
     ProjectDuplicate,
     ProjectFile,
+    ProjectStats,
     ProjectUpdate,
 )
 from .controller.templates import Template, TemplateCreate, TemplateUpdate, TemplateUsage
@@ -108,11 +126,31 @@ from .compute.vmware_nodes import VMware, VMwareCreate, VMwareUpdate
 from .compute.vpcs_nodes import VPCS, VPCSCreate, VPCSUpdate
 from .controller.capabilities import Capabilities
 from .controller.iou_license import IOULicense
+from .controller.marker_replay import (
+    ReplayFrame,
+    ReplayFrameDetail,
+    ReplayFrames,
+    ReplayFrameSource,
+    ReplaySource,
+    ReplayTimeline,
+    ReplayTreeNode,
+)
 from .controller.netmiko import NetmikoDeviceType, NetmikoDeviceTypeList
 from .controller.pools import Resource, ResourceCreate, ResourcePool, ResourcePoolCreate, ResourcePoolUpdate
-from .controller.rbac import ACE, ACECreate, ACEUpdate, Privilege, Role, RoleCreate, RoleUpdate
+from .controller.rbac import ACE, ACECreate, ACEEndpoint, ACEUpdate, Privilege, Role, RoleCreate, RoleUpdate
 from .controller.settings import SettingsResponse, SettingsUpdate, SettingsUpdateResponse
 from .controller.snapshots import Snapshot, SnapshotCreate
+from .controller.statistics import (
+    ComputeStatistics,
+    ComputeStatisticsEntry,
+    LinkStatistics,
+    NodeStatistics,
+    ProjectCountStatistics,
+    ServerStatistics,
+    WebWiresharkContainer,
+    WebWiresharkStatistics,
+)
+from .controller.symbols import SymbolDimensions, SymbolInfo
 from .controller.templates.cloud_templates import CloudTemplate, CloudTemplateUpdate
 from .controller.templates.docker_templates import DockerTemplate, DockerTemplateUpdate
 from .controller.templates.dynamips_templates import (
@@ -141,7 +179,7 @@ from .controller.templates.vmware_templates import VMwareTemplate, VMwareTemplat
 
 # Controller template schemas
 from .controller.templates.vpcs_templates import VPCSTemplate, VPCSTemplateUpdate
-from .controller.tokens import ApiKeyCreate, RefreshTokenRequest, Token
+from .controller.tokens import ApiKey, ApiKeyCreate, ApiKeyCreated, ApiKeyMessage, RefreshTokenRequest, Token
 
 # Schemas for both controller and compute
 from .qemu_disk_image import QemuDiskImageCreate, QemuDiskImageFormat, QemuDiskImageUpdate
@@ -155,11 +193,15 @@ __all__ = [
     "UDPNIO",
     "VPCS",
     "ACECreate",
+    "ACEEndpoint",
     "ACEUpdate",
     "ATMSwitch",
     "ATMSwitchCreate",
     "ATMSwitchUpdate",
+    "ApiKey",
     "ApiKeyCreate",
+    "ApiKeyCreated",
+    "ApiKeyMessage",
     "Appliance",
     "ApplianceVersion",
     "ApplianceVersionV8",
@@ -192,6 +234,8 @@ __all__ = [
     "Compute",
     "ComputeCreate",
     "ComputeDockerImage",
+    "ComputeStatistics",
+    "ComputeStatisticsEntry",
     "ComputeUpdate",
     "ComputeVMwareVM",
     "ComputeVirtualBoxVM",
@@ -223,13 +267,19 @@ __all__ = [
     "FrameRelaySwitch",
     "FrameRelaySwitchCreate",
     "FrameRelaySwitchUpdate",
+    "GNS3VMEngineInfo",
+    "GNS3VMInfo",
     "IOUCreate",
     "IOULicense",
     "IOUStart",
     "IOUTemplate",
     "IOUTemplateUpdate",
     "IOUUpdate",
+    "IdlePC",
     "Image",
+    "ImageInstallCreated",
+    "ImageInstallResult",
+    "ImageInstallSkipped",
     "ImageSyncJob",
     "ImageSyncRequest",
     "ImageType",
@@ -244,10 +294,17 @@ __all__ = [
     "Link",
     "LinkCapture",
     "LinkCreate",
+    "LinkFilterInfo",
+    "LinkFilterParameter",
+    "LinkStatistics",
     "LinkUpdate",
+    "LinkWiresharkRestart",
     "LoggedInUserUpdate",
+    "Marker",
     "MarkerCreate",
+    "MarkerDefinition",
     "MarkerDefinitionCreate",
+    "MarkerDefinitionWithLinks",
     "MarkerRebuild",
     "MarkerToggle",
     "MarkerUpdate",
@@ -260,15 +317,19 @@ __all__ = [
     "NodeCreate",
     "NodeDuplicate",
     "NodeFile",
+    "NodeStatistics",
     "NodeUpdate",
     "OpenAIMessage",
     "OpenAIToolCall",
     "Privilege",
     "Project",
     "ProjectCompression",
+    "ProjectCountStatistics",
     "ProjectCreate",
     "ProjectDuplicate",
     "ProjectFile",
+    "ProjectMarker",
+    "ProjectStats",
     "ProjectUpdate",
     "Qemu",
     "QemuCreate",
@@ -280,6 +341,13 @@ __all__ = [
     "QemuUpdate",
     "RefreshTokenRequest",
     "RenameSession",
+    "ReplayFrame",
+    "ReplayFrameDetail",
+    "ReplayFrameSource",
+    "ReplayFrames",
+    "ReplaySource",
+    "ReplayTimeline",
+    "ReplayTreeNode",
     "Resource",
     "ResourceCreate",
     "ResourcePool",
@@ -289,11 +357,14 @@ __all__ = [
     "RoleCreate",
     "RoleUpdate",
     "ServerConfig",
+    "ServerStatistics",
     "SettingsResponse",
     "SettingsUpdate",
     "SettingsUpdateResponse",
     "Snapshot",
     "SnapshotCreate",
+    "SymbolDimensions",
+    "SymbolInfo",
     "Template",
     "TemplateCreate",
     "TemplateUpdate",
@@ -321,4 +392,6 @@ __all__ = [
     "VirtualBoxTemplate",
     "VirtualBoxTemplateUpdate",
     "VirtualBoxUpdate",
+    "WebWiresharkContainer",
+    "WebWiresharkStatistics",
 ]

gns3server/schemas/controller/computes.py

@@ -161,3 +161,11 @@ class AutoIdlePC(BaseModel):
     model_config = ConfigDict(
         json_schema_extra={"example": {"platform": "c7200", "image": "/path/to/c7200_image.bin", "ram": 256}}
     )
+
+
+class IdlePC(BaseModel):
+    """
+    Result of an Idle-PC computation.
+    """
+
+    idlepc: Optional[str] = Field(None, description="Idle-PC value, null when none was found")

gns3server/schemas/controller/gns3vm.py

@@ -55,3 +55,24 @@ class GNS3VM(BaseModel):
     vcpus: Optional[int] = Field(None, description="Number of CPUs to allocate for the GNS3 VM")
     ram: Optional[int] = Field(None, description="Amount of memory to allocate for the GNS3 VM")
     port: Optional[int] = Field(None, gt=0, le=65535)
+
+
+class GNS3VMEngineInfo(BaseModel):
+    """
+    A virtualization engine supported by the GNS3 VM.
+    """
+
+    engine_id: str = Field(..., description="Engine identifier")
+    name: str = Field(..., description="Engine display name")
+    description: str = Field(..., description="Engine description (may contain HTML)")
+    support_when_exit: bool = Field(..., description="The engine supports the 'when exit' action")
+    support_headless: bool = Field(..., description="The engine supports headless mode")
+    support_ram: bool = Field(..., description="The engine supports RAM and vCPUs allocation")
+
+
+class GNS3VMInfo(BaseModel):
+    """
+    A virtual machine available on a virtualization engine.
+    """
+
+    vmname: str = Field(..., description="Virtual machine name")

gns3server/schemas/controller/images.py

@@ -16,7 +16,8 @@
 
 from datetime import datetime
 from enum import Enum
-from typing import Annotated, Literal, Optional
+from typing import Annotated, List, Literal, Optional
+from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -100,3 +101,32 @@ class ImageCompatibility(BaseModel):
 class ImageCompatibilityCatalog(BaseModel):
     image_sizes: list[int]
     has_unknown_sizes: bool
+
+
+class ImageInstallCreated(BaseModel):
+    """
+    A template created from an image by the automatic installation.
+    """
+
+    template_id: UUID
+    name: Optional[str] = None
+    version: Optional[str] = None
+    template_type: Optional[str] = None
+
+
+class ImageInstallSkipped(BaseModel):
+    """
+    An image or template that the automatic installation skipped.
+    """
+
+    name: Optional[str] = None
+    reason: str
+
+
+class ImageInstallResult(BaseModel):
+    """
+    Result of the automatic template installation from images.
+    """
+
+    created: List[ImageInstallCreated]
+    skipped: List[ImageInstallSkipped]

gns3server/schemas/controller/links.py

@@ -274,3 +274,81 @@ class MarkerDefinitionCreate(BaseModel):
     @classmethod
     def _both_to_none(cls, v):
         return None if v == "both" else v
+
+
+class Marker(BaseModel):
+    """
+    A traffic-insight marker attached to a link.
+    """
+
+    bpf: str = Field(..., description="libpcap BPF expression")
+    tag: Optional[int] = Field(None, description="Correlation id shared by markers replayed together")
+    enabled: bool = Field(True, description="Whether the marker is capturing")
+    color: Optional[str] = Field(None, description="Hex color used by the Web UI")
+    highlight_duration: Optional[int] = Field(None, description="Web UI highlight duration in milliseconds")
+    capture_node_id: Optional[str] = Field(None, description="Node whose uBridge hosts the marker")
+    direction: Optional[str] = Field(None, description="'tx' or 'rx', null for both directions")
+    data_link_type: Optional[str] = Field(None, description="pcap link-layer type of the capture file")
+    inherited_from: Optional[str] = Field(None, description="Project marker definition this marker was copied from")
+
+
+class ProjectMarker(Marker):
+    """
+    A marker in the project-wide aggregation, with the link and node it belongs to.
+    """
+
+    link_id: str
+    node_id: Optional[str] = None
+
+
+class MarkerDefinition(BaseModel):
+    """
+    A project-level marker definition inherited by every link.
+    """
+
+    bpf: str = Field(..., description="libpcap BPF expression")
+    tag: Optional[int] = Field(None, description="Correlation id shared by markers replayed together")
+    direction: Optional[str] = Field(None, description="'tx' or 'rx', null for both directions")
+    color: Optional[str] = Field(None, description="Hex color used by the Web UI")
+    highlight_duration: Optional[int] = Field(None, description="Web UI highlight duration in milliseconds")
+    data_link_type: Optional[str] = Field(None, description="pcap link-layer type of inherited markers")
+    paused: bool = Field(False, description="Whether the inherited markers are paused")
+
+
+class MarkerDefinitionWithLinks(MarkerDefinition):
+    """
+    A project-level marker definition with the links currently carrying a copy of it.
+    """
+
+    link_ids: List[str] = Field(..., description="Links carrying an inherited copy of the definition")
+
+
+class LinkWiresharkRestart(BaseModel):
+    """
+    Result of restarting the Wireshark window of a link capture.
+    """
+
+    status: str
+
+
+class LinkFilterParameter(BaseModel):
+    """
+    A parameter of a packet filter.
+    """
+
+    name: str
+    type: str
+    minimum: Optional[int] = None
+    maximum: Optional[int] = None
+    unit: Optional[str] = None
+
+
+class LinkFilterInfo(BaseModel):
+    """
+    A packet filter that can be applied to a link.
+    """
+
+    type: str = Field(..., description="Filter identifier used as key in the link 'filters' property")
+    name: str
+    description: str
+    parameters: List[LinkFilterParameter]

gns3server/schemas/controller/marker_replay.py

@@ -0,0 +1,114 @@
+#
+# 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 List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ReplaySource(BaseModel):
+    """
+    A capture source (one marker pcap) of a replay tag.
+    """
+
+    node_id: str
+    link_id: str
+    marker: str
+    data_link_type: str
+    count: int = Field(..., description="Total frames in the capture, unaffected by filters")
+
+
+class ReplayFrame(BaseModel):
+    """
+    One frame of the merged replay timeline.
+    """
+
+    ts: str = Field(..., description="Timestamp string to send back unchanged")
+    len: int = Field(..., description="Captured length in bytes")
+    node_id: str
+    link_id: str
+    marker: str
+    frame_number: int = Field(..., description="1-based frame number in the source pcap")
+    src: Optional[str] = None
+    dst: Optional[str] = None
+    proto: Optional[str] = None
+    info: Optional[str] = None
+    bg: Optional[str] = Field(None, description="Wireshark coloring rule background")
+    fg: Optional[str] = Field(None, description="Wireshark coloring rule foreground")
+
+
+class ReplayTimeline(BaseModel):
+    """
+    Replay timeline of a tag.
+    """
+
+    tag: int
+    start: Optional[str] = Field(None, description="Timestamp of the first matching frame")
+    end: Optional[str] = Field(None, description="Timestamp of the last matching frame")
+    frame_count: int
+    sources: List[ReplaySource]
+    frames: List[ReplayFrame]
+
+
+class ReplayFrames(BaseModel):
+    """
+    Frames of a replay time window.
+    """
+
+    frames: List[ReplayFrame]
+
+
+class ReplayFrameSource(BaseModel):
+    """
+    The source pcap and frame a decoded frame comes from.
+    """
+
+    node_id: str
+    link_id: str
+    marker: str
+    frame_number: int
+
+
+class ReplayTreeNode(BaseModel):
+    """
+    A node of the decoded protocol tree.
+
+    Keys sharkd adds in the future are passed through unchanged.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    element: Optional[str] = Field(None, description="Node type")
+    label: Optional[str] = Field(None, description="Display text")
+    name: Optional[str] = Field(None, description="Field name, e.g. 'ip.ttl'")
+    filter_expr: Optional[str] = Field(None, description="Display filter with the value baked in")
+    pos: Optional[int] = Field(None, description="Byte offset for hex highlighting")
+    size: Optional[int] = Field(None, description="Byte length for hex highlighting")
+    expert: Optional[str] = Field(None, description="Expert severity")
+    generated: Optional[bool] = Field(None, description="Generated by Wireshark")
+    children: Optional[List["ReplayTreeNode"]] = Field(None, description="Nested fields")
+
+
+class ReplayFrameDetail(BaseModel):
+    """
+    One decoded frame.
+    """
+
+    ts: str
+    source: ReplayFrameSource
+    field_count: int
+    hex: str = Field(..., description="Raw frame bytes as hex")
+    tree: List[ReplayTreeNode]

gns3server/schemas/controller/projects.py

@@ -126,3 +126,15 @@ class ProjectCompression(str, Enum):
     bzip2 = "bzip2"
     lzma = "lzma"
     zstd = "zstd"
+
+
+class ProjectStats(BaseModel):
+    """
+    Project object counts.
+    """
+
+    nodes: int
+    links: int
+    drawings: int
+    snapshots: int
+    markers: int

gns3server/schemas/controller/rbac.py

@@ -109,3 +109,13 @@ class Role(DateTimeModelMixin, RoleBase):
     is_builtin: bool
     privileges: List[Privilege]
     model_config = ConfigDict(from_attributes=True)
+
+
+class ACEEndpoint(BaseModel):
+    """
+    An endpoint that can be used in an ACL entry.
+    """
+
+    endpoint: str = Field(..., description="Endpoint path to use as the ACE path")
+    name: str = Field(..., description="Human readable name of the endpoint")
+    endpoint_type: str = Field(..., description="Kind of resource the endpoint refers to")

gns3server/schemas/controller/statistics.py

@@ -0,0 +1,131 @@
+#
+# 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 Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field
+
+
+class ComputeStatistics(BaseModel):
+    """
+    Resource usage reported by a compute.
+
+    Fields come from the compute itself, so a compute running another build
+    may omit some of them.
+    """
+
+    memory_total: Optional[int] = None
+    memory_free: Optional[int] = None
+    memory_used: Optional[int] = None
+    swap_total: Optional[int] = None
+    swap_free: Optional[int] = None
+    swap_used: Optional[int] = None
+    cpu_usage_percent: Optional[int] = None
+    cpu_count: Optional[int] = None
+    cpu_count_physical: Optional[int] = None
+    cpu_model: Optional[str] = None
+    memory_usage_percent: Optional[int] = None
+    swap_usage_percent: Optional[int] = None
+    disk_usage_percent: Optional[int] = None
+    disk_total: Optional[int] = None
+    disk_used: Optional[int] = None
+    disk_free: Optional[int] = None
+    load_average: Optional[List[float]] = None
+    load_average_percent: Optional[List[float]] = None
+
+
+class ComputeStatisticsEntry(BaseModel):
+    """
+    Statistics of one compute.
+    """
+
+    compute_id: str
+    compute_name: str
+    statistics: ComputeStatistics
+
+
+class ProjectCountStatistics(BaseModel):
+    """
+    Project counts by status.
+    """
+
+    total: int
+    opened: int
+    closed: int
+
+
+class NodeStatistics(BaseModel):
+    """
+    Node counts across all projects.
+    """
+
+    total: int
+    open_project_nodes: int
+    closed_project_nodes: int
+    by_type: Dict[str, int] = Field(..., description="Node count by node type")
+    by_status: Dict[str, int] = Field(..., description="Node count by status, open projects only")
+
+
+class LinkStatistics(BaseModel):
+    """
+    Link counts across all projects.
+    """
+
+    total: int
+    capturing: int
+
+
+class WebWiresharkContainer(BaseModel):
+    """
+    A Web Wireshark container.
+    """
+
+    project_id: str
+    project_name: str
+    container_id: str
+    status: str
+    running: bool
+    active_sessions: Optional[int] = None
+    memory_limit: Optional[str] = None
+    cpu_limit: Optional[str] = None
+    pids_limit: Optional[Union[int, str]] = Field(None, description="Process limit, or 'unlimited'")
+    memory: Optional[str] = Field(None, description="Current memory usage")
+    cpu: Optional[str] = Field(None, description="Current CPU usage")
+    pids: Optional[int] = Field(None, description="Current process count")
+
+
+class WebWiresharkStatistics(BaseModel):
+    """
+    Web Wireshark container statistics across all opened projects.
+    """
+
+    total_containers: int
+    running_containers: int
+    active_sessions: int
+    containers: List[WebWiresharkContainer]
+
+
+class ServerStatistics(BaseModel):
+    """
+    Server statistics.
+    """
+
+    uptime_seconds: int
+    computes: List[ComputeStatisticsEntry]
+    projects: ProjectCountStatistics
+    nodes: NodeStatistics
+    links: LinkStatistics
+    webwireshark: WebWiresharkStatistics

gns3server/schemas/controller/symbols.py

@@ -0,0 +1,37 @@
+#
+# 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 pydantic import BaseModel
+
+
+class SymbolInfo(BaseModel):
+    """
+    A symbol available on the controller.
+    """
+
+    symbol_id: str
+    filename: str
+    theme: str
+    builtin: bool
+
+
+class SymbolDimensions(BaseModel):
+    """
+    Symbol dimensions in pixels.
+    """
+
+    width: int
+    height: int

gns3server/schemas/controller/tokens.py

@@ -15,6 +15,7 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 from typing import Optional
+from uuid import UUID
 
 from pydantic import BaseModel
 
@@ -41,3 +42,30 @@ class ApiKeyCreate(BaseModel):
     """Schema for creating a new API key."""
 
     name: str
+
+
+class ApiKey(BaseModel):
+    """API key metadata. The secret is never returned after creation."""
+
+    api_key_id: UUID
+    name: str
+    key_prefix: str
+    created_at: Optional[str] = None
+    last_used_at: Optional[str] = None
+    revoked: bool
+
+
+class ApiKeyCreated(BaseModel):
+    """A newly created API key. The full key is returned only once."""
+
+    api_key_id: UUID
+    api_key: str
+    name: str
+    key_prefix: str
+    created_at: Optional[str] = None
+
+
+class ApiKeyMessage(BaseModel):
+    """Confirmation message returned when an API key is revoked or restored."""
+
+    message: str