0
# Backend REST API
1

2
The Metlo backend provides comprehensive REST API endpoints for managing API security data, alerts, traces, and platform configuration. The backend serves as the central hub for all Metlo operations including data ingestion, analysis, and security monitoring.
3

4
## Capabilities
5

6
### Endpoint Management API
7

8
#### List Endpoints
9

10
Retrieve API endpoints with filtering and pagination support.
11

12
```typescript { .api }
13
GET /api/v1/endpoints?host={host}&riskScore={riskScore}&offset={offset}&limit={limit}
14

15
// Query Parameters:
16
interface GetEndpointParams {
17
  host?: string;                    // Filter by host
18
  riskScore?: RiskScore[];         // Filter by risk scores
19
  dataClass?: string[];            // Filter by data classes
20
  owner?: string[];                // Filter by owner
21
  tag?: string[];                  // Filter by tags
22
  method?: RestMethod[];           // Filter by HTTP methods
23
  isAuthenticated?: boolean;       // Filter by authentication status
24
  offset?: number;                 // Pagination offset (default: 0)
25
  limit?: number;                  // Results per page (default: 10)
26
}
27

28
// Response:
29
interface EndpointResponse {
30
  endpoints: ApiEndpoint[];
31
  totalCount: number;
32
}
33
```
34

35
#### Get Endpoint Details
36

37
Retrieve detailed information about a specific endpoint.
38

39
```typescript { .api }
40
GET /api/v1/endpoint/{endpointId}
41

42
// Response:
43
interface EndpointDetailResponse {
44
  endpoint: ApiEndpointDetailed;
45
}
46
```
47

48
#### Update Endpoint Authentication
49

50
Set authentication requirements for an endpoint.
51

52
```typescript { .api }
53
PUT /api/v1/endpoint/{endpointId}/authenticated
54

55
// Request Body:
56
interface UpdateAuthParams {
57
  authenticated: boolean;
58
}
59
```
60

61
#### Delete Endpoints
62

63
Remove endpoints from monitoring.
64

65
```typescript { .api }
66
DELETE /api/v1/endpoints
67

68
// Request Body:
69
interface DeleteEndpointsParams {
70
  endpointIds: string[];
71
}
72
```
73

74
### Alert Management API
75

76
#### List Alerts
77

78
Retrieve security alerts with filtering options.
79

80
```typescript { .api }
81
GET /api/v1/alerts?alertTypes={types}&riskScores={scores}&hosts={hosts}&offset={offset}&limit={limit}
82

83
// Query Parameters:
84
interface GetAlertParams {
85
  alertTypes?: AlertType[];        // Filter by alert types
86
  riskScores?: RiskScore[];       // Filter by risk scores
87
  hosts?: string[];               // Filter by hosts
88
  endpointIds?: string[];         // Filter by endpoint IDs
89
  status?: Status[];              // Filter by resolution status
90
  offset?: number;                // Pagination offset
91
  limit?: number;                 // Results per page
92
}
93

94
// Response:
95
interface AlertResponse {
96
  alerts: Alert[];
97
  totalCount: number;
98
}
99
```
100

101
#### Update Alert Status
102

103
Resolve or update alert status.
104

105
```typescript { .api }
106
PUT /api/v1/alert/{alertId}
107

108
// Request Body:
109
interface UpdateAlertParams {
110
  status: Status;
111
  resolutionMessage?: string;
112
}
113
```
114

115
#### Batch Update Alerts
116

117
Update multiple alerts simultaneously.
118

119
```typescript { .api }
120
PUT /api/v1/alerts/batch
121

122
// Request Body:
123
interface BatchUpdateAlertParams {
124
  alertIds: string[];
125
  status: Status;
126
  resolutionMessage?: string;
127
}
128
```
129

130
### Data Collection API
131

132
#### Single Trace Ingestion
133

134
Submit individual API traces for analysis.
135

136
```typescript { .api }
137
POST /api/v1/log-request/single
138

139
// Request Body: TraceParams
140
// Response:
141
interface TraceIngestionResponse {
142
  success: boolean;
143
  message?: string;
144
}
145
```
146

147
#### Batch Trace Ingestion
148

149
Submit multiple API traces for efficient processing.
150

151
```typescript { .api }
152
POST /api/v1/log-request/batch
153

154
// Request Body:
155
interface BatchTraceParams {
156
  traces: TraceParams[];
157
}
158

159
// Response:
160
interface BatchIngestionResponse {
161
  success: boolean;
162
  processed: number;
163
  failed: number;
164
  errors?: string[];
165
}
166
```
167

