Skip to main content
POST
/
v1
/
agents
/
{agentId}
/
suspend
Suspend Agent
curl --request POST \
  --url https://api.truthlocks.com/v1/agents/{agentId}/suspend \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "reason": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_type": "orchestrator",
  "display_name": "<string>",
  "description": "<string>",
  "status": "active",
  "scopes": [
    "<string>"
  ],
  "metadata": {},
  "trust_score": 0.5,
  "public_key": "<string>",
  "session_count": 123,
  "keys": [
    {
      "kid": "<string>",
      "algorithm": "<string>",
      "public_key": "<string>",
      "status": "active"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

​
Suspend Agent

POST /v1/agents/{agentID}/suspend Suspends a machine agent identity, immediately preventing it from creating new sessions, invoking tools, or performing any authenticated operations. Suspension is reversible — the agent can be reactivated by updating its status back to "active" via the update endpoint. All active sessions belonging to the suspended agent are effectively blocked at the access-control layer. Existing session tokens will fail scope checks until the agent is reactivated.
Suspension is the recommended first response for anomalous agent behavior. Use revoke only when permanent decommissioning is required.

​
Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

​
Path Parameters

​
agentID
string
required
The MAIP agent identifier (e.g., maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH).

​
Request Body

​
reason
string
required
Human-readable explanation for the suspension. Recorded in the audit log for compliance review. Maximum 1024 characters.

​
Response

​
status
string
Updated status, always "suspended" on success.
​
agent_id
string
The MAIP agent identifier that was suspended.

​
Example

curl -X POST https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH/suspend \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Anomalous data access pattern detected by velocity scoring at 2026-04-06T15:00:00Z"
  }'

​
Reactivating a Suspended Agent

To restore a suspended agent to active status, use the PATCH /v1/agents/ endpoint: 
curl -X PATCH https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Path Parameters

​
agentId
string<uuid>
required

Agent identifier

Body

application/json
​
reason
string
required

Human-readable reason for suspension

Response

Agent suspended

​
id
string<uuid>
​
agent_type
enum<string>
Available options:
orchestrator,
worker,
inference,
pipeline,
service,
bot,
llm
​
display_name
string
Maximum string length: 256
​
description
string
​
status
enum<string>
Available options:
active,
suspended,
revoked
​
scopes
string[]
​
metadata
object
​
trust_score
number<float>
Required range: 0 <= x <= 1
​
public_key
string

Base64-encoded public key

​
session_count
integer
​
keys
object[]
​
created_at
string<date-time>
​
updated_at
string<date-time>