> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Report Anomaly
> Report a behavioral anomaly detected in an AI agent's activity.
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
| Type | Description |
| :------------------- | :---------------------------------------------------------------- |
| `rate_spike` | Agent's request rate significantly exceeds historical baseline |
| `scope_violation` | Agent attempted to access a resource outside its granted scopes |
| `trust_drop` | Agent's computed trust score dropped below threshold |
| `pattern_deviation` | Agent's behavioral pattern deviates from its trained baseline |
| `geographic_anomaly` | Agent accessed from an unexpected geographic location or IP range |
### Severity Levels
| Severity | SLA | Auto-Response |
| :--------- | :----------- | :---------------------------------- |
| `low` | 24h review | Logged only |
| `medium` | 4h review | Agent throttled |
| `high` | 1h review | Sessions suspended |
| `critical` | 15min review | Agent revoked pending investigation |
### Authentication
API key with `anomalies:write` scope. Alternatively, pass a Bearer JWT token
in the `Authorization` header.
Tenant identifier for multi-tenant isolation.
### Request
MAIP agent identifier exhibiting the anomalous behavior.
Type of anomaly detected. Must be one of: `rate_spike`, `scope_violation`,
`trust_drop`, `pattern_deviation`, `geographic_anomaly`.
Severity level. Must be one of: `low`, `medium`, `high`, `critical`.
Human-readable description of the anomaly and its potential impact.
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
Unique anomaly identifier in MAIP format (`maip-anom:ULID`).
The agent associated with the anomaly.
Type of anomaly reported.
Severity level.
Anomaly status. Always `open` on creation.
Automated response action taken (if any), based on severity and tenant policy.
ISO 8601 timestamp of creation.
## OpenAPI
````yaml mint-openapi.yaml POST /v1/agents/{agentId}/anomalies
openapi: 3.0.3
info:
title: Truthlocks API
description: >
Truthlocks is a universal verification infrastructure for documents,
credentials, and digital assets.
This specification defines the canonical API for interacting with Truthlocks
services.
## Base URLs
- **Production**: `https://api.truthlocks.com`
- **Sandbox**: `https://sandbox-api.truthlocks.com`
## Authentication
- **API Keys**: Use `X-API-Key` header for machine-to-machine operations
- **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated
operations
## Tenant Identity
In production, tenant identity is derived from the authenticated context
(API key or JWT).
The `X-Tenant-ID` header is ignored in production to prevent spoofing.
version: 1.0.0
contact:
name: Truthlocks Support
url: https://truthlocks.com/support
email: support@truthlocks.com
servers:
- url: https://api.truthlocks.com
description: Production API
- url: https://sandbox-api.truthlocks.com
description: Sandbox Environment
security:
- APIKey: []
tags:
- name: Authentication
description: API key and token management
- name: Issuers
description: Issuer registration and trust management
- name: Keys
description: Cryptographic key management for issuers
- name: Attestations
description: Attestation lifecycle (mint, revoke, supersede)
- name: Verification
description: Attestation verification and proof bundles
- name: Governance
description: Issuer governance workflows (admin only)
- name: Identity
description: Organization, user, and role management
- name: Audit
description: Audit event queries
- name: Platform
description: Platform administration (super admin only)
- name: Platform Review
description: Staff review workflows for issuer applications
- name: Tenant Console
description: Tenant profile and lifecycle endpoints
- name: Health
description: Service health and readiness endpoints
- name: Risk
description: Risk signal ingestion and fraud detection
- name: Risk Enforcement
description: Risk enforcement actions — block, challenge, quarantine, and configuration
- name: Billing
description: Billing, subscription, and addon management
- name: Machine Identity
description: >-
Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
trust, witness, compliance, orchestration, and observability
externalDocs:
description: Transparency read-only API (separate service spec)
url: >-
https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
/v1/agents/{agentId}/anomalies:
post:
tags:
- Machine Identity
summary: Report Anomaly
description: |
Reports a behavioral or security anomaly detected for an agent.
Anomalies are tracked and may affect the agent trust score.
operationId: maip.anomalies.report
parameters:
- name: agentId
in: path
required: true
schema:
type: string
format: uuid
description: Agent identifier
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- anomaly_type
- severity
properties:
anomaly_type:
type: string
description: >-
Classification (e.g. scope_escalation, unusual_volume,
auth_failure_burst)
severity:
type: string
enum:
- low
- medium
- high
- critical
description: Severity classification
description:
type: string
description: Human-readable description of the anomaly
evidence:
type: object
additionalProperties: true
description: Structured evidence supporting the anomaly report
responses:
'201':
description: Anomaly reported
content:
application/json:
schema:
$ref: '#/components/schemas/MaipAnomaly'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- APIKey: []
components:
schemas:
MaipAnomaly:
type: object
properties:
anomaly_id:
type: string
format: uuid
agent_id:
type: string
format: uuid
anomaly_type:
type: string
severity:
type: string
enum:
- low
- medium
- high
- critical
details:
type: object
additionalProperties: true
status:
type: string
enum:
- open
- investigating
- resolved
- dismissed
resolution:
type: string
resolved_by:
type: string
created_at:
type: string
format: date-time
resolved_at:
type: string
format: date-time
ErrorEnvelope:
type: object
required:
- code
- message
- http_status
properties:
code:
type: string
description: Machine-readable error code
enum:
- AUTH_REQUIRED
- AUTH_INVALID
- PERMISSION_DENIED
- TENANT_IDENTITY_UNVERIFIED
- NOT_FOUND
- VALIDATION_ERROR
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
message:
type: string
description: Human-readable error message
http_status:
type: integer
description: HTTP status code
retry_after_ms:
type: integer
description: Milliseconds to wait before retrying (for rate limits)
details:
type: object
description: Additional error context
example:
code: AUTH_REQUIRED
message: Authentication required
http_status: 401
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
````