Nyk commited on
Commit
13daa38
·
1 Parent(s): a69dc45

feat: add OpenAPI 3.1 documentation with Scalar UI

Browse files

- Add openapi.json spec covering all 59 API routes (~95 operations)
- Serve spec at GET /api/docs (no auth required, cached)
- Add interactive Scalar API reference UI at /docs
- Allow unauthenticated access to /api/docs and /docs in middleware
- Add @scalar /api-reference-react dependency
- Add 3 E2E tests for spec validation and auth bypass

openapi.json ADDED
@@ -0,0 +1,1695 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "openapi": "3.1.0",
3
+ "info": {
4
+ "title": "Mission Control API",
5
+ "version": "1.2.0",
6
+ "description": "AI Agent Orchestration Platform API"
7
+ },
8
+ "servers": [
9
+ { "url": "/", "description": "Current server" }
10
+ ],
11
+ "security": [
12
+ { "sessionCookie": [] },
13
+ { "apiKey": [] }
14
+ ],
15
+ "tags": [
16
+ { "name": "Auth", "description": "Authentication and user management" },
17
+ { "name": "Agents", "description": "Agent lifecycle and configuration" },
18
+ { "name": "Tasks", "description": "Task management and assignment" },
19
+ { "name": "Chat", "description": "Conversations and messaging" },
20
+ { "name": "Tokens", "description": "Token usage tracking and cost analysis" },
21
+ { "name": "Sessions", "description": "Gateway session management" },
22
+ { "name": "Webhooks", "description": "Webhook configuration and delivery" },
23
+ { "name": "Alerts", "description": "Alert rule management" },
24
+ { "name": "Workflows", "description": "Workflow template management" },
25
+ { "name": "Pipelines", "description": "Pipeline orchestration" },
26
+ { "name": "Monitoring", "description": "Activities, logs, events, and notifications" },
27
+ { "name": "Admin", "description": "System administration and configuration" },
28
+ { "name": "Super Admin", "description": "Multi-tenant provisioning" }
29
+ ],
30
+ "paths": {
31
+ "/api/auth/login": {
32
+ "post": {
33
+ "tags": ["Auth"],
34
+ "summary": "Login with credentials",
35
+ "operationId": "login",
36
+ "security": [],
37
+ "requestBody": {
38
+ "required": true,
39
+ "content": {
40
+ "application/json": {
41
+ "schema": {
42
+ "type": "object",
43
+ "required": ["username", "password"],
44
+ "properties": {
45
+ "username": { "type": "string" },
46
+ "password": { "type": "string" }
47
+ }
48
+ }
49
+ }
50
+ }
51
+ },
52
+ "responses": {
53
+ "200": {
54
+ "description": "Login successful. Sets mc-session cookie.",
55
+ "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } } } } },
56
+ "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "mc-session cookie" } }
57
+ },
58
+ "400": { "$ref": "#/components/responses/BadRequest" },
59
+ "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
60
+ "429": { "$ref": "#/components/responses/RateLimited" }
61
+ }
62
+ }
63
+ },
64
+ "/api/auth/logout": {
65
+ "post": {
66
+ "tags": ["Auth"],
67
+ "summary": "Logout and clear session",
68
+ "operationId": "logout",
69
+ "responses": {
70
+ "200": { "description": "Session cleared" },
71
+ "401": { "$ref": "#/components/responses/Unauthorized" }
72
+ }
73
+ }
74
+ },
75
+ "/api/auth/me": {
76
+ "get": {
77
+ "tags": ["Auth"],
78
+ "summary": "Get current user info",
79
+ "operationId": "getCurrentUser",
80
+ "responses": {
81
+ "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } } } } }, "description": "Current user" },
82
+ "401": { "$ref": "#/components/responses/Unauthorized" }
83
+ }
84
+ }
85
+ },
86
+ "/api/auth/users": {
87
+ "get": {
88
+ "tags": ["Auth"],
89
+ "summary": "List users",
90
+ "operationId": "listUsers",
91
+ "responses": {
92
+ "200": { "description": "User list", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } } } },
93
+ "401": { "$ref": "#/components/responses/Unauthorized" },
94
+ "403": { "$ref": "#/components/responses/Forbidden" }
95
+ }
96
+ },
97
+ "post": {
98
+ "tags": ["Auth"],
99
+ "summary": "Create user",
100
+ "operationId": "createUser",
101
+ "requestBody": {
102
+ "required": true,
103
+ "content": { "application/json": { "schema": { "type": "object", "required": ["username", "password", "role"], "properties": { "username": { "type": "string" }, "password": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string", "enum": ["admin", "operator", "viewer"] }, "email": { "type": "string" } } } } }
104
+ },
105
+ "responses": {
106
+ "201": { "description": "User created", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } } } } } },
107
+ "400": { "$ref": "#/components/responses/BadRequest" },
108
+ "401": { "$ref": "#/components/responses/Unauthorized" },
109
+ "403": { "$ref": "#/components/responses/Forbidden" },
110
+ "409": { "description": "Username already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
111
+ }
112
+ },
113
+ "put": {
114
+ "tags": ["Auth"],
115
+ "summary": "Update user",
116
+ "operationId": "updateUser",
117
+ "requestBody": {
118
+ "required": true,
119
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" }, "role": { "type": "string", "enum": ["admin", "operator", "viewer"] }, "email": { "type": "string" }, "password": { "type": "string" } } } } }
120
+ },
121
+ "responses": {
122
+ "200": { "description": "User updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } } } } } },
123
+ "400": { "$ref": "#/components/responses/BadRequest" },
124
+ "401": { "$ref": "#/components/responses/Unauthorized" },
125
+ "403": { "$ref": "#/components/responses/Forbidden" },
126
+ "404": { "$ref": "#/components/responses/NotFound" }
127
+ }
128
+ },
129
+ "delete": {
130
+ "tags": ["Auth"],
131
+ "summary": "Delete user",
132
+ "operationId": "deleteUser",
133
+ "requestBody": {
134
+ "required": true,
135
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" } } } } }
136
+ },
137
+ "responses": {
138
+ "200": { "description": "User deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
139
+ "401": { "$ref": "#/components/responses/Unauthorized" },
140
+ "403": { "$ref": "#/components/responses/Forbidden" },
141
+ "404": { "$ref": "#/components/responses/NotFound" }
142
+ }
143
+ }
144
+ },
145
+ "/api/auth/access-requests": {
146
+ "get": {
147
+ "tags": ["Auth"],
148
+ "summary": "List access requests",
149
+ "operationId": "listAccessRequests",
150
+ "responses": {
151
+ "200": { "description": "Access request list", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "email": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "approved", "rejected"] }, "created_at": { "type": "integer" } } } } } } } } },
152
+ "401": { "$ref": "#/components/responses/Unauthorized" },
153
+ "403": { "$ref": "#/components/responses/Forbidden" }
154
+ }
155
+ },
156
+ "post": {
157
+ "tags": ["Auth"],
158
+ "summary": "Approve or reject access request",
159
+ "operationId": "handleAccessRequest",
160
+ "requestBody": {
161
+ "required": true,
162
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id", "action"], "properties": { "id": { "type": "integer" }, "action": { "type": "string", "enum": ["approve", "reject"] }, "role": { "type": "string", "enum": ["admin", "operator", "viewer"] } } } } }
163
+ },
164
+ "responses": {
165
+ "200": { "description": "Request processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
166
+ "400": { "$ref": "#/components/responses/BadRequest" },
167
+ "401": { "$ref": "#/components/responses/Unauthorized" },
168
+ "403": { "$ref": "#/components/responses/Forbidden" }
169
+ }
170
+ }
171
+ },
172
+ "/api/auth/google": {
173
+ "get": {
174
+ "tags": ["Auth"],
175
+ "summary": "Google OAuth callback",
176
+ "operationId": "googleOAuthCallback",
177
+ "security": [],
178
+ "parameters": [
179
+ { "name": "code", "in": "query", "schema": { "type": "string" } },
180
+ { "name": "state", "in": "query", "schema": { "type": "string" } }
181
+ ],
182
+ "responses": {
183
+ "302": { "description": "Redirects to dashboard after successful auth" },
184
+ "400": { "$ref": "#/components/responses/BadRequest" }
185
+ }
186
+ }
187
+ },
188
+ "/api/agents": {
189
+ "get": {
190
+ "tags": ["Agents"],
191
+ "summary": "List agents",
192
+ "operationId": "listAgents",
193
+ "parameters": [
194
+ { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["online", "offline", "busy", "idle", "error"] } },
195
+ { "name": "role", "in": "query", "schema": { "type": "string" } },
196
+ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } },
197
+ { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
198
+ ],
199
+ "responses": {
200
+ "200": { "description": "Paginated agent list", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } } },
201
+ "401": { "$ref": "#/components/responses/Unauthorized" }
202
+ }
203
+ },
204
+ "post": {
205
+ "tags": ["Agents"],
206
+ "summary": "Create agent",
207
+ "operationId": "createAgent",
208
+ "requestBody": {
209
+ "required": true,
210
+ "content": { "application/json": { "schema": { "type": "object", "required": ["name", "role"], "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "session_key": { "type": "string" }, "soul_content": { "type": "string" }, "status": { "type": "string", "enum": ["online", "offline", "busy", "idle", "error"], "default": "offline" }, "config": { "type": "object" }, "template": { "type": "string" }, "gateway_config": { "type": "object" }, "write_to_gateway": { "type": "boolean" } } } } }
211
+ },
212
+ "responses": {
213
+ "201": { "description": "Agent created", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/Agent" } } } } } },
214
+ "400": { "$ref": "#/components/responses/BadRequest" },
215
+ "401": { "$ref": "#/components/responses/Unauthorized" },
216
+ "403": { "$ref": "#/components/responses/Forbidden" },
217
+ "409": { "description": "Agent name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
218
+ "429": { "$ref": "#/components/responses/RateLimited" }
219
+ }
220
+ },
221
+ "put": {
222
+ "tags": ["Agents"],
223
+ "summary": "Update agent by name",
224
+ "operationId": "updateAgentByName",
225
+ "requestBody": {
226
+ "required": true,
227
+ "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": ["online", "offline", "busy", "idle", "error"] }, "last_activity": { "type": "string" }, "config": { "type": "object" }, "session_key": { "type": "string" }, "soul_content": { "type": "string" }, "role": { "type": "string" } } } } }
228
+ },
229
+ "responses": {
230
+ "200": { "description": "Agent updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
231
+ "400": { "$ref": "#/components/responses/BadRequest" },
232
+ "401": { "$ref": "#/components/responses/Unauthorized" },
233
+ "403": { "$ref": "#/components/responses/Forbidden" },
234
+ "404": { "$ref": "#/components/responses/NotFound" },
235
+ "429": { "$ref": "#/components/responses/RateLimited" }
236
+ }
237
+ }
238
+ },
239
+ "/api/agents/{id}": {
240
+ "get": {
241
+ "tags": ["Agents"],
242
+ "summary": "Get agent by ID",
243
+ "operationId": "getAgent",
244
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
245
+ "responses": {
246
+ "200": { "description": "Agent details", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/Agent" } } } } } },
247
+ "401": { "$ref": "#/components/responses/Unauthorized" },
248
+ "404": { "$ref": "#/components/responses/NotFound" }
249
+ }
250
+ },
251
+ "put": {
252
+ "tags": ["Agents"],
253
+ "summary": "Update agent by ID",
254
+ "operationId": "updateAgent",
255
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
256
+ "requestBody": {
257
+ "required": true,
258
+ "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "config": { "type": "object" }, "session_key": { "type": "string" }, "soul_content": { "type": "string" } } } } }
259
+ },
260
+ "responses": {
261
+ "200": { "description": "Agent updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/Agent" } } } } } },
262
+ "401": { "$ref": "#/components/responses/Unauthorized" },
263
+ "403": { "$ref": "#/components/responses/Forbidden" },
264
+ "404": { "$ref": "#/components/responses/NotFound" },
265
+ "429": { "$ref": "#/components/responses/RateLimited" }
266
+ }
267
+ },
268
+ "delete": {
269
+ "tags": ["Agents"],
270
+ "summary": "Delete agent",
271
+ "operationId": "deleteAgent",
272
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
273
+ "responses": {
274
+ "200": { "description": "Agent deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
275
+ "401": { "$ref": "#/components/responses/Unauthorized" },
276
+ "403": { "$ref": "#/components/responses/Forbidden" },
277
+ "404": { "$ref": "#/components/responses/NotFound" }
278
+ }
279
+ }
280
+ },
281
+ "/api/agents/{id}/heartbeat": {
282
+ "get": {
283
+ "tags": ["Agents"],
284
+ "summary": "Check agent work items",
285
+ "operationId": "getAgentHeartbeat",
286
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
287
+ "responses": {
288
+ "200": { "description": "Heartbeat data with pending work items", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "pending_tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "messages": { "type": "array", "items": { "type": "object" } } } } } } },
289
+ "401": { "$ref": "#/components/responses/Unauthorized" },
290
+ "404": { "$ref": "#/components/responses/NotFound" }
291
+ }
292
+ },
293
+ "post": {
294
+ "tags": ["Agents"],
295
+ "summary": "Trigger manual heartbeat",
296
+ "operationId": "triggerAgentHeartbeat",
297
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
298
+ "responses": {
299
+ "200": { "description": "Heartbeat triggered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
300
+ "401": { "$ref": "#/components/responses/Unauthorized" },
301
+ "404": { "$ref": "#/components/responses/NotFound" }
302
+ }
303
+ }
304
+ },
305
+ "/api/agents/{id}/soul": {
306
+ "get": {
307
+ "tags": ["Agents"],
308
+ "summary": "Get agent soul config",
309
+ "operationId": "getAgentSoul",
310
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
311
+ "responses": {
312
+ "200": { "description": "Soul configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "soul_content": { "type": "string" } } } } } },
313
+ "401": { "$ref": "#/components/responses/Unauthorized" },
314
+ "404": { "$ref": "#/components/responses/NotFound" }
315
+ }
316
+ },
317
+ "put": {
318
+ "tags": ["Agents"],
319
+ "summary": "Update agent soul config",
320
+ "operationId": "updateAgentSoul",
321
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
322
+ "requestBody": {
323
+ "required": true,
324
+ "content": { "application/json": { "schema": { "type": "object", "required": ["soul_content"], "properties": { "soul_content": { "type": "string" } } } } }
325
+ },
326
+ "responses": {
327
+ "200": { "description": "Soul updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
328
+ "401": { "$ref": "#/components/responses/Unauthorized" },
329
+ "403": { "$ref": "#/components/responses/Forbidden" },
330
+ "404": { "$ref": "#/components/responses/NotFound" }
331
+ }
332
+ }
333
+ },
334
+ "/api/agents/{id}/memory": {
335
+ "get": {
336
+ "tags": ["Agents"],
337
+ "summary": "Get agent memory",
338
+ "operationId": "getAgentMemory",
339
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
340
+ "responses": {
341
+ "200": { "description": "Agent memory data", "content": { "application/json": { "schema": { "type": "object" } } } },
342
+ "401": { "$ref": "#/components/responses/Unauthorized" },
343
+ "404": { "$ref": "#/components/responses/NotFound" }
344
+ }
345
+ },
346
+ "put": {
347
+ "tags": ["Agents"],
348
+ "summary": "Update agent memory",
349
+ "operationId": "updateAgentMemory",
350
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
351
+ "requestBody": {
352
+ "required": true,
353
+ "content": { "application/json": { "schema": { "type": "object" } } }
354
+ },
355
+ "responses": {
356
+ "200": { "description": "Memory updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
357
+ "401": { "$ref": "#/components/responses/Unauthorized" },
358
+ "403": { "$ref": "#/components/responses/Forbidden" },
359
+ "404": { "$ref": "#/components/responses/NotFound" }
360
+ }
361
+ }
362
+ },
363
+ "/api/agents/{id}/wake": {
364
+ "post": {
365
+ "tags": ["Agents"],
366
+ "summary": "Wake an agent",
367
+ "operationId": "wakeAgent",
368
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
369
+ "requestBody": {
370
+ "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } }
371
+ },
372
+ "responses": {
373
+ "200": { "description": "Agent woken", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
374
+ "401": { "$ref": "#/components/responses/Unauthorized" },
375
+ "403": { "$ref": "#/components/responses/Forbidden" },
376
+ "404": { "$ref": "#/components/responses/NotFound" }
377
+ }
378
+ }
379
+ },
380
+ "/api/agents/message": {
381
+ "post": {
382
+ "tags": ["Agents"],
383
+ "summary": "Send message between agents",
384
+ "operationId": "sendAgentMessage",
385
+ "requestBody": {
386
+ "required": true,
387
+ "content": { "application/json": { "schema": { "type": "object", "required": ["from", "to", "content"], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "content": { "type": "string" }, "type": { "type": "string" } } } } }
388
+ },
389
+ "responses": {
390
+ "200": { "description": "Message sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "integer" } } } } } },
391
+ "400": { "$ref": "#/components/responses/BadRequest" },
392
+ "401": { "$ref": "#/components/responses/Unauthorized" },
393
+ "403": { "$ref": "#/components/responses/Forbidden" }
394
+ }
395
+ }
396
+ },
397
+ "/api/agents/comms": {
398
+ "get": {
399
+ "tags": ["Agents"],
400
+ "summary": "Get agent communications",
401
+ "operationId": "getAgentComms",
402
+ "parameters": [
403
+ { "name": "agent", "in": "query", "schema": { "type": "string" } },
404
+ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
405
+ ],
406
+ "responses": {
407
+ "200": { "description": "Agent communication log", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "from_agent": { "type": "string" }, "to_agent": { "type": "string" }, "content": { "type": "string" }, "type": { "type": "string" }, "created_at": { "type": "integer" } } } } } } } } },
408
+ "401": { "$ref": "#/components/responses/Unauthorized" }
409
+ }
410
+ }
411
+ },
412
+ "/api/agents/sync": {
413
+ "post": {
414
+ "tags": ["Agents"],
415
+ "summary": "Sync agents from gateway config",
416
+ "operationId": "syncAgents",
417
+ "responses": {
418
+ "200": { "description": "Sync results", "content": { "application/json": { "schema": { "type": "object", "properties": { "synced": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" } } } } } },
419
+ "401": { "$ref": "#/components/responses/Unauthorized" },
420
+ "403": { "$ref": "#/components/responses/Forbidden" }
421
+ }
422
+ }
423
+ },
424
+ "/api/tasks": {
425
+ "get": {
426
+ "tags": ["Tasks"],
427
+ "summary": "List tasks",
428
+ "operationId": "listTasks",
429
+ "parameters": [
430
+ { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["inbox", "assigned", "in_progress", "quality_review", "done"] } },
431
+ { "name": "assigned_to", "in": "query", "schema": { "type": "string" } },
432
+ { "name": "priority", "in": "query", "schema": { "type": "string", "enum": ["critical", "high", "medium", "low"] } },
433
+ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } },
434
+ { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
435
+ ],
436
+ "responses": {
437
+ "200": { "description": "Paginated task list", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } } },
438
+ "401": { "$ref": "#/components/responses/Unauthorized" }
439
+ }
440
+ },
441
+ "post": {
442
+ "tags": ["Tasks"],
443
+ "summary": "Create task",
444
+ "operationId": "createTask",
445
+ "requestBody": {
446
+ "required": true,
447
+ "content": { "application/json": { "schema": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": ["inbox", "assigned", "in_progress", "quality_review", "done"], "default": "inbox" }, "priority": { "type": "string", "enum": ["critical", "high", "medium", "low"], "default": "medium" }, "assigned_to": { "type": "string" }, "created_by": { "type": "string" }, "due_date": { "type": "string" }, "estimated_hours": { "type": "number" }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" } } } } }
448
+ },
449
+ "responses": {
450
+ "201": { "description": "Task created", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/Task" } } } } } },
451
+ "400": { "$ref": "#/components/responses/BadRequest" },
452
+ "401": { "$ref": "#/components/responses/Unauthorized" },
453
+ "403": { "$ref": "#/components/responses/Forbidden" },
454
+ "409": { "description": "Task title already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
455
+ "429": { "$ref": "#/components/responses/RateLimited" }
456
+ }
457
+ },
458
+ "put": {
459
+ "tags": ["Tasks"],
460
+ "summary": "Bulk update task statuses",
461
+ "operationId": "bulkUpdateTasks",
462
+ "requestBody": {
463
+ "required": true,
464
+ "content": { "application/json": { "schema": { "type": "object", "required": ["tasks"], "properties": { "tasks": { "type": "array", "items": { "type": "object", "required": ["id", "status"], "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": ["inbox", "assigned", "in_progress", "quality_review", "done"] } } } } } } } }
465
+ },
466
+ "responses": {
467
+ "200": { "description": "Tasks updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "updated": { "type": "integer" } } } } } },
468
+ "400": { "$ref": "#/components/responses/BadRequest" },
469
+ "401": { "$ref": "#/components/responses/Unauthorized" },
470
+ "403": { "$ref": "#/components/responses/Forbidden" },
471
+ "429": { "$ref": "#/components/responses/RateLimited" }
472
+ }
473
+ }
474
+ },
475
+ "/api/tasks/{id}": {
476
+ "get": {
477
+ "tags": ["Tasks"],
478
+ "summary": "Get task by ID",
479
+ "operationId": "getTask",
480
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
481
+ "responses": {
482
+ "200": { "description": "Task details", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/Task" } } } } } },
483
+ "401": { "$ref": "#/components/responses/Unauthorized" },
484
+ "404": { "$ref": "#/components/responses/NotFound" }
485
+ }
486
+ },
487
+ "put": {
488
+ "tags": ["Tasks"],
489
+ "summary": "Update task",
490
+ "operationId": "updateTask",
491
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
492
+ "requestBody": {
493
+ "required": true,
494
+ "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "assigned_to": { "type": "string" }, "due_date": { "type": "string" }, "estimated_hours": { "type": "number" }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" } } } } }
495
+ },
496
+ "responses": {
497
+ "200": { "description": "Task updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/Task" } } } } } },
498
+ "401": { "$ref": "#/components/responses/Unauthorized" },
499
+ "403": { "$ref": "#/components/responses/Forbidden" },
500
+ "404": { "$ref": "#/components/responses/NotFound" },
501
+ "429": { "$ref": "#/components/responses/RateLimited" }
502
+ }
503
+ },
504
+ "delete": {
505
+ "tags": ["Tasks"],
506
+ "summary": "Delete task",
507
+ "operationId": "deleteTask",
508
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
509
+ "responses": {
510
+ "200": { "description": "Task deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
511
+ "401": { "$ref": "#/components/responses/Unauthorized" },
512
+ "403": { "$ref": "#/components/responses/Forbidden" },
513
+ "404": { "$ref": "#/components/responses/NotFound" }
514
+ }
515
+ }
516
+ },
517
+ "/api/tasks/{id}/comments": {
518
+ "get": {
519
+ "tags": ["Tasks"],
520
+ "summary": "List task comments",
521
+ "operationId": "listTaskComments",
522
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
523
+ "responses": {
524
+ "200": { "description": "Comment list", "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "task_id": { "type": "integer" }, "author": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "integer" } } } } } } } } },
525
+ "401": { "$ref": "#/components/responses/Unauthorized" },
526
+ "404": { "$ref": "#/components/responses/NotFound" }
527
+ }
528
+ },
529
+ "post": {
530
+ "tags": ["Tasks"],
531
+ "summary": "Add comment to task",
532
+ "operationId": "addTaskComment",
533
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
534
+ "requestBody": {
535
+ "required": true,
536
+ "content": { "application/json": { "schema": { "type": "object", "required": ["content"], "properties": { "content": { "type": "string" }, "author": { "type": "string" } } } } }
537
+ },
538
+ "responses": {
539
+ "201": { "description": "Comment added", "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "object" } } } } } },
540
+ "400": { "$ref": "#/components/responses/BadRequest" },
541
+ "401": { "$ref": "#/components/responses/Unauthorized" },
542
+ "403": { "$ref": "#/components/responses/Forbidden" },
543
+ "404": { "$ref": "#/components/responses/NotFound" }
544
+ }
545
+ }
546
+ },
547
+ "/api/tasks/{id}/broadcast": {
548
+ "post": {
549
+ "tags": ["Tasks"],
550
+ "summary": "Broadcast task to agents",
551
+ "operationId": "broadcastTask",
552
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
553
+ "requestBody": {
554
+ "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } } } } }
555
+ },
556
+ "responses": {
557
+ "200": { "description": "Task broadcast sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "delivered_to": { "type": "array", "items": { "type": "string" } } } } } } },
558
+ "401": { "$ref": "#/components/responses/Unauthorized" },
559
+ "403": { "$ref": "#/components/responses/Forbidden" },
560
+ "404": { "$ref": "#/components/responses/NotFound" }
561
+ }
562
+ }
563
+ },
564
+ "/api/chat/conversations": {
565
+ "get": {
566
+ "tags": ["Chat"],
567
+ "summary": "List conversations",
568
+ "operationId": "listConversations",
569
+ "responses": {
570
+ "200": { "description": "Conversation list", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "participants": { "type": "array", "items": { "type": "string" } }, "last_message": { "type": "string" }, "updated_at": { "type": "integer" } } } } } } } } },
571
+ "401": { "$ref": "#/components/responses/Unauthorized" }
572
+ }
573
+ }
574
+ },
575
+ "/api/chat/messages": {
576
+ "get": {
577
+ "tags": ["Chat"],
578
+ "summary": "List messages",
579
+ "operationId": "listMessages",
580
+ "parameters": [
581
+ { "name": "conversation_id", "in": "query", "schema": { "type": "integer" } },
582
+ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } },
583
+ { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
584
+ ],
585
+ "responses": {
586
+ "200": { "description": "Message list", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "conversation_id": { "type": "integer" }, "sender": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "integer" } } } } } } } } },
587
+ "401": { "$ref": "#/components/responses/Unauthorized" }
588
+ }
589
+ },
590
+ "post": {
591
+ "tags": ["Chat"],
592
+ "summary": "Send message",
593
+ "operationId": "sendMessage",
594
+ "requestBody": {
595
+ "required": true,
596
+ "content": { "application/json": { "schema": { "type": "object", "required": ["content"], "properties": { "conversation_id": { "type": "integer" }, "content": { "type": "string" }, "recipient": { "type": "string" } } } } }
597
+ },
598
+ "responses": {
599
+ "201": { "description": "Message sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object" } } } } } },
600
+ "400": { "$ref": "#/components/responses/BadRequest" },
601
+ "401": { "$ref": "#/components/responses/Unauthorized" },
602
+ "403": { "$ref": "#/components/responses/Forbidden" }
603
+ }
604
+ }
605
+ },
606
+ "/api/chat/messages/{id}": {
607
+ "get": {
608
+ "tags": ["Chat"],
609
+ "summary": "Get message by ID",
610
+ "operationId": "getMessage",
611
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
612
+ "responses": {
613
+ "200": { "description": "Message details", "content": { "application/json": { "schema": { "type": "object" } } } },
614
+ "401": { "$ref": "#/components/responses/Unauthorized" },
615
+ "404": { "$ref": "#/components/responses/NotFound" }
616
+ }
617
+ },
618
+ "delete": {
619
+ "tags": ["Chat"],
620
+ "summary": "Delete message",
621
+ "operationId": "deleteMessage",
622
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
623
+ "responses": {
624
+ "200": { "description": "Message deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
625
+ "401": { "$ref": "#/components/responses/Unauthorized" },
626
+ "403": { "$ref": "#/components/responses/Forbidden" },
627
+ "404": { "$ref": "#/components/responses/NotFound" }
628
+ }
629
+ }
630
+ },
631
+ "/api/tokens": {
632
+ "get": {
633
+ "tags": ["Tokens"],
634
+ "summary": "Query token usage",
635
+ "operationId": "getTokenUsage",
636
+ "parameters": [
637
+ { "name": "action", "in": "query", "schema": { "type": "string", "enum": ["list", "stats", "agent-costs", "export", "trends"], "default": "list" } },
638
+ { "name": "timeframe", "in": "query", "schema": { "type": "string", "enum": ["hour", "day", "week", "month", "all"], "default": "all" } },
639
+ { "name": "format", "in": "query", "description": "Export format (only for action=export)", "schema": { "type": "string", "enum": ["json", "csv"], "default": "json" } }
640
+ ],
641
+ "responses": {
642
+ "200": { "description": "Token usage data. Shape varies by action.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "ListResponse", "properties": { "usage": { "type": "array", "items": { "$ref": "#/components/schemas/TokenUsageRecord" } }, "total": { "type": "integer" }, "timeframe": { "type": "string" } } }, { "type": "object", "title": "StatsResponse", "properties": { "summary": { "$ref": "#/components/schemas/TokenStats" }, "models": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TokenStats" } }, "sessions": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TokenStats" } }, "agents": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TokenStats" } }, "timeframe": { "type": "string" }, "recordCount": { "type": "integer" } } }, { "type": "object", "title": "TrendsResponse", "properties": { "trends": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "tokens": { "type": "integer" }, "cost": { "type": "number" }, "requests": { "type": "integer" } } } }, "timeframe": { "type": "string" } } } ] } } },
643
+ "400": { "$ref": "#/components/responses/BadRequest" },
644
+ "401": { "$ref": "#/components/responses/Unauthorized" }
645
+ }
646
+ },
647
+ "post": {
648
+ "tags": ["Tokens"],
649
+ "summary": "Record token usage",
650
+ "operationId": "recordTokenUsage",
651
+ "requestBody": {
652
+ "required": true,
653
+ "content": { "application/json": { "schema": { "type": "object", "required": ["model", "sessionId", "inputTokens", "outputTokens"], "properties": { "model": { "type": "string" }, "sessionId": { "type": "string" }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "operation": { "type": "string", "default": "chat_completion" }, "duration": { "type": "number" } } } } }
654
+ },
655
+ "responses": {
656
+ "200": { "description": "Usage recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "record": { "$ref": "#/components/schemas/TokenUsageRecord" } } } } } },
657
+ "400": { "$ref": "#/components/responses/BadRequest" },
658
+ "401": { "$ref": "#/components/responses/Unauthorized" },
659
+ "403": { "$ref": "#/components/responses/Forbidden" }
660
+ }
661
+ }
662
+ },
663
+ "/api/sessions": {
664
+ "get": {
665
+ "tags": ["Sessions"],
666
+ "summary": "List gateway sessions",
667
+ "operationId": "listSessions",
668
+ "parameters": [
669
+ { "name": "agent", "in": "query", "schema": { "type": "string" } },
670
+ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
671
+ ],
672
+ "responses": {
673
+ "200": { "description": "Session list", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "agent": { "type": "string" }, "model": { "type": "string" }, "status": { "type": "string" }, "totalTokens": { "type": "integer" }, "updatedAt": { "type": "integer" } } } } } } } } },
674
+ "401": { "$ref": "#/components/responses/Unauthorized" }
675
+ }
676
+ }
677
+ },
678
+ "/api/sessions/{id}/control": {
679
+ "post": {
680
+ "tags": ["Sessions"],
681
+ "summary": "Control session (pause/resume/kill)",
682
+ "operationId": "controlSession",
683
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ],
684
+ "requestBody": {
685
+ "required": true,
686
+ "content": { "application/json": { "schema": { "type": "object", "required": ["action"], "properties": { "action": { "type": "string", "enum": ["pause", "resume", "kill"] } } } } }
687
+ },
688
+ "responses": {
689
+ "200": { "description": "Action applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
690
+ "400": { "$ref": "#/components/responses/BadRequest" },
691
+ "401": { "$ref": "#/components/responses/Unauthorized" },
692
+ "403": { "$ref": "#/components/responses/Forbidden" },
693
+ "404": { "$ref": "#/components/responses/NotFound" }
694
+ }
695
+ }
696
+ },
697
+ "/api/webhooks": {
698
+ "get": {
699
+ "tags": ["Webhooks"],
700
+ "summary": "List webhooks",
701
+ "operationId": "listWebhooks",
702
+ "responses": {
703
+ "200": { "description": "Webhook list with delivery stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } },
704
+ "401": { "$ref": "#/components/responses/Unauthorized" },
705
+ "403": { "$ref": "#/components/responses/Forbidden" }
706
+ }
707
+ },
708
+ "post": {
709
+ "tags": ["Webhooks"],
710
+ "summary": "Create webhook",
711
+ "operationId": "createWebhook",
712
+ "requestBody": {
713
+ "required": true,
714
+ "content": { "application/json": { "schema": { "type": "object", "required": ["name", "url"], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "generate_secret": { "type": "boolean", "default": true } } } } }
715
+ },
716
+ "responses": {
717
+ "200": { "description": "Webhook created. Secret is only shown in full on creation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "secret": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "message": { "type": "string" } } } } } },
718
+ "400": { "$ref": "#/components/responses/BadRequest" },
719
+ "401": { "$ref": "#/components/responses/Unauthorized" },
720
+ "403": { "$ref": "#/components/responses/Forbidden" },
721
+ "429": { "$ref": "#/components/responses/RateLimited" }
722
+ }
723
+ },
724
+ "put": {
725
+ "tags": ["Webhooks"],
726
+ "summary": "Update webhook",
727
+ "operationId": "updateWebhook",
728
+ "requestBody": {
729
+ "required": true,
730
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "regenerate_secret": { "type": "boolean" } } } } }
731
+ },
732
+ "responses": {
733
+ "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "secret": { "type": "string", "description": "Only present when regenerate_secret is true" }, "message": { "type": "string" } } } } } },
734
+ "400": { "$ref": "#/components/responses/BadRequest" },
735
+ "401": { "$ref": "#/components/responses/Unauthorized" },
736
+ "403": { "$ref": "#/components/responses/Forbidden" },
737
+ "404": { "$ref": "#/components/responses/NotFound" },
738
+ "429": { "$ref": "#/components/responses/RateLimited" }
739
+ }
740
+ },
741
+ "delete": {
742
+ "tags": ["Webhooks"],
743
+ "summary": "Delete webhook",
744
+ "operationId": "deleteWebhook",
745
+ "requestBody": {
746
+ "required": true,
747
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" } } } } }
748
+ },
749
+ "responses": {
750
+ "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted": { "type": "integer" } } } } } },
751
+ "400": { "$ref": "#/components/responses/BadRequest" },
752
+ "401": { "$ref": "#/components/responses/Unauthorized" },
753
+ "403": { "$ref": "#/components/responses/Forbidden" },
754
+ "404": { "$ref": "#/components/responses/NotFound" },
755
+ "429": { "$ref": "#/components/responses/RateLimited" }
756
+ }
757
+ }
758
+ },
759
+ "/api/webhooks/deliveries": {
760
+ "get": {
761
+ "tags": ["Webhooks"],
762
+ "summary": "Get webhook delivery history",
763
+ "operationId": "getWebhookDeliveries",
764
+ "parameters": [
765
+ { "name": "webhook_id", "in": "query", "schema": { "type": "integer" } },
766
+ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
767
+ ],
768
+ "responses": {
769
+ "200": { "description": "Delivery history", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "webhook_id": { "type": "integer" }, "event": { "type": "string" }, "status_code": { "type": "integer" }, "error": { "type": "string" }, "created_at": { "type": "integer" } } } } } } } } },
770
+ "401": { "$ref": "#/components/responses/Unauthorized" },
771
+ "403": { "$ref": "#/components/responses/Forbidden" }
772
+ }
773
+ }
774
+ },
775
+ "/api/webhooks/test": {
776
+ "post": {
777
+ "tags": ["Webhooks"],
778
+ "summary": "Test webhook",
779
+ "operationId": "testWebhook",
780
+ "requestBody": {
781
+ "required": true,
782
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" } } } } }
783
+ },
784
+ "responses": {
785
+ "200": { "description": "Test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status_code": { "type": "integer" }, "response_time_ms": { "type": "number" } } } } } },
786
+ "401": { "$ref": "#/components/responses/Unauthorized" },
787
+ "403": { "$ref": "#/components/responses/Forbidden" },
788
+ "404": { "$ref": "#/components/responses/NotFound" }
789
+ }
790
+ }
791
+ },
792
+ "/api/alerts": {
793
+ "get": {
794
+ "tags": ["Alerts"],
795
+ "summary": "List alert rules",
796
+ "operationId": "listAlertRules",
797
+ "responses": {
798
+ "200": { "description": "Alert rule list", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRule" } } } } } } },
799
+ "401": { "$ref": "#/components/responses/Unauthorized" }
800
+ }
801
+ },
802
+ "post": {
803
+ "tags": ["Alerts"],
804
+ "summary": "Create alert rule or evaluate rules",
805
+ "operationId": "createAlertRule",
806
+ "requestBody": {
807
+ "required": true,
808
+ "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "CreateRule", "required": ["name", "entity_type", "condition_field", "condition_operator", "condition_value"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "entity_type": { "type": "string", "enum": ["agent", "task", "session", "activity"] }, "condition_field": { "type": "string" }, "condition_operator": { "type": "string", "enum": ["equals", "not_equals", "greater_than", "less_than", "contains", "count_above", "count_below", "age_minutes_above"] }, "condition_value": { "type": "string" }, "action_type": { "type": "string", "default": "notification" }, "action_config": { "type": "object" }, "cooldown_minutes": { "type": "integer", "default": 60 } } }, { "type": "object", "title": "EvaluateRules", "required": ["action"], "properties": { "action": { "type": "string", "const": "evaluate" } } } ] } } }
809
+ },
810
+ "responses": {
811
+ "201": { "description": "Rule created", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/AlertRule" } } } } } },
812
+ "200": { "description": "Rules evaluated", "content": { "application/json": { "schema": { "type": "object", "properties": { "evaluated": { "type": "integer" }, "triggered": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "rule_id": { "type": "integer" }, "rule_name": { "type": "string" }, "triggered": { "type": "boolean" }, "reason": { "type": "string" } } } } } } } } },
813
+ "400": { "$ref": "#/components/responses/BadRequest" },
814
+ "401": { "$ref": "#/components/responses/Unauthorized" },
815
+ "403": { "$ref": "#/components/responses/Forbidden" },
816
+ "429": { "$ref": "#/components/responses/RateLimited" }
817
+ }
818
+ },
819
+ "put": {
820
+ "tags": ["Alerts"],
821
+ "summary": "Update alert rule",
822
+ "operationId": "updateAlertRule",
823
+ "requestBody": {
824
+ "required": true,
825
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "enabled": { "type": "boolean" }, "entity_type": { "type": "string" }, "condition_field": { "type": "string" }, "condition_operator": { "type": "string" }, "condition_value": { "type": "string" }, "action_type": { "type": "string" }, "action_config": { "type": "object" }, "cooldown_minutes": { "type": "integer" } } } } }
826
+ },
827
+ "responses": {
828
+ "200": { "description": "Rule updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/AlertRule" } } } } } },
829
+ "400": { "$ref": "#/components/responses/BadRequest" },
830
+ "401": { "$ref": "#/components/responses/Unauthorized" },
831
+ "403": { "$ref": "#/components/responses/Forbidden" },
832
+ "404": { "$ref": "#/components/responses/NotFound" },
833
+ "429": { "$ref": "#/components/responses/RateLimited" }
834
+ }
835
+ },
836
+ "delete": {
837
+ "tags": ["Alerts"],
838
+ "summary": "Delete alert rule",
839
+ "operationId": "deleteAlertRule",
840
+ "requestBody": {
841
+ "required": true,
842
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" } } } } }
843
+ },
844
+ "responses": {
845
+ "200": { "description": "Rule deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } },
846
+ "400": { "$ref": "#/components/responses/BadRequest" },
847
+ "401": { "$ref": "#/components/responses/Unauthorized" },
848
+ "403": { "$ref": "#/components/responses/Forbidden" },
849
+ "429": { "$ref": "#/components/responses/RateLimited" }
850
+ }
851
+ }
852
+ },
853
+ "/api/workflows": {
854
+ "get": {
855
+ "tags": ["Workflows"],
856
+ "summary": "List workflow templates",
857
+ "operationId": "listWorkflows",
858
+ "responses": {
859
+ "200": { "description": "Workflow template list", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object" } }, "created_by": { "type": "string" }, "use_count": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } } } } },
860
+ "401": { "$ref": "#/components/responses/Unauthorized" }
861
+ }
862
+ },
863
+ "post": {
864
+ "tags": ["Workflows"],
865
+ "summary": "Create workflow template",
866
+ "operationId": "createWorkflow",
867
+ "requestBody": {
868
+ "required": true,
869
+ "content": { "application/json": { "schema": { "type": "object", "required": ["name", "steps"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "agent": { "type": "string" }, "action": { "type": "string" }, "params": { "type": "object" } } } } } } } }
870
+ },
871
+ "responses": {
872
+ "201": { "description": "Template created", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "object" } } } } } },
873
+ "400": { "$ref": "#/components/responses/BadRequest" },
874
+ "401": { "$ref": "#/components/responses/Unauthorized" },
875
+ "403": { "$ref": "#/components/responses/Forbidden" },
876
+ "429": { "$ref": "#/components/responses/RateLimited" }
877
+ }
878
+ },
879
+ "put": {
880
+ "tags": ["Workflows"],
881
+ "summary": "Update workflow template",
882
+ "operationId": "updateWorkflow",
883
+ "requestBody": {
884
+ "required": true,
885
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object" } } } } } }
886
+ },
887
+ "responses": {
888
+ "200": { "description": "Template updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "object" } } } } } },
889
+ "400": { "$ref": "#/components/responses/BadRequest" },
890
+ "401": { "$ref": "#/components/responses/Unauthorized" },
891
+ "403": { "$ref": "#/components/responses/Forbidden" },
892
+ "404": { "$ref": "#/components/responses/NotFound" }
893
+ }
894
+ },
895
+ "delete": {
896
+ "tags": ["Workflows"],
897
+ "summary": "Delete workflow template",
898
+ "operationId": "deleteWorkflow",
899
+ "requestBody": {
900
+ "required": true,
901
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" } } } } }
902
+ },
903
+ "responses": {
904
+ "200": { "description": "Template deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
905
+ "401": { "$ref": "#/components/responses/Unauthorized" },
906
+ "403": { "$ref": "#/components/responses/Forbidden" },
907
+ "404": { "$ref": "#/components/responses/NotFound" }
908
+ }
909
+ }
910
+ },
911
+ "/api/pipelines": {
912
+ "get": {
913
+ "tags": ["Pipelines"],
914
+ "summary": "List pipelines",
915
+ "operationId": "listPipelines",
916
+ "responses": {
917
+ "200": { "description": "Pipeline list with enriched step data and run counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "pipelines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "template_id": { "type": "integer" }, "template_name": { "type": "string" }, "on_failure": { "type": "string", "enum": ["stop", "continue"] } } } }, "created_by": { "type": "string" }, "use_count": { "type": "integer" }, "runs": { "type": "object", "properties": { "total": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "running": { "type": "integer" } } }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } } } } } } },
918
+ "401": { "$ref": "#/components/responses/Unauthorized" }
919
+ }
920
+ },
921
+ "post": {
922
+ "tags": ["Pipelines"],
923
+ "summary": "Create pipeline",
924
+ "operationId": "createPipeline",
925
+ "requestBody": {
926
+ "required": true,
927
+ "content": { "application/json": { "schema": { "type": "object", "required": ["name", "steps"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "required": ["template_id"], "properties": { "template_id": { "type": "integer" }, "on_failure": { "type": "string", "enum": ["stop", "continue"], "default": "stop" } } } } } } } }
928
+ },
929
+ "responses": {
930
+ "201": { "description": "Pipeline created", "content": { "application/json": { "schema": { "type": "object", "properties": { "pipeline": { "type": "object" } } } } } },
931
+ "400": { "$ref": "#/components/responses/BadRequest" },
932
+ "401": { "$ref": "#/components/responses/Unauthorized" },
933
+ "403": { "$ref": "#/components/responses/Forbidden" },
934
+ "429": { "$ref": "#/components/responses/RateLimited" }
935
+ }
936
+ },
937
+ "put": {
938
+ "tags": ["Pipelines"],
939
+ "summary": "Update pipeline",
940
+ "operationId": "updatePipeline",
941
+ "requestBody": {
942
+ "required": true,
943
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object" } } } } } }
944
+ },
945
+ "responses": {
946
+ "200": { "description": "Pipeline updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "pipeline": { "type": "object" } } } } } },
947
+ "400": { "$ref": "#/components/responses/BadRequest" },
948
+ "401": { "$ref": "#/components/responses/Unauthorized" },
949
+ "403": { "$ref": "#/components/responses/Forbidden" },
950
+ "404": { "$ref": "#/components/responses/NotFound" }
951
+ }
952
+ },
953
+ "delete": {
954
+ "tags": ["Pipelines"],
955
+ "summary": "Delete pipeline",
956
+ "operationId": "deletePipeline",
957
+ "requestBody": {
958
+ "required": true,
959
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" } } } } }
960
+ },
961
+ "responses": {
962
+ "200": { "description": "Pipeline deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
963
+ "400": { "$ref": "#/components/responses/BadRequest" },
964
+ "401": { "$ref": "#/components/responses/Unauthorized" },
965
+ "403": { "$ref": "#/components/responses/Forbidden" }
966
+ }
967
+ }
968
+ },
969
+ "/api/pipelines/run": {
970
+ "post": {
971
+ "tags": ["Pipelines"],
972
+ "summary": "Run a pipeline",
973
+ "operationId": "runPipeline",
974
+ "requestBody": {
975
+ "required": true,
976
+ "content": { "application/json": { "schema": { "type": "object", "required": ["pipeline_id"], "properties": { "pipeline_id": { "type": "integer" }, "params": { "type": "object" } } } } }
977
+ },
978
+ "responses": {
979
+ "200": { "description": "Pipeline run started", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "integer" }, "status": { "type": "string" } } } } } },
980
+ "400": { "$ref": "#/components/responses/BadRequest" },
981
+ "401": { "$ref": "#/components/responses/Unauthorized" },
982
+ "403": { "$ref": "#/components/responses/Forbidden" },
983
+ "404": { "$ref": "#/components/responses/NotFound" }
984
+ }
985
+ }
986
+ },
987
+ "/api/activities": {
988
+ "get": {
989
+ "tags": ["Monitoring"],
990
+ "summary": "List activities",
991
+ "operationId": "listActivities",
992
+ "parameters": [
993
+ { "name": "type", "in": "query", "schema": { "type": "string" } },
994
+ { "name": "actor", "in": "query", "schema": { "type": "string" } },
995
+ { "name": "entity_type", "in": "query", "schema": { "type": "string" } },
996
+ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } },
997
+ { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
998
+ ],
999
+ "responses": {
1000
+ "200": { "description": "Activity list", "content": { "application/json": { "schema": { "type": "object", "properties": { "activities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "integer" }, "actor": { "type": "string" }, "description": { "type": "string" }, "metadata": { "type": "object" }, "created_at": { "type": "integer" } } } }, "total": { "type": "integer" } } } } } },
1001
+ "401": { "$ref": "#/components/responses/Unauthorized" }
1002
+ }
1003
+ }
1004
+ },
1005
+ "/api/audit": {
1006
+ "get": {
1007
+ "tags": ["Monitoring"],
1008
+ "summary": "Get audit log",
1009
+ "operationId": "getAuditLog",
1010
+ "parameters": [
1011
+ { "name": "action", "in": "query", "schema": { "type": "string" } },
1012
+ { "name": "actor", "in": "query", "schema": { "type": "string" } },
1013
+ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } },
1014
+ { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
1015
+ ],
1016
+ "responses": {
1017
+ "200": { "description": "Audit log entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "action": { "type": "string" }, "actor": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "integer" }, "detail": { "type": "object" }, "ip_address": { "type": "string" }, "created_at": { "type": "integer" } } } }, "total": { "type": "integer" } } } } } },
1018
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1019
+ "403": { "$ref": "#/components/responses/Forbidden" }
1020
+ }
1021
+ }
1022
+ },
1023
+ "/api/logs": {
1024
+ "get": {
1025
+ "tags": ["Monitoring"],
1026
+ "summary": "Get system logs",
1027
+ "operationId": "getSystemLogs",
1028
+ "parameters": [
1029
+ { "name": "level", "in": "query", "schema": { "type": "string", "enum": ["info", "warn", "error", "debug"] } },
1030
+ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } }
1031
+ ],
1032
+ "responses": {
1033
+ "200": { "description": "Log entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "level": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "string" } } } } } } } } },
1034
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1035
+ "403": { "$ref": "#/components/responses/Forbidden" }
1036
+ }
1037
+ }
1038
+ },
1039
+ "/api/notifications": {
1040
+ "get": {
1041
+ "tags": ["Monitoring"],
1042
+ "summary": "List notifications",
1043
+ "operationId": "listNotifications",
1044
+ "parameters": [
1045
+ { "name": "recipient", "in": "query", "schema": { "type": "string" } },
1046
+ { "name": "unread", "in": "query", "schema": { "type": "boolean" } },
1047
+ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
1048
+ ],
1049
+ "responses": {
1050
+ "200": { "description": "Notification list", "content": { "application/json": { "schema": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "recipient": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "message": { "type": "string" }, "read": { "type": "boolean" }, "source_type": { "type": "string" }, "source_id": { "type": "integer" }, "created_at": { "type": "integer" } } } } } } } } },
1051
+ "401": { "$ref": "#/components/responses/Unauthorized" }
1052
+ }
1053
+ },
1054
+ "post": {
1055
+ "tags": ["Monitoring"],
1056
+ "summary": "Notification actions (mark read, dismiss)",
1057
+ "operationId": "notificationAction",
1058
+ "requestBody": {
1059
+ "required": true,
1060
+ "content": { "application/json": { "schema": { "type": "object", "required": ["action"], "properties": { "action": { "type": "string", "enum": ["mark_read", "mark_all_read", "dismiss"] }, "id": { "type": "integer" }, "recipient": { "type": "string" } } } } }
1061
+ },
1062
+ "responses": {
1063
+ "200": { "description": "Action applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
1064
+ "400": { "$ref": "#/components/responses/BadRequest" },
1065
+ "401": { "$ref": "#/components/responses/Unauthorized" }
1066
+ }
1067
+ }
1068
+ },
1069
+ "/api/notifications/deliver": {
1070
+ "post": {
1071
+ "tags": ["Monitoring"],
1072
+ "summary": "Deliver notification to agent",
1073
+ "operationId": "deliverNotification",
1074
+ "requestBody": {
1075
+ "required": true,
1076
+ "content": { "application/json": { "schema": { "type": "object", "required": ["agent", "title", "message"], "properties": { "agent": { "type": "string" }, "title": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string" } } } } }
1077
+ },
1078
+ "responses": {
1079
+ "200": { "description": "Notification delivered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
1080
+ "400": { "$ref": "#/components/responses/BadRequest" },
1081
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1082
+ "403": { "$ref": "#/components/responses/Forbidden" }
1083
+ }
1084
+ }
1085
+ },
1086
+ "/api/events": {
1087
+ "get": {
1088
+ "tags": ["Monitoring"],
1089
+ "summary": "SSE stream for real-time events",
1090
+ "operationId": "getEventStream",
1091
+ "responses": {
1092
+ "200": { "description": "Server-Sent Events stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } },
1093
+ "401": { "$ref": "#/components/responses/Unauthorized" }
1094
+ }
1095
+ }
1096
+ },
1097
+ "/api/status": {
1098
+ "get": {
1099
+ "tags": ["Monitoring"],
1100
+ "summary": "Get system status",
1101
+ "operationId": "getSystemStatus",
1102
+ "security": [],
1103
+ "responses": {
1104
+ "200": { "description": "System health status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok", "degraded", "down"] }, "version": { "type": "string" }, "uptime": { "type": "integer" }, "agents": { "type": "object", "properties": { "total": { "type": "integer" }, "online": { "type": "integer" } } }, "tasks": { "type": "object", "properties": { "total": { "type": "integer" }, "in_progress": { "type": "integer" } } } } } } } }
1105
+ }
1106
+ }
1107
+ },
1108
+ "/api/settings": {
1109
+ "get": {
1110
+ "tags": ["Admin"],
1111
+ "summary": "Get application settings",
1112
+ "operationId": "getSettings",
1113
+ "responses": {
1114
+ "200": { "description": "Current settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object" } } } } } },
1115
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1116
+ "403": { "$ref": "#/components/responses/Forbidden" }
1117
+ }
1118
+ },
1119
+ "post": {
1120
+ "tags": ["Admin"],
1121
+ "summary": "Update settings",
1122
+ "operationId": "updateSettings",
1123
+ "requestBody": {
1124
+ "required": true,
1125
+ "content": { "application/json": { "schema": { "type": "object" } } }
1126
+ },
1127
+ "responses": {
1128
+ "200": { "description": "Settings updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
1129
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1130
+ "403": { "$ref": "#/components/responses/Forbidden" }
1131
+ }
1132
+ }
1133
+ },
1134
+ "/api/scheduler": {
1135
+ "get": {
1136
+ "tags": ["Admin"],
1137
+ "summary": "Get scheduler status",
1138
+ "operationId": "getSchedulerStatus",
1139
+ "responses": {
1140
+ "200": { "description": "Scheduler status and registered tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "running": { "type": "boolean" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "interval": { "type": "string" }, "last_run": { "type": "integer" }, "next_run": { "type": "integer" } } } } } } } } },
1141
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1142
+ "403": { "$ref": "#/components/responses/Forbidden" }
1143
+ }
1144
+ },
1145
+ "post": {
1146
+ "tags": ["Admin"],
1147
+ "summary": "Trigger scheduled task",
1148
+ "operationId": "triggerScheduledTask",
1149
+ "requestBody": {
1150
+ "required": true,
1151
+ "content": { "application/json": { "schema": { "type": "object", "required": ["task"], "properties": { "task": { "type": "string" } } } } }
1152
+ },
1153
+ "responses": {
1154
+ "200": { "description": "Task triggered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "result": { "type": "object" } } } } } },
1155
+ "400": { "$ref": "#/components/responses/BadRequest" },
1156
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1157
+ "403": { "$ref": "#/components/responses/Forbidden" }
1158
+ }
1159
+ }
1160
+ },
1161
+ "/api/cron": {
1162
+ "get": {
1163
+ "tags": ["Admin"],
1164
+ "summary": "Get cron jobs",
1165
+ "operationId": "getCronJobs",
1166
+ "parameters": [
1167
+ { "name": "action", "in": "query", "schema": { "type": "string", "enum": ["list", "logs"], "default": "list" } }
1168
+ ],
1169
+ "responses": {
1170
+ "200": { "description": "Cron job list or logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "schedule": { "type": "string" }, "enabled": { "type": "boolean" }, "last_run": { "type": "integer" }, "last_status": { "type": "string" } } } } } } } } },
1171
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1172
+ "403": { "$ref": "#/components/responses/Forbidden" }
1173
+ }
1174
+ },
1175
+ "post": {
1176
+ "tags": ["Admin"],
1177
+ "summary": "Manage cron jobs",
1178
+ "operationId": "manageCronJobs",
1179
+ "requestBody": {
1180
+ "required": true,
1181
+ "content": { "application/json": { "schema": { "type": "object", "required": ["action"], "properties": { "action": { "type": "string", "enum": ["toggle", "trigger", "add", "remove"] }, "name": { "type": "string" }, "schedule": { "type": "string" }, "command": { "type": "string" }, "enabled": { "type": "boolean" } } } } }
1182
+ },
1183
+ "responses": {
1184
+ "200": { "description": "Action applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
1185
+ "400": { "$ref": "#/components/responses/BadRequest" },
1186
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1187
+ "403": { "$ref": "#/components/responses/Forbidden" }
1188
+ }
1189
+ }
1190
+ },
1191
+ "/api/gateways": {
1192
+ "get": {
1193
+ "tags": ["Admin"],
1194
+ "summary": "List gateways",
1195
+ "operationId": "listGateways",
1196
+ "responses": {
1197
+ "200": { "description": "Gateway list", "content": { "application/json": { "schema": { "type": "object", "properties": { "gateways": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string" }, "last_health_check": { "type": "integer" } } } } } } } } },
1198
+ "401": { "$ref": "#/components/responses/Unauthorized" }
1199
+ }
1200
+ },
1201
+ "post": {
1202
+ "tags": ["Admin"],
1203
+ "summary": "Add gateway",
1204
+ "operationId": "addGateway",
1205
+ "requestBody": {
1206
+ "required": true,
1207
+ "content": { "application/json": { "schema": { "type": "object", "required": ["name", "url"], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } }
1208
+ },
1209
+ "responses": {
1210
+ "201": { "description": "Gateway added", "content": { "application/json": { "schema": { "type": "object" } } } },
1211
+ "400": { "$ref": "#/components/responses/BadRequest" },
1212
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1213
+ "403": { "$ref": "#/components/responses/Forbidden" }
1214
+ }
1215
+ },
1216
+ "put": {
1217
+ "tags": ["Admin"],
1218
+ "summary": "Update gateway",
1219
+ "operationId": "updateGateway",
1220
+ "requestBody": {
1221
+ "required": true,
1222
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string" } } } } }
1223
+ },
1224
+ "responses": {
1225
+ "200": { "description": "Gateway updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
1226
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1227
+ "403": { "$ref": "#/components/responses/Forbidden" },
1228
+ "404": { "$ref": "#/components/responses/NotFound" }
1229
+ }
1230
+ },
1231
+ "delete": {
1232
+ "tags": ["Admin"],
1233
+ "summary": "Delete gateway",
1234
+ "operationId": "deleteGateway",
1235
+ "requestBody": {
1236
+ "required": true,
1237
+ "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" } } } } }
1238
+ },
1239
+ "responses": {
1240
+ "200": { "description": "Gateway deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
1241
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1242
+ "403": { "$ref": "#/components/responses/Forbidden" }
1243
+ }
1244
+ }
1245
+ },
1246
+ "/api/gateways/health": {
1247
+ "post": {
1248
+ "tags": ["Admin"],
1249
+ "summary": "Probe gateway health",
1250
+ "operationId": "probeGatewayHealth",
1251
+ "requestBody": {
1252
+ "content": { "application/json": { "schema": { "type": "object", "properties": { "gateway_id": { "type": "integer" } } } } }
1253
+ },
1254
+ "responses": {
1255
+ "200": { "description": "Health check results", "content": { "application/json": { "schema": { "type": "object", "properties": { "healthy": { "type": "boolean" }, "latency_ms": { "type": "number" }, "details": { "type": "object" } } } } } },
1256
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1257
+ "403": { "$ref": "#/components/responses/Forbidden" }
1258
+ }
1259
+ }
1260
+ },
1261
+ "/api/gateway-config": {
1262
+ "get": {
1263
+ "tags": ["Admin"],
1264
+ "summary": "Read gateway config",
1265
+ "operationId": "getGatewayConfig",
1266
+ "responses": {
1267
+ "200": { "description": "Gateway configuration", "content": { "application/json": { "schema": { "type": "object" } } } },
1268
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1269
+ "403": { "$ref": "#/components/responses/Forbidden" }
1270
+ }
1271
+ },
1272
+ "post": {
1273
+ "tags": ["Admin"],
1274
+ "summary": "Update gateway config",
1275
+ "operationId": "updateGatewayConfig",
1276
+ "requestBody": {
1277
+ "required": true,
1278
+ "content": { "application/json": { "schema": { "type": "object" } } }
1279
+ },
1280
+ "responses": {
1281
+ "200": { "description": "Config updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
1282
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1283
+ "403": { "$ref": "#/components/responses/Forbidden" }
1284
+ }
1285
+ }
1286
+ },
1287
+ "/api/integrations": {
1288
+ "get": {
1289
+ "tags": ["Admin"],
1290
+ "summary": "List integrations",
1291
+ "operationId": "listIntegrations",
1292
+ "responses": {
1293
+ "200": { "description": "Integration list", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "enabled": { "type": "boolean" }, "config": { "type": "object" } } } } } } } } },
1294
+ "401": { "$ref": "#/components/responses/Unauthorized" }
1295
+ }
1296
+ },
1297
+ "post": {
1298
+ "tags": ["Admin"],
1299
+ "summary": "Integration actions (enable, disable, test, configure)",
1300
+ "operationId": "integrationAction",
1301
+ "requestBody": {
1302
+ "required": true,
1303
+ "content": { "application/json": { "schema": { "type": "object", "required": ["action", "id"], "properties": { "action": { "type": "string", "enum": ["enable", "disable", "test", "configure"] }, "id": { "type": "string" }, "config": { "type": "object" } } } } }
1304
+ },
1305
+ "responses": {
1306
+ "200": { "description": "Action applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
1307
+ "400": { "$ref": "#/components/responses/BadRequest" },
1308
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1309
+ "403": { "$ref": "#/components/responses/Forbidden" }
1310
+ }
1311
+ }
1312
+ },
1313
+ "/api/spawn": {
1314
+ "post": {
1315
+ "tags": ["Admin"],
1316
+ "summary": "Spawn agent process",
1317
+ "operationId": "spawnAgent",
1318
+ "requestBody": {
1319
+ "required": true,
1320
+ "content": { "application/json": { "schema": { "type": "object", "required": ["agent"], "properties": { "agent": { "type": "string" }, "task": { "type": "string" }, "params": { "type": "object" } } } } }
1321
+ },
1322
+ "responses": {
1323
+ "200": { "description": "Agent spawned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "session_id": { "type": "string" } } } } } },
1324
+ "400": { "$ref": "#/components/responses/BadRequest" },
1325
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1326
+ "403": { "$ref": "#/components/responses/Forbidden" }
1327
+ }
1328
+ }
1329
+ },
1330
+ "/api/standup": {
1331
+ "get": {
1332
+ "tags": ["Admin"],
1333
+ "summary": "Get standup report",
1334
+ "operationId": "getStandupReport",
1335
+ "parameters": [
1336
+ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }
1337
+ ],
1338
+ "responses": {
1339
+ "200": { "description": "Standup report", "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string" }, "agents": { "type": "array", "items": { "type": "object" } }, "tasks_completed": { "type": "integer" }, "tasks_in_progress": { "type": "integer" }, "highlights": { "type": "array", "items": { "type": "string" } } } } } } },
1340
+ "401": { "$ref": "#/components/responses/Unauthorized" }
1341
+ }
1342
+ }
1343
+ },
1344
+ "/api/memory": {
1345
+ "get": {
1346
+ "tags": ["Admin"],
1347
+ "summary": "Get memory files",
1348
+ "operationId": "getMemoryFiles",
1349
+ "parameters": [
1350
+ { "name": "path", "in": "query", "schema": { "type": "string" } }
1351
+ ],
1352
+ "responses": {
1353
+ "200": { "description": "Memory file contents", "content": { "application/json": { "schema": { "type": "object" } } } },
1354
+ "401": { "$ref": "#/components/responses/Unauthorized" }
1355
+ }
1356
+ },
1357
+ "post": {
1358
+ "tags": ["Admin"],
1359
+ "summary": "Update memory file",
1360
+ "operationId": "updateMemoryFile",
1361
+ "requestBody": {
1362
+ "required": true,
1363
+ "content": { "application/json": { "schema": { "type": "object", "required": ["path", "content"], "properties": { "path": { "type": "string" }, "content": { "type": "string" } } } } }
1364
+ },
1365
+ "responses": {
1366
+ "200": { "description": "Memory updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
1367
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1368
+ "403": { "$ref": "#/components/responses/Forbidden" }
1369
+ }
1370
+ }
1371
+ },
1372
+ "/api/search": {
1373
+ "get": {
1374
+ "tags": ["Admin"],
1375
+ "summary": "Full-text search",
1376
+ "operationId": "search",
1377
+ "parameters": [
1378
+ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
1379
+ { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["tasks", "agents", "activities", "all"] } },
1380
+ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }
1381
+ ],
1382
+ "responses": {
1383
+ "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "title": { "type": "string" }, "snippet": { "type": "string" }, "score": { "type": "number" } } } }, "total": { "type": "integer" } } } } } },
1384
+ "400": { "$ref": "#/components/responses/BadRequest" },
1385
+ "401": { "$ref": "#/components/responses/Unauthorized" }
1386
+ }
1387
+ }
1388
+ },
1389
+ "/api/backup": {
1390
+ "post": {
1391
+ "tags": ["Admin"],
1392
+ "summary": "Trigger backup",
1393
+ "operationId": "triggerBackup",
1394
+ "responses": {
1395
+ "200": { "description": "Backup completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "path": { "type": "string" }, "size_bytes": { "type": "integer" } } } } } },
1396
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1397
+ "403": { "$ref": "#/components/responses/Forbidden" }
1398
+ }
1399
+ }
1400
+ },
1401
+ "/api/cleanup": {
1402
+ "post": {
1403
+ "tags": ["Admin"],
1404
+ "summary": "Trigger cleanup of old data",
1405
+ "operationId": "triggerCleanup",
1406
+ "requestBody": {
1407
+ "content": { "application/json": { "schema": { "type": "object", "properties": { "older_than_days": { "type": "integer", "default": 30 } } } } }
1408
+ },
1409
+ "responses": {
1410
+ "200": { "description": "Cleanup results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted": { "type": "object" } } } } } },
1411
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1412
+ "403": { "$ref": "#/components/responses/Forbidden" }
1413
+ }
1414
+ }
1415
+ },
1416
+ "/api/export": {
1417
+ "get": {
1418
+ "tags": ["Admin"],
1419
+ "summary": "Export data",
1420
+ "operationId": "exportData",
1421
+ "parameters": [
1422
+ { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["tasks", "agents", "activities", "all"] } },
1423
+ { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "csv"], "default": "json" } }
1424
+ ],
1425
+ "responses": {
1426
+ "200": { "description": "Exported data", "content": { "application/json": { "schema": { "type": "object" } }, "text/csv": { "schema": { "type": "string" } } } },
1427
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1428
+ "403": { "$ref": "#/components/responses/Forbidden" }
1429
+ }
1430
+ }
1431
+ },
1432
+ "/api/super/tenants": {
1433
+ "get": {
1434
+ "tags": ["Super Admin"],
1435
+ "summary": "List tenants",
1436
+ "operationId": "listTenants",
1437
+ "responses": {
1438
+ "200": { "description": "Tenant list", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "linux_user": { "type": "string" }, "created_at": { "type": "integer" } } } } } } } } },
1439
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1440
+ "403": { "$ref": "#/components/responses/Forbidden" }
1441
+ }
1442
+ },
1443
+ "post": {
1444
+ "tags": ["Super Admin"],
1445
+ "summary": "Create tenant and bootstrap job",
1446
+ "operationId": "createTenant",
1447
+ "requestBody": {
1448
+ "required": true,
1449
+ "content": { "application/json": { "schema": { "type": "object", "required": ["slug", "name"], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "linux_user": { "type": "string" }, "config": { "type": "object" } } } } }
1450
+ },
1451
+ "responses": {
1452
+ "201": { "description": "Tenant created with bootstrap job", "content": { "application/json": { "schema": { "type": "object" } } } },
1453
+ "400": { "$ref": "#/components/responses/BadRequest" },
1454
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1455
+ "403": { "$ref": "#/components/responses/Forbidden" },
1456
+ "409": { "description": "Tenant slug or linux user already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
1457
+ }
1458
+ }
1459
+ },
1460
+ "/api/super/tenants/{id}/decommission": {
1461
+ "post": {
1462
+ "tags": ["Super Admin"],
1463
+ "summary": "Decommission tenant",
1464
+ "operationId": "decommissionTenant",
1465
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
1466
+ "responses": {
1467
+ "200": { "description": "Tenant decommissioned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } },
1468
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1469
+ "403": { "$ref": "#/components/responses/Forbidden" },
1470
+ "404": { "$ref": "#/components/responses/NotFound" }
1471
+ }
1472
+ }
1473
+ },
1474
+ "/api/super/provision-jobs": {
1475
+ "get": {
1476
+ "tags": ["Super Admin"],
1477
+ "summary": "List provision jobs",
1478
+ "operationId": "listProvisionJobs",
1479
+ "responses": {
1480
+ "200": { "description": "Provision job list", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "tenant_id": { "type": "integer" }, "type": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "running", "completed", "failed"] }, "output": { "type": "string" }, "created_at": { "type": "integer" }, "completed_at": { "type": "integer" } } } } } } } } },
1481
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1482
+ "403": { "$ref": "#/components/responses/Forbidden" }
1483
+ }
1484
+ },
1485
+ "post": {
1486
+ "tags": ["Super Admin"],
1487
+ "summary": "Create provision job",
1488
+ "operationId": "createProvisionJob",
1489
+ "requestBody": {
1490
+ "required": true,
1491
+ "content": { "application/json": { "schema": { "type": "object", "required": ["tenant_id", "type"], "properties": { "tenant_id": { "type": "integer" }, "type": { "type": "string" }, "params": { "type": "object" } } } } }
1492
+ },
1493
+ "responses": {
1494
+ "201": { "description": "Job created", "content": { "application/json": { "schema": { "type": "object" } } } },
1495
+ "400": { "$ref": "#/components/responses/BadRequest" },
1496
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1497
+ "403": { "$ref": "#/components/responses/Forbidden" }
1498
+ }
1499
+ }
1500
+ },
1501
+ "/api/super/provision-jobs/{id}": {
1502
+ "get": {
1503
+ "tags": ["Super Admin"],
1504
+ "summary": "Get provision job details",
1505
+ "operationId": "getProvisionJob",
1506
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
1507
+ "responses": {
1508
+ "200": { "description": "Job details", "content": { "application/json": { "schema": { "type": "object" } } } },
1509
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1510
+ "403": { "$ref": "#/components/responses/Forbidden" },
1511
+ "404": { "$ref": "#/components/responses/NotFound" }
1512
+ }
1513
+ }
1514
+ },
1515
+ "/api/super/provision-jobs/{id}/run": {
1516
+ "post": {
1517
+ "tags": ["Super Admin"],
1518
+ "summary": "Run provision job",
1519
+ "operationId": "runProvisionJob",
1520
+ "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
1521
+ "responses": {
1522
+ "200": { "description": "Job started", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string" } } } } } },
1523
+ "401": { "$ref": "#/components/responses/Unauthorized" },
1524
+ "403": { "$ref": "#/components/responses/Forbidden" },
1525
+ "404": { "$ref": "#/components/responses/NotFound" }
1526
+ }
1527
+ }
1528
+ }
1529
+ },
1530
+ "components": {
1531
+ "securitySchemes": {
1532
+ "sessionCookie": {
1533
+ "type": "apiKey",
1534
+ "in": "cookie",
1535
+ "name": "mc-session"
1536
+ },
1537
+ "apiKey": {
1538
+ "type": "apiKey",
1539
+ "in": "header",
1540
+ "name": "x-api-key"
1541
+ }
1542
+ },
1543
+ "schemas": {
1544
+ "Error": {
1545
+ "type": "object",
1546
+ "required": ["error"],
1547
+ "properties": {
1548
+ "error": { "type": "string" },
1549
+ "details": { "type": "array", "items": { "type": "string" } }
1550
+ }
1551
+ },
1552
+ "User": {
1553
+ "type": "object",
1554
+ "properties": {
1555
+ "id": { "type": "integer" },
1556
+ "username": { "type": "string" },
1557
+ "display_name": { "type": "string" },
1558
+ "role": { "type": "string", "enum": ["admin", "operator", "viewer"] },
1559
+ "provider": { "type": "string" },
1560
+ "email": { "type": "string" },
1561
+ "avatar_url": { "type": "string" },
1562
+ "created_at": { "type": "integer" },
1563
+ "last_login_at": { "type": "integer" }
1564
+ }
1565
+ },
1566
+ "Agent": {
1567
+ "type": "object",
1568
+ "properties": {
1569
+ "id": { "type": "integer" },
1570
+ "name": { "type": "string" },
1571
+ "role": { "type": "string" },
1572
+ "status": { "type": "string", "enum": ["online", "offline", "busy", "idle", "error"] },
1573
+ "session_key": { "type": "string" },
1574
+ "soul_content": { "type": "string" },
1575
+ "config": { "type": "object" },
1576
+ "last_seen": { "type": "integer" },
1577
+ "created_at": { "type": "integer" },
1578
+ "updated_at": { "type": "integer" },
1579
+ "taskStats": {
1580
+ "type": "object",
1581
+ "properties": {
1582
+ "total": { "type": "integer" },
1583
+ "assigned": { "type": "integer" },
1584
+ "in_progress": { "type": "integer" },
1585
+ "completed": { "type": "integer" }
1586
+ }
1587
+ }
1588
+ }
1589
+ },
1590
+ "Task": {
1591
+ "type": "object",
1592
+ "properties": {
1593
+ "id": { "type": "integer" },
1594
+ "title": { "type": "string" },
1595
+ "description": { "type": "string" },
1596
+ "status": { "type": "string", "enum": ["inbox", "assigned", "in_progress", "quality_review", "done"] },
1597
+ "priority": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
1598
+ "assigned_to": { "type": "string" },
1599
+ "created_by": { "type": "string" },
1600
+ "due_date": { "type": "string" },
1601
+ "estimated_hours": { "type": "number" },
1602
+ "tags": { "type": "array", "items": { "type": "string" } },
1603
+ "metadata": { "type": "object" },
1604
+ "created_at": { "type": "integer" },
1605
+ "updated_at": { "type": "integer" }
1606
+ }
1607
+ },
1608
+ "TokenUsageRecord": {
1609
+ "type": "object",
1610
+ "properties": {
1611
+ "id": { "type": "string" },
1612
+ "model": { "type": "string" },
1613
+ "sessionId": { "type": "string" },
1614
+ "timestamp": { "type": "integer" },
1615
+ "inputTokens": { "type": "integer" },
1616
+ "outputTokens": { "type": "integer" },
1617
+ "totalTokens": { "type": "integer" },
1618
+ "cost": { "type": "number" },
1619
+ "operation": { "type": "string" },
1620
+ "duration": { "type": "number" }
1621
+ }
1622
+ },
1623
+ "TokenStats": {
1624
+ "type": "object",
1625
+ "properties": {
1626
+ "totalTokens": { "type": "integer" },
1627
+ "totalCost": { "type": "number" },
1628
+ "requestCount": { "type": "integer" },
1629
+ "avgTokensPerRequest": { "type": "integer" },
1630
+ "avgCostPerRequest": { "type": "number" }
1631
+ }
1632
+ },
1633
+ "Webhook": {
1634
+ "type": "object",
1635
+ "properties": {
1636
+ "id": { "type": "integer" },
1637
+ "name": { "type": "string" },
1638
+ "url": { "type": "string" },
1639
+ "secret": { "type": "string", "description": "Masked except on creation" },
1640
+ "events": { "type": "array", "items": { "type": "string" } },
1641
+ "enabled": { "type": "boolean" },
1642
+ "last_fired_at": { "type": "integer" },
1643
+ "last_status": { "type": "integer" },
1644
+ "total_deliveries": { "type": "integer" },
1645
+ "successful_deliveries": { "type": "integer" },
1646
+ "failed_deliveries": { "type": "integer" },
1647
+ "created_at": { "type": "integer" }
1648
+ }
1649
+ },
1650
+ "AlertRule": {
1651
+ "type": "object",
1652
+ "properties": {
1653
+ "id": { "type": "integer" },
1654
+ "name": { "type": "string" },
1655
+ "description": { "type": "string" },
1656
+ "enabled": { "type": "boolean" },
1657
+ "entity_type": { "type": "string", "enum": ["agent", "task", "session", "activity"] },
1658
+ "condition_field": { "type": "string" },
1659
+ "condition_operator": { "type": "string" },
1660
+ "condition_value": { "type": "string" },
1661
+ "action_type": { "type": "string" },
1662
+ "action_config": { "type": "object" },
1663
+ "cooldown_minutes": { "type": "integer" },
1664
+ "last_triggered_at": { "type": "integer" },
1665
+ "trigger_count": { "type": "integer" },
1666
+ "created_by": { "type": "string" },
1667
+ "created_at": { "type": "integer" },
1668
+ "updated_at": { "type": "integer" }
1669
+ }
1670
+ }
1671
+ },
1672
+ "responses": {
1673
+ "BadRequest": {
1674
+ "description": "Invalid request",
1675
+ "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
1676
+ },
1677
+ "Unauthorized": {
1678
+ "description": "Authentication required",
1679
+ "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
1680
+ },
1681
+ "Forbidden": {
1682
+ "description": "Insufficient permissions",
1683
+ "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
1684
+ },
1685
+ "NotFound": {
1686
+ "description": "Resource not found",
1687
+ "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
1688
+ },
1689
+ "RateLimited": {
1690
+ "description": "Rate limit exceeded",
1691
+ "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
1692
+ }
1693
+ }
1694
+ }
1695
+ }
package.json CHANGED
@@ -1,7 +1,7 @@
1
  {
2
  "name": "mission-control",
3
  "version": "1.2.0",
4
- "description": "OpenClaw Mission Control \u2014 open-source agent orchestration dashboard",
5
  "scripts": {
6
  "dev": "next dev --hostname 127.0.0.1",
7
  "build": "next build",
@@ -16,6 +16,7 @@
16
  "quality:gate": "pnpm test:all"
17
  },
18
  "dependencies": {
 
19
  "@xyflow/react": "^12.10.0",
20
  "autoprefixer": "^10.4.20",
21
  "better-sqlite3": "^12.6.2",
 
1
  {
2
  "name": "mission-control",
3
  "version": "1.2.0",
4
+ "description": "OpenClaw Mission Control — open-source agent orchestration dashboard",
5
  "scripts": {
6
  "dev": "next dev --hostname 127.0.0.1",
7
  "build": "next build",
 
16
  "quality:gate": "pnpm test:all"
17
  },
18
  "dependencies": {
19
+ "@scalar/api-reference-react": "^0.8.66",
20
  "@xyflow/react": "^12.10.0",
21
  "autoprefixer": "^10.4.20",
22
  "better-sqlite3": "^12.6.2",
pnpm-lock.yaml CHANGED
The diff for this file is too large to render. See raw diff
 
src/app/api/docs/route.ts ADDED
@@ -0,0 +1,19 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { NextResponse } from 'next/server'
2
+ import { readFileSync } from 'fs'
3
+ import { join } from 'path'
4
+
5
+ let cachedSpec: string | null = null
6
+
7
+ export async function GET() {
8
+ if (!cachedSpec) {
9
+ const specPath = join(process.cwd(), 'openapi.json')
10
+ cachedSpec = readFileSync(specPath, 'utf-8')
11
+ }
12
+
13
+ return new NextResponse(cachedSpec, {
14
+ headers: {
15
+ 'Content-Type': 'application/json',
16
+ 'Cache-Control': 'public, max-age=3600',
17
+ },
18
+ })
19
+ }
src/app/docs/page.tsx ADDED
@@ -0,0 +1,27 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ 'use client'
2
+
3
+ import { ApiReferenceReact } from '@scalar/api-reference-react'
4
+ import '@scalar/api-reference-react/style.css'
5
+
6
+ export default function DocsPage() {
7
+ return (
8
+ <div className="h-screen">
9
+ <ApiReferenceReact
10
+ configuration={{
11
+ url: '/api/docs',
12
+ theme: 'kepler',
13
+ darkMode: true,
14
+ hideModels: false,
15
+ hideDownloadButton: false,
16
+ defaultHttpClient: {
17
+ targetKey: 'shell',
18
+ clientKey: 'curl',
19
+ },
20
+ metaData: {
21
+ title: 'Mission Control API Docs',
22
+ },
23
+ }}
24
+ />
25
+ </div>
26
+ )
27
+ }
src/middleware.ts CHANGED
@@ -91,8 +91,8 @@ export function middleware(request: NextRequest) {
91
  }
92
  }
93
 
94
- // Allow login page and auth API without session
95
- if (pathname === '/login' || pathname.startsWith('/api/auth/')) {
96
  return applySecurityHeaders(NextResponse.next())
97
  }
98
 
 
91
  }
92
  }
93
 
94
+ // Allow login page, auth API, and docs without session
95
+ if (pathname === '/login' || pathname.startsWith('/api/auth/') || pathname === '/api/docs' || pathname === '/docs') {
96
  return applySecurityHeaders(NextResponse.next())
97
  }
98
 
tests/openapi.spec.ts ADDED
@@ -0,0 +1,36 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { test, expect } from '@playwright/test'
2
+
3
+ test.describe('OpenAPI Documentation', () => {
4
+ test('GET /api/docs returns valid OpenAPI 3.1 JSON', async ({ request }) => {
5
+ const res = await request.get('/api/docs')
6
+ expect(res.status()).toBe(200)
7
+ expect(res.headers()['content-type']).toContain('application/json')
8
+
9
+ const spec = await res.json()
10
+ expect(spec.openapi).toMatch(/^3\.1/)
11
+ expect(spec.info).toBeDefined()
12
+ expect(spec.info.title).toBe('Mission Control API')
13
+ expect(spec.info.version).toBeDefined()
14
+ expect(spec.paths).toBeDefined()
15
+ })
16
+
17
+ test('GET /api/docs includes key paths', async ({ request }) => {
18
+ const res = await request.get('/api/docs')
19
+ const spec = await res.json()
20
+
21
+ // Verify core paths exist
22
+ const paths = Object.keys(spec.paths)
23
+ expect(paths).toContain('/api/agents')
24
+ expect(paths).toContain('/api/tasks')
25
+ expect(paths).toContain('/api/tokens')
26
+ expect(paths).toContain('/api/auth/login')
27
+ })
28
+
29
+ test('GET /api/docs is accessible without auth', async ({ request }) => {
30
+ // No API key header, no session cookie
31
+ const res = await request.get('/api/docs', { headers: {} })
32
+ expect(res.status()).toBe(200)
33
+ const spec = await res.json()
34
+ expect(spec.openapi).toBeDefined()
35
+ })
36
+ })