Skip to main content
POST
/
v1
/
anomalies
Report Anomaly
curl --request POST \
  --url https://api.truthlocks.com/v1/anomalies \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "anomaly_type": "<string>",
  "severity": "low",
  "details": {}
}
'
{
  "anomaly_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "anomaly_type": "<string>",
  "severity": "low",
  "details": {},
  "status": "open",
  "resolution": "<string>",
  "resolved_by": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "resolved_at": "2023-11-07T05:31:56Z"
}
Reports a behavioral anomaly detected in an AI agent’s activity. Anomalies are flagged observations that indicate an agent may be operating outside its expected behavioral envelope — such as sudden rate spikes, scope violations, trust score drops, or geographic access anomalies. Anomaly reports create actionable alerts for security teams and can trigger automated response policies (e.g., throttling, session revocation, or agent suspension) depending on severity and tenant configuration.

​
Anomaly Types

TypeDescription
rate_spikeAgent’s request rate significantly exceeds historical baseline
scope_violationAgent attempted to access a resource outside its granted scopes
trust_dropAgent’s computed trust score dropped below threshold
pattern_deviationAgent’s behavioral pattern deviates from its trained baseline
geographic_anomalyAgent accessed from an unexpected geographic location or IP range

​
Severity Levels

SeveritySLAAuto-Response
low24h reviewLogged only
medium4h reviewAgent throttled
high1h reviewSessions suspended
critical15min reviewAgent revoked pending investigation

​
Authentication

​
X-API-Key
string
required
API key with anomalies:write scope. Alternatively, pass a Bearer JWT token in the Authorization header.
​
X-Tenant-ID
string
required
Tenant identifier for multi-tenant isolation.

​
Request

​
agent_id
string
required
MAIP agent identifier exhibiting the anomalous behavior.
​
anomaly_type
string
required
Type of anomaly detected. Must be one of: rate_spike, scope_violation, trust_drop, pattern_deviation, geographic_anomaly.
​
severity
string
required
Severity level. Must be one of: low, medium, high, critical.
​
description
string
Human-readable description of the anomaly and its potential impact.
​
evidence
object
Structured evidence supporting the anomaly report. Contents vary by anomaly type: - For rate_spike: baseline_rps, observed_rps, window_seconds - For scope_violation: attempted_scope, granted_scopes, resource_id - For trust_drop: previous_score, current_score, threshold - For pattern_deviation: expected_pattern, observed_pattern, deviation_score
  • For geographic_anomaly: expected_regions, observed_ip, observed_country

​
Response

​
id
string
Unique anomaly identifier in MAIP format (maip-anom:ULID).
​
agent_id
string
The agent associated with the anomaly.
​
anomaly_type
string
Type of anomaly reported.
​
severity
string
Severity level.
​
status
string
Anomaly status. Always open on creation.
​
auto_response
string
Automated response action taken (if any), based on severity and tenant policy.
​
created_at
string
ISO 8601 timestamp of creation.

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
agent_id
string<uuid>
required

Agent exhibiting the anomaly

​
anomaly_type
string
required

Classification (e.g. scope_escalation, unusual_volume, auth_failure_burst)

​
severity
enum<string>
required

Severity classification

Available options:
low,
medium,
high,
critical
​
details
object

Anomaly details and context

Response

Anomaly reported

​
anomaly_id
string<uuid>
​
agent_id
string<uuid>
​
anomaly_type
string
​
severity
enum<string>
Available options:
low,
medium,
high,
critical
​
details
object
​
status
enum<string>
Available options:
open,
investigating,
resolved,
dismissed
​
resolution
string
​
resolved_by
string
​
created_at
string<date-time>
​
resolved_at
string<date-time>