cameleer-server/ui/src/api/openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Cameleer3 Server API",
    "version": "1.0"
  },
  "servers": [],
  "security": [
    {
      "bearer": []
    }
  ],
  "tags": [
    {
      "name": "Agent SSE",
      "description": "Server-Sent Events endpoint for agent communication"
    },
    {
      "name": "Agent Commands",
      "description": "Command push endpoints for agent communication"
    },
    {
      "name": "User Admin",
      "description": "User management (ADMIN only)"
    },
    {
      "name": "Agent Management",
      "description": "Agent registration and lifecycle endpoints"
    },
    {
      "name": "Ingestion",
      "description": "Data ingestion endpoints"
    },
    {
      "name": "Authentication",
      "description": "Login and token refresh endpoints"
    },
    {
      "name": "OIDC Config Admin",
      "description": "OIDC provider configuration (ADMIN only)"
    },
    {
      "name": "Diagrams",
      "description": "Diagram rendering endpoints"
    },
    {
      "name": "Detail",
      "description": "Execution detail and processor snapshot endpoints"
    },
    {
      "name": "Search",
      "description": "Transaction search endpoints"
    }
  ],
  "paths": {
    "/admin/users/{userId}/roles": {
      "put": {
        "tags": [
          "User Admin"
        ],
        "summary": "Update user roles",
        "operationId": "updateRoles",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RolesRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Roles updated"
          },
          "404": {
            "description": "User not found"
          }
        }
      }
    },
    "/admin/oidc": {
      "get": {
        "tags": [
          "OIDC Config Admin"
        ],
        "summary": "Get OIDC configuration",
        "operationId": "getConfig",
        "responses": {
          "200": {
            "description": "Current OIDC configuration (client_secret masked)",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/OidcAdminConfigResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "OIDC Config Admin"
        ],
        "summary": "Save OIDC configuration",
        "operationId": "saveConfig",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OidcAdminConfigRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Configuration saved",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/OidcAdminConfigResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid configuration",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "OIDC Config Admin"
        ],
        "summary": "Delete OIDC configuration",
        "operationId": "deleteConfig",
        "responses": {
          "204": {
            "description": "Configuration deleted"
          }
        }
      }
    },
    "/search/executions": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "Search executions with basic filters",
        "operationId": "searchGet",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "timeFrom",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "timeTo",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "correlationId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "text",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "routeId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "agentId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "processorType",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 50
            }
          },
          {
            "name": "sortField",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sortDir",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResultExecutionSummary"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Search"
        ],
        "summary": "Advanced search with all filters",
        "operationId": "searchPost",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResultExecutionSummary"
                }
              }
            }
          }
        }
      }
    },
    "/data/metrics": {
      "post": {
        "tags": [
          "Ingestion"
        ],
        "summary": "Ingest agent metrics",
        "description": "Accepts an array of MetricsSnapshot objects",
        "operationId": "ingestMetrics",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Data accepted for processing"
          },
          "503": {
            "description": "Buffer full, retry later"
          }
        }
      }
    },
    "/data/executions": {
      "post": {
        "tags": [
          "Ingestion"
        ],
        "summary": "Ingest route execution data",
        "description": "Accepts a single RouteExecution or an array of RouteExecutions",
        "operationId": "ingestExecutions",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Data accepted for processing"
          },
          "503": {
            "description": "Buffer full, retry later"
          }
        }
      }
    },
    "/data/diagrams": {
      "post": {
        "tags": [
          "Ingestion"
        ],
        "summary": "Ingest route diagram data",
        "description": "Accepts a single RouteGraph or an array of RouteGraphs",
        "operationId": "ingestDiagrams",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Data accepted for processing"
          },
          "503": {
            "description": "Buffer full, retry later"
          }
        }
      }
    },
    "/auth/refresh": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Refresh access token",
        "operationId": "refresh",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefreshRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Token refreshed",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid refresh token",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/auth/oidc/callback": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Exchange OIDC authorization code for JWTs",
        "operationId": "callback",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CallbackRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Authentication successful",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "401": {
            "description": "OIDC authentication failed",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Account not provisioned",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "OIDC not configured or disabled",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          }
        }
      }
    },
    "/auth/login": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Login with local credentials",
        "operationId": "login",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Login successful",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid credentials",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{id}/refresh": {
      "post": {
        "tags": [
          "Agent Management"
        ],
        "summary": "Refresh access token",
        "description": "Issues a new access JWT from a valid refresh token",
        "operationId": "refresh_1",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRefreshRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "New access token issued",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRefreshResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or expired refresh token",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRefreshResponse"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRefreshResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{id}/heartbeat": {
      "post": {
        "tags": [
          "Agent Management"
        ],
        "summary": "Agent heartbeat ping",
        "description": "Updates the agent's last heartbeat timestamp",
        "operationId": "heartbeat",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Heartbeat accepted"
          },
          "404": {
            "description": "Agent not registered"
          }
        }
      }
    },
    "/agents/{id}/commands": {
      "post": {
        "tags": [
          "Agent Commands"
        ],
        "summary": "Send command to a specific agent",
        "description": "Sends a config-update, deep-trace, or replay command to the specified agent",
        "operationId": "sendCommand",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CommandRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Command accepted",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/CommandSingleResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid command payload",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/CommandSingleResponse"
                }
              }
            }
          },
          "404": {
            "description": "Agent not registered",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/CommandSingleResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{id}/commands/{commandId}/ack": {
      "post": {
        "tags": [
          "Agent Commands"
        ],
        "summary": "Acknowledge command receipt",
        "description": "Agent acknowledges that it has received and processed a command",
        "operationId": "acknowledgeCommand",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "commandId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Command acknowledged"
          },
          "404": {
            "description": "Command not found"
          }
        }
      }
    },
    "/agents/register": {
      "post": {
        "tags": [
          "Agent Management"
        ],
        "summary": "Register an agent",
        "description": "Registers a new agent or re-registers an existing one. Requires bootstrap token in Authorization header.",
        "operationId": "register",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRegistrationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Agent registered successfully",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRegistrationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid registration payload",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bootstrap token",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRegistrationResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/groups/{group}/commands": {
      "post": {
        "tags": [
          "Agent Commands"
        ],
        "summary": "Send command to all agents in a group",
        "description": "Sends a command to all LIVE agents in the specified group",
        "operationId": "sendGroupCommand",
        "parameters": [
          {
            "name": "group",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CommandRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Commands accepted",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/CommandBroadcastResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid command payload",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/CommandBroadcastResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/commands": {
      "post": {
        "tags": [
          "Agent Commands"
        ],
        "summary": "Broadcast command to all live agents",
        "description": "Sends a command to all agents currently in LIVE state",
        "operationId": "broadcastCommand",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CommandRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Commands accepted",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/CommandBroadcastResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid command payload",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/CommandBroadcastResponse"
                }
              }
            }
          }
        }
      }
    },
    "/admin/oidc/test": {
      "post": {
        "tags": [
          "OIDC Config Admin"
        ],
        "summary": "Test OIDC provider connectivity",
        "operationId": "testConnection",
        "responses": {
          "200": {
            "description": "Provider reachable",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/OidcTestResult"
                }
              }
            }
          },
          "400": {
            "description": "Provider unreachable or misconfigured",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/search/stats": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "Aggregate execution stats (P99 latency, active count)",
        "operationId": "stats",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "routeId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ExecutionStats"
                }
              }
            }
          }
        }
      }
    },
    "/search/stats/timeseries": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "Bucketed time-series stats over a time window",
        "operationId": "timeseries",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "buckets",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 24
            }
          },
          {
            "name": "routeId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/StatsTimeseries"
                }
              }
            }
          }
        }
      }
    },
    "/executions/{executionId}": {
      "get": {
        "tags": [
          "Detail"
        ],
        "summary": "Get execution detail with nested processor tree",
        "operationId": "getDetail",
        "parameters": [
          {
            "name": "executionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Execution detail found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ExecutionDetail"
                }
              }
            }
          },
          "404": {
            "description": "Execution not found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ExecutionDetail"
                }
              }
            }
          }
        }
      }
    },
    "/executions/{executionId}/processors/{index}/snapshot": {
      "get": {
        "tags": [
          "Detail"
        ],
        "summary": "Get exchange snapshot for a specific processor",
        "operationId": "getProcessorSnapshot",
        "parameters": [
          {
            "name": "executionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot data",
            "content": {
              "*/*": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Snapshot not found",
            "content": {
              "*/*": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/diagrams": {
      "get": {
        "tags": [
          "Diagrams"
        ],
        "summary": "Find diagram by application group and route ID",
        "description": "Resolves group to agent IDs and finds the latest diagram for the route",
        "operationId": "findByGroupAndRoute",
        "parameters": [
          {
            "name": "group",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "routeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Diagram layout returned",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/DiagramLayout"
                }
              }
            }
          },
          "404": {
            "description": "No diagram found for the given group and route"
          }
        }
      }
    },
    "/diagrams/{contentHash}/render": {
      "get": {
        "tags": [
          "Diagrams"
        ],
        "summary": "Render a route diagram",
        "description": "Returns SVG (default) or JSON layout based on Accept header",
        "operationId": "renderDiagram",
        "parameters": [
          {
            "name": "contentHash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Diagram rendered successfully",
            "content": {
              "image/svg+xml": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiagramLayout"
                }
              }
            }
          },
          "404": {
            "description": "Diagram not found",
            "content": {
              "*/*": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/auth/oidc/config": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Get OIDC config for SPA login flow",
        "operationId": "getConfig_1",
        "responses": {
          "200": {
            "description": "OIDC configuration",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/OidcPublicConfigResponse"
                }
              }
            }
          },
          "404": {
            "description": "OIDC not configured or disabled",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/OidcPublicConfigResponse"
                }
              }
            }
          },
          "500": {
            "description": "Failed to retrieve OIDC provider metadata",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents": {
      "get": {
        "tags": [
          "Agent Management"
        ],
        "summary": "List all agents",
        "description": "Returns all registered agents, optionally filtered by status and/or group",
        "operationId": "listAgents",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Agent list returned",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AgentInstanceResponse"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid status filter",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{id}/events": {
      "get": {
        "tags": [
          "Agent SSE"
        ],
        "summary": "Open SSE event stream",
        "description": "Opens a Server-Sent Events stream for the specified agent. Commands (config-update, deep-trace, replay) are pushed as events. Ping keepalive comments sent every 15 seconds.",
        "operationId": "events",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Last-Event-ID",
            "in": "header",
            "description": "Last received event ID (no replay, acknowledged only)",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SSE stream opened",
            "content": {
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/SseEmitter"
                }
              }
            }
          },
          "404": {
            "description": "Agent not registered",
            "content": {
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/SseEmitter"
                }
              }
            }
          }
        }
      }
    },
    "/admin/users": {
      "get": {
        "tags": [
          "User Admin"
        ],
        "summary": "List all users",
        "operationId": "listUsers",
        "responses": {
          "200": {
            "description": "User list returned",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/UserInfo"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/admin/users/{userId}": {
      "get": {
        "tags": [
          "User Admin"
        ],
        "summary": "Get user by ID",
        "operationId": "getUser",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/UserInfo"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/UserInfo"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "User Admin"
        ],
        "summary": "Delete user",
        "operationId": "deleteUser",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "User deleted"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RolesRequest": {
        "type": "object",
        "properties": {
          "roles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "OidcAdminConfigRequest": {
        "type": "object",
        "description": "OIDC configuration update request",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "issuerUri": {
            "type": "string"
          },
          "clientId": {
            "type": "string"
          },
          "clientSecret": {
            "type": "string"
          },
          "rolesClaim": {
            "type": "string"
          },
          "defaultRoles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "autoSignup": {
            "type": "boolean"
          },
          "displayNameClaim": {
            "type": "string"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Error response",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      },
      "OidcAdminConfigResponse": {
        "type": "object",
        "description": "OIDC configuration for admin management",
        "properties": {
          "configured": {
            "type": "boolean"
          },
          "enabled": {
            "type": "boolean"
          },
          "issuerUri": {
            "type": "string"
          },
          "clientId": {
            "type": "string"
          },
          "clientSecretSet": {
            "type": "boolean"
          },
          "rolesClaim": {
            "type": "string"
          },
          "defaultRoles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "autoSignup": {
            "type": "boolean"
          },
          "displayNameClaim": {
            "type": "string"
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "timeFrom": {
            "type": "string",
            "format": "date-time"
          },
          "timeTo": {
            "type": "string",
            "format": "date-time"
          },
          "durationMin": {
            "type": "integer",
            "format": "int64"
          },
          "durationMax": {
            "type": "integer",
            "format": "int64"
          },
          "correlationId": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "textInBody": {
            "type": "string"
          },
          "textInHeaders": {
            "type": "string"
          },
          "textInErrors": {
            "type": "string"
          },
          "routeId": {
            "type": "string"
          },
          "agentId": {
            "type": "string"
          },
          "processorType": {
            "type": "string"
          },
          "group": {
            "type": "string"
          },
          "agentIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "offset": {
            "type": "integer",
            "format": "int32"
          },
          "limit": {
            "type": "integer",
            "format": "int32"
          },
          "sortField": {
            "type": "string"
          },
          "sortDir": {
            "type": "string"
          }
        }
      },
      "ExecutionSummary": {
        "type": "object",
        "properties": {
          "executionId": {
            "type": "string"
          },
          "routeId": {
            "type": "string"
          },
          "agentId": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "startTime": {
            "type": "string",
            "format": "date-time"
          },
          "endTime": {
            "type": "string",
            "format": "date-time"
          },
          "durationMs": {
            "type": "integer",
            "format": "int64"
          },
          "correlationId": {
            "type": "string"
          },
          "errorMessage": {
            "type": "string"
          },
          "diagramContentHash": {
            "type": "string"
          }
        },
        "required": [
          "agentId",
          "correlationId",
          "diagramContentHash",
          "durationMs",
          "endTime",
          "errorMessage",
          "executionId",
          "routeId",
          "startTime",
          "status"
        ]
      },
      "SearchResultExecutionSummary": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExecutionSummary"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "offset": {
            "type": "integer",
            "format": "int32"
          },
          "limit": {
            "type": "integer",
            "format": "int32"
          }
        },
        "required": [
          "data",
          "limit",
          "offset",
          "total"
        ]
      },
      "RefreshRequest": {
        "type": "object",
        "properties": {
          "refreshToken": {
            "type": "string"
          }
        }
      },
      "AuthTokenResponse": {
        "type": "object",
        "description": "JWT token pair",
        "properties": {
          "accessToken": {
            "type": "string"
          },
          "refreshToken": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "idToken": {
            "type": "string",
            "description": "OIDC id_token for end-session logout (only present after OIDC login)"
          }
        },
        "required": [
          "accessToken",
          "refreshToken",
          "displayName"
        ]
      },
      "CallbackRequest": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "redirectUri": {
            "type": "string"
          }
        }
      },
      "LoginRequest": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string"
          }
        }
      },
      "AgentRefreshRequest": {
        "type": "object",
        "description": "Agent token refresh request",
        "properties": {
          "refreshToken": {
            "type": "string"
          }
        },
        "required": [
          "refreshToken"
        ]
      },
      "AgentRefreshResponse": {
        "type": "object",
        "description": "Refreshed access token",
        "properties": {
          "accessToken": {
            "type": "string"
          }
        },
        "required": [
          "accessToken"
        ]
      },
      "CommandRequest": {
        "type": "object",
        "description": "Command to send to agent(s)",
        "properties": {
          "type": {
            "type": "string",
            "description": "Command type: config-update, deep-trace, or replay"
          },
          "payload": {
            "type": "object",
            "description": "Command payload JSON"
          }
        },
        "required": [
          "type"
        ]
      },
      "CommandSingleResponse": {
        "type": "object",
        "description": "Result of sending a command to a single agent",
        "properties": {
          "commandId": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "commandId",
          "status"
        ]
      },
      "AgentRegistrationRequest": {
        "type": "object",
        "description": "Agent registration payload",
        "properties": {
          "agentId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "group": {
            "type": "string",
            "default": "default"
          },
          "version": {
            "type": "string"
          },
          "routeIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "capabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "object"
            }
          }
        },
        "required": [
          "agentId",
          "name"
        ]
      },
      "AgentRegistrationResponse": {
        "type": "object",
        "description": "Agent registration result with JWT tokens and SSE endpoint",
        "properties": {
          "agentId": {
            "type": "string"
          },
          "sseEndpoint": {
            "type": "string"
          },
          "heartbeatIntervalMs": {
            "type": "integer",
            "format": "int64"
          },
          "serverPublicKey": {
            "type": "string"
          },
          "accessToken": {
            "type": "string"
          },
          "refreshToken": {
            "type": "string"
          }
        },
        "required": [
          "accessToken",
          "agentId",
          "refreshToken",
          "serverPublicKey",
          "sseEndpoint"
        ]
      },
      "CommandBroadcastResponse": {
        "type": "object",
        "description": "Result of broadcasting a command to multiple agents",
        "properties": {
          "commandIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "targetCount": {
            "type": "integer",
            "format": "int32"
          }
        },
        "required": [
          "commandIds"
        ]
      },
      "OidcTestResult": {
        "type": "object",
        "description": "OIDC provider connectivity test result",
        "properties": {
          "status": {
            "type": "string"
          },
          "authorizationEndpoint": {
            "type": "string"
          }
        },
        "required": [
          "authorizationEndpoint",
          "status"
        ]
      },
      "ExecutionStats": {
        "type": "object",
        "properties": {
          "totalCount": {
            "type": "integer",
            "format": "int64"
          },
          "failedCount": {
            "type": "integer",
            "format": "int64"
          },
          "avgDurationMs": {
            "type": "integer",
            "format": "int64"
          },
          "p99LatencyMs": {
            "type": "integer",
            "format": "int64"
          },
          "activeCount": {
            "type": "integer",
            "format": "int64"
          },
          "totalToday": {
            "type": "integer",
            "format": "int64"
          },
          "prevTotalCount": {
            "type": "integer",
            "format": "int64"
          },
          "prevFailedCount": {
            "type": "integer",
            "format": "int64"
          },
          "prevAvgDurationMs": {
            "type": "integer",
            "format": "int64"
          },
          "prevP99LatencyMs": {
            "type": "integer",
            "format": "int64"
          }
        },
        "required": [
          "activeCount",
          "avgDurationMs",
          "failedCount",
          "p99LatencyMs",
          "prevAvgDurationMs",
          "prevFailedCount",
          "prevP99LatencyMs",
          "prevTotalCount",
          "totalCount",
          "totalToday"
        ]
      },
      "StatsTimeseries": {
        "type": "object",
        "properties": {
          "buckets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TimeseriesBucket"
            }
          }
        },
        "required": [
          "buckets"
        ]
      },
      "TimeseriesBucket": {
        "type": "object",
        "properties": {
          "time": {
            "type": "string",
            "format": "date-time"
          },
          "totalCount": {
            "type": "integer",
            "format": "int64"
          },
          "failedCount": {
            "type": "integer",
            "format": "int64"
          },
          "avgDurationMs": {
            "type": "integer",
            "format": "int64"
          },
          "p99DurationMs": {
            "type": "integer",
            "format": "int64"
          },
          "activeCount": {
            "type": "integer",
            "format": "int64"
          }
        },
        "required": [
          "activeCount",
          "avgDurationMs",
          "failedCount",
          "p99DurationMs",
          "time",
          "totalCount"
        ]
      },
      "ExecutionDetail": {
        "type": "object",
        "properties": {
          "executionId": {
            "type": "string"
          },
          "routeId": {
            "type": "string"
          },
          "agentId": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "startTime": {
            "type": "string",
            "format": "date-time"
          },
          "endTime": {
            "type": "string",
            "format": "date-time"
          },
          "durationMs": {
            "type": "integer",
            "format": "int64"
          },
          "correlationId": {
            "type": "string"
          },
          "exchangeId": {
            "type": "string"
          },
          "errorMessage": {
            "type": "string"
          },
          "errorStackTrace": {
            "type": "string"
          },
          "diagramContentHash": {
            "type": "string"
          },
          "processors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProcessorNode"
            }
          }
        },
        "required": [
          "agentId",
          "correlationId",
          "diagramContentHash",
          "durationMs",
          "endTime",
          "errorMessage",
          "errorStackTrace",
          "exchangeId",
          "executionId",
          "processors",
          "routeId",
          "startTime",
          "status"
        ]
      },
      "ProcessorNode": {
        "type": "object",
        "properties": {
          "processorId": {
            "type": "string"
          },
          "processorType": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "startTime": {
            "type": "string",
            "format": "date-time"
          },
          "endTime": {
            "type": "string",
            "format": "date-time"
          },
          "durationMs": {
            "type": "integer",
            "format": "int64"
          },
          "diagramNodeId": {
            "type": "string"
          },
          "errorMessage": {
            "type": "string"
          },
          "errorStackTrace": {
            "type": "string"
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProcessorNode"
            }
          }
        },
        "required": [
          "children",
          "diagramNodeId",
          "durationMs",
          "endTime",
          "errorMessage",
          "errorStackTrace",
          "processorId",
          "processorType",
          "startTime",
          "status"
        ]
      },
      "DiagramLayout": {
        "type": "object",
        "properties": {
          "width": {
            "type": "number",
            "format": "double"
          },
          "height": {
            "type": "number",
            "format": "double"
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PositionedNode"
            }
          },
          "edges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PositionedEdge"
            }
          }
        }
      },
      "PositionedEdge": {
        "type": "object",
        "properties": {
          "sourceId": {
            "type": "string"
          },
          "targetId": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "points": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "number",
                "format": "double"
              }
            }
          }
        }
      },
      "PositionedNode": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "x": {
            "type": "number",
            "format": "double"
          },
          "y": {
            "type": "number",
            "format": "double"
          },
          "width": {
            "type": "number",
            "format": "double"
          },
          "height": {
            "type": "number",
            "format": "double"
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PositionedNode"
            }
          }
        }
      },
      "OidcPublicConfigResponse": {
        "type": "object",
        "description": "OIDC configuration for SPA login flow",
        "properties": {
          "issuer": {
            "type": "string"
          },
          "clientId": {
            "type": "string"
          },
          "authorizationEndpoint": {
            "type": "string"
          },
          "endSessionEndpoint": {
            "type": "string",
            "description": "Present if the provider supports RP-initiated logout"
          }
        },
        "required": [
          "authorizationEndpoint",
          "clientId",
          "issuer"
        ]
      },
      "AgentInstanceResponse": {
        "type": "object",
        "description": "Agent instance summary",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "group": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "routeIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "registeredAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastHeartbeat": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "group",
          "id",
          "lastHeartbeat",
          "name",
          "registeredAt",
          "routeIds",
          "status"
        ]
      },
      "SseEmitter": {
        "type": "object",
        "properties": {
          "timeout": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "UserInfo": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "createdAt",
          "displayName",
          "email",
          "provider",
          "roles",
          "userId"
        ]
      }
    },
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}