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>"
}
'

import requests

url = "https://api.truthlocks.com/v1/agents/{agentId}/suspend"

payload = { "reason": "<string>" }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({reason: '<string>'})
};

fetch('https://api.truthlocks.com/v1/agents/{agentId}/suspend', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.truthlocks.com/v1/agents/{agentId}/suspend",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.truthlocks.com/v1/agents/{agentId}/suspend"

	payload := strings.NewReader("{\n  \"reason\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.truthlocks.com/v1/agents/{agentId}/suspend")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.truthlocks.com/v1/agents/{agentId}/suspend")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

POST

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>"
}
'

import requests

url = "https://api.truthlocks.com/v1/agents/{agentId}/suspend"

payload = { "reason": "<string>" }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({reason: '<string>'})
};

fetch('https://api.truthlocks.com/v1/agents/{agentId}/suspend', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.truthlocks.com/v1/agents/{agentId}/suspend",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.truthlocks.com/v1/agents/{agentId}/suspend"

	payload := strings.NewReader("{\n  \"reason\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.truthlocks.com/v1/agents/{agentId}/suspend")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.truthlocks.com/v1/agents/{agentId}/suspend")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}

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

string

required

The MAIP agent identifier (e.g., maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH).

Request Body

string

required

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

Response

string

Updated status, always "suspended" on success.

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

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[]

Show child attributes

created_at

string<date-time>

updated_at

string<date-time>

​Suspend Agent

​Authentication

​Path Parameters

​Request Body

​Response

​Example

​Reactivating a Suspended Agent

Authorizations

Path Parameters

Body

Response

Suspend Agent

Authentication

Path Parameters

Request Body

Response

Example

Reactivating a Suspended Agent