Skip to main content
The Alerts API allows you to retrieve and manage security alerts that Metlo has detected in your API traffic.

​
List Alerts

Retrieve a list of security alerts with optional filtering.
cURL
curl 'https://<your-metlo-instance>/api/v1/alerts?limit=20&offset=0' \
  -H 'Authorization: metlo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

​
Query Parameters

​
uuid
uuid
Filter by specific alert UUID
​
apiEndpointUuid
uuid
Filter by endpoint UUID
​
riskScores
enum[]
Filter by risk scores: HIGH, MEDIUM, LOW, NONE
​
status
enum[]
Filter by alert status: RESOLVED, IGNORED, etc.
​
alertTypes
enum[]
Filter by alert types (e.g., UNAUTHENTICATED_ENDPOINT, PII_DATA_DETECTED, OPEN_API_SPEC_DIFF)
​
hosts
string[]
Filter by hostnames
​
offset
number
default:"0"
Number of results to skip for pagination
​
limit
number
default:"10"
Maximum number of results to return
​
order
enum
default:"DESC"
Sort order: ASC or DESC

​
Response

​
alerts
Alert[]
Array of alert objects
Response Example
[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "type": "PII_DATA_DETECTED",
    "riskScore": "HIGH",
    "apiEndpointUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "apiEndpoint": {
      "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "method": "GET",
      "host": "api.example.com",
      "path": "/api/users/{id}",
      "openapiSpecName": "users-api-v1"
    },
    "description": "Sensitive data detected in response: Email, SSN",
    "status": "UNRESOLVED",
    "resolutionMessage": null,
    "context": {
      "dataClasses": ["email", "ssn"],
      "sections": ["RESPONSE_BODY"]
    },
    "createdAt": "2026-03-03T10:30:00.000Z",
    "updatedAt": "2026-03-03T10:30:00.000Z"
  },
  {
    "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "type": "UNAUTHENTICATED_ENDPOINT",
    "riskScore": "MEDIUM",
    "apiEndpointUuid": "8d3f2a1b-4c5e-6d7f-8a9b-0c1d2e3f4a5b",
    "apiEndpoint": {
      "uuid": "8d3f2a1b-4c5e-6d7f-8a9b-0c1d2e3f4a5b",
      "method": "POST",
      "host": "api.example.com",
      "path": "/api/admin/users",
      "openapiSpecName": "admin-api-v1"
    },
    "description": "Endpoint accessible without authentication",
    "status": "RESOLVED",
    "resolutionMessage": "Added authentication middleware",
    "context": {},
    "createdAt": "2026-03-01T14:20:00.000Z",
    "updatedAt": "2026-03-02T09:15:00.000Z"
  }
]

​
Alert Types

Metlo can detect various types of security issues:
Personally Identifiable Information (PII) detected in API requests or responses.
Endpoint is accessible without proper authentication.
Differences detected between actual API behavior and OpenAPI specification.
Sensitive data being sent in query parameters (should be in body).
Sensitive data exposed in URL paths.
Use of basic authentication (should use more secure methods).
Endpoint accessible over HTTP instead of HTTPS.

​
Update Alert

Update the status of a specific alert.
cURL
curl -X PUT 'https://<your-metlo-instance>/api/v1/alert/{alertId}' \
  -H 'Authorization: metlo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "updateType": "RESOLVE",
    "resolutionMessage": "Fixed by implementing authentication"
  }'

​
Path Parameters

​
alertId
uuid
required
The unique identifier of the alert

​
Request Body

​
updateType
enum
required
Type of update to apply:
  • RESOLVE: Mark the alert as resolved
  • IGNORE: Ignore the alert
  • UNRESOLVE: Reopen a resolved alert
​
resolutionMessage
string
Optional message describing how the issue was resolved or why it’s being ignored

​
Response

​
alert
Alert
The updated alert object
Response Example
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "type": "UNAUTHENTICATED_ENDPOINT",
  "riskScore": "MEDIUM",
  "status": "RESOLVED",
  "resolutionMessage": "Fixed by implementing authentication",
  "updatedAt": "2026-03-03T12:00:00.000Z"
}

​
Update Multiple Alerts

Update multiple alerts at once using filter criteria.
cURL
curl -X PUT 'https://<your-metlo-instance>/api/v1/alerts' \
  -H 'Authorization: metlo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "updateType": "RESOLVE",
    "resolutionMessage": "Bulk resolution after security review",
    "riskScores": ["LOW"],
    "alertTypes": ["QUERY_SENSITIVE_DATA"],
    "hosts": ["staging.api.example.com"]
  }'

​
Request Body

​
updateType
enum
required
Type of update: RESOLVE, IGNORE, or UNRESOLVE
​
resolutionMessage
string
Optional resolution or ignore message
​
uuid
uuid
Filter by specific alert UUID
​
apiEndpointUuid
uuid
Filter by endpoint UUID
​
riskScores
enum[]
Filter by risk scores: HIGH, MEDIUM, LOW, NONE
​
status
enum[]
Filter by current status
​
alertTypes
enum[]
Filter by alert types
​
hosts
string[]
Filter by hostnames

​
Response

null
Returns null on success with HTTP status 200.
Be careful with batch updates - they will affect all alerts matching the specified filters.

​
Alert Object Structure

​
Alert Fields

​
uuid
string
Unique identifier for the alert
​
type
enum
Type of security issue detected
​
riskScore
enum
Severity level: HIGH, MEDIUM, LOW, or NONE
​
apiEndpointUuid
string
UUID of the affected endpoint
​
apiEndpoint
object
Summary information about the affected endpoint
​
description
string
Human-readable description of the alert
​
status
enum
Current status of the alert
​
resolutionMessage
string
Message explaining resolution or why alert was ignored
​
context
object
Additional context specific to the alert type
​
createdAt
string
ISO 8601 timestamp when alert was created
​
updatedAt
string
ISO 8601 timestamp when alert was last updated

​
Common Use Cases

​
Get All High-Risk Unresolved Alerts

curl 'https://<your-metlo-instance>/api/v1/alerts?riskScores=HIGH&status=UNRESOLVED' \
  -H 'Authorization: metlo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

​
Get Alerts for a Specific Endpoint

curl 'https://<your-metlo-instance>/api/v1/alerts?apiEndpointUuid=550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: metlo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

​
Resolve All Alerts for a Host

curl -X PUT 'https://<your-metlo-instance>/api/v1/alerts' \
  -H 'Authorization: metlo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "updateType": "RESOLVE",
    "resolutionMessage": "Host decommissioned",
    "hosts": ["old-api.example.com"]
  }'

​
Ignore Low-Priority Alerts

curl -X PUT 'https://<your-metlo-instance>/api/v1/alerts' \
  -H 'Authorization: metlo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "updateType": "IGNORE",
    "resolutionMessage": "Accepted risk for staging environment",
    "riskScores": ["LOW"],
    "hosts": ["staging.api.example.com"]
  }'

​
Error Responses

​
400 Bad Request

{
  "type": "ZOD",
  "message": "Invalid parameters",
  "err": {}
}
Returned when query parameters or request body fail validation.

​
404 Not Found

"Alert does not exist."
Returned when the specified alert UUID is not found.

​
Best Practices

Alert Management Tips

  • Prioritize by Risk Score: Focus on HIGH risk alerts first
  • Add Context: Always include meaningful resolution messages
  • Regular Review: Periodically review ignored alerts to ensure they’re still acceptable
  • Automate Responses: Use the API to integrate alert management into your workflows
  • Monitor Trends: Track alert types over time to identify recurring issues

Build docs developers (and LLMs) love

Get started for freeTalk to us