168
### Testing API
169

170
#### Generate Security Tests
171

172
Generate automated security tests for endpoints.
173

174
```typescript { .api }
175
POST /api/v1/test/generate
176

177
// Request Body:
178
interface GenerateTestParams {
179
  type: string;                   // Test type (auth, sqli, xss, bola)
180
  endpoint: string;               // Target endpoint path
181
  host?: string;                  // Host for the endpoint
182
  method?: RestMethod;            // HTTP method
183
  version?: number;               // Template version
184
}
185

186
// Response:
187
interface GenerateTestResponse {
188
  success: boolean;
189
  testConfig?: TestConfig;
190
  templateName?: string;
191
  templateVersion?: number;
192
  message?: string;
193
}
194
```
195

196
#### Execute Test
197

198
Run a security test configuration.
199

200
```typescript { .api }
201
POST /api/v1/test/run
202

203
// Request Body:
204
interface RunTestParams {
205
  testConfig: TestConfig;
206
  context?: Record<string, any>;
207
}
208

209
// Response:
210
interface RunTestResponse {
211
  success: boolean;
212
  result: TestResult;
213
  duration: number;
214
}
215
```
216

217
#### List Test Templates
218

219
Retrieve available test templates.
220

221
```typescript { .api }
222
GET /api/v1/test/templates?type={type}
223

224
// Query Parameters:
225
interface GetTemplatesParams {
226
  type?: string;                  // Filter by test type
227
}
228

229
// Response:
230
interface TemplateResponse {
231
  templates: TestTemplate[];
232
}
233
```
234

235
### Summary and Analytics API
236

237
#### Platform Summary
238

239
Get high-level platform statistics and metrics.
240

241
```typescript { .api }
242
GET /api/v1/summary
243

244
// Response: Summary interface (comprehensive platform statistics)
245
```
246

247
#### Usage Statistics
248

249
Retrieve API usage and traffic patterns.
250

251
```typescript { .api }
252
GET /api/v1/usage?startDate={start}&endDate={end}&host={host}
253

254
// Query Parameters:
255
interface GetUsageParams {
256
  startDate?: string;             // ISO date string
257
  endDate?: string;               // ISO date string
258
  host?: string;                  // Filter by host
259
}
260

261
// Response:
262
interface UsageResponse {
263
  dailyUsage: Usage[];
264
  totalRequests: number;
265
  uniqueEndpoints: number;
266
  averageRPS: number;
267
}
268
```
269

270
#### Vulnerability Summary
271

272
Get vulnerability statistics and trends.
273

274
```typescript { .api }
275
GET /api/v1/vulnerabilities/summary
276

277
// Response: VulnerabilitySummary interface
278
```
279

280
#### PII Data Summary
281

282
Retrieve sensitive data exposure statistics.
283

284
```typescript { .api }
285
GET /api/v1/data-fields/summary
286

287
// Response: SensitiveDataSummary interface
288
```
289

290
### Configuration API
291

292
#### Update Metlo Configuration
293

294
Modify platform configuration settings.
295

296
```typescript { .api }
297
PUT /api/v1/config
298

299
// Request Body: UpdateMetloConfigParams
300
// Response: MetloConfigResp
301
```
302

303
#### Get Configuration
304

305
Retrieve current platform configuration.
306

307
```typescript { .api }
308
GET /api/v1/config
309

310
// Response: MetloConfigResp
311
```
312

313
#### Manage API Keys
314

315
Create and manage API keys for integrations.
316

317
```typescript { .api }
318
POST /api/v1/keys
319
GET /api/v1/keys
320
DELETE /api/v1/keys/{keyId}
321

322
// Create Request Body:
323
interface CreateApiKeyParams {
324
  name: string;
325
  for: API_KEY_TYPE;
326
}
327

328
// Response:
329
interface ApiKeyResponse {
330
  keys: ApiKey[];
331
}
332
```
333

334
### Webhook API
335

336
#### Configure Webhooks
337

338
Set up webhook endpoints for alert notifications.
339

340
```typescript { .api }
341
POST /api/v1/webhooks
342
PUT /api/v1/webhooks/{webhookId}
343
DELETE /api/v1/webhooks/{webhookId}
344
GET /api/v1/webhooks
345

346
// Create/Update Request Body:
347
interface WebhookConfigParams {
348
  url: string;
349
  maxRetries: number;
350
  alertTypes: AlertType[];
351
  hosts: string[];
352
}
353

354
// Response:
355
interface WebhookResponse {
356
  webhooks: WebhookResp[];
357
}
358
```
359

360
#### Test Webhook
361

362
Validate webhook endpoint configuration.
363

364
```typescript { .api }
365
POST /api/v1/webhooks/{webhookId}/test
366

367
// Response:
368
interface WebhookTestResponse {
369
  success: boolean;
370
  responseTime: number;
371
  statusCode: number;
372
  message: string;
373
}
374
```
375

376
### Host Management API
377

378
#### List Hosts
379

380
Retrieve monitored hosts and their statistics.
381

382
```typescript { .api }
383
GET /api/v1/hosts
384

385
// Response:
386
interface HostListResponse {
387
  hosts: HostResponse[];
388
  totalCount: number;
389
}
390
```
391

392
#### Host Graph
393

394
Get network topology and host relationships.
395

396
```typescript { .api }
397
GET /api/v1/hosts/graph
398

399
// Response: HostGraph interface
400
```
401

402
### OpenAPI Specification API
403

404
#### Manage API Specifications
405

406
Upload and manage OpenAPI/Swagger specifications.
407

408
```typescript { .api }
409
POST /api/v1/specs
410
GET /api/v1/specs
411
PUT /api/v1/specs/{specId}
412
DELETE /api/v1/specs/{specId}
413

414
// Upload Request Body:
415
interface UploadSpecParams {
416
  name: string;
417
  spec: string;                   // OpenAPI specification content
418
  hosts: string[];
419
}
420

421
// Response:
422
interface SpecResponse {
423
  specs: OpenApiSpec[];
424
}
425
```
426

427
#### Specification Diff
428

429
Compare API specifications for changes.
430

431
```typescript { .api }
432
POST /api/v1/specs/{specId}/diff
433

434
// Request Body:
435
interface SpecDiffParams {
436
  newSpec: string;
437
}
438

439
// Response:
440
interface SpecDiffResponse {
441
  changes: SpecChange[];
442
  addedEndpoints: string[];
443
  removedEndpoints: string[];
444
  modifiedEndpoints: string[];
445
}
446
```
447

448
### Attack Detection API
449

450
#### List Attacks
451

452
Retrieve detected security attacks.
453

454
```typescript { .api }
455
GET /api/v1/attacks?resolved={resolved}&attackTypes={types}&hosts={hosts}
456

457
// Query Parameters:
458
interface GetAttackParams {
459
  resolved?: boolean;
460
  attackTypes?: AttackType[];
461
  hosts?: string[];
462
  startTime?: string;
463
  endTime?: string;
464
  offset?: number;
465
  limit?: number;
466
}
467

468
// Response: AttackResponse interface
469
```
470

471
#### Attack Details
472

473
Get detailed information about a specific attack.
474

475
```typescript { .api }
476
GET /api/v1/attacks/{attackId}
477

478
// Response: AttackDetailResponse interface
479
```
480

481
#### Resolve Attack
482

483
Mark an attack as resolved or snoozed.
484

485
```typescript { .api }
486
PUT /api/v1/attacks/{attackId}
487

488
// Request Body:
489
interface ResolveAttackParams {
490
  resolved?: boolean;
491
  snoozed?: boolean;
492
  snoozeHours?: number;
493
}
494
```
495

496
## Authentication
497

498
All API endpoints require authentication using API keys:
499

500
```http
501
Authorization: Bearer {api_key}
502
Content-Type: application/json
503
```
504

505
## Error Responses
506

507
The API uses standard HTTP status codes and returns error details:
508

509
```typescript { .api }
510
interface ErrorResponse {
511
  success: false;
512
  error: string;
513
  details?: string;
514
  code?: string;
515
}
516
```
517

518
Common error codes:
519
- `400` - Bad Request (invalid parameters)
520
- `401` - Unauthorized (invalid API key)
521
- `403` - Forbidden (insufficient permissions)
522
- `404` - Not Found (resource not found)
523
- `429` - Too Many Requests (rate limited)
524
- `500` - Internal Server Error
525

526
## Rate Limiting
527

528
API endpoints are rate limited based on your plan:
529
- Free tier: 100 requests/minute
530
- Pro tier: 1000 requests/minute  
531
- Enterprise: Custom limits
532

533
Rate limit headers are included in all responses:
534

535
```http
536
X-RateLimit-Limit: 1000
537
X-RateLimit-Remaining: 999
538
X-RateLimit-Reset: 1640995200
539
```