Update Agent

curl --request PATCH \
  --url https://api.truthlocks.com/v1/agents/{agentId} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "display_name": "<string>",
  "description": "<string>",
  "scopes": [
    "<string>"
  ],
  "metadata": {}
}
'

import requests

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

payload = {
    "display_name": "<string>",
    "description": "<string>",
    "scopes": ["<string>"],
    "metadata": {}
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    display_name: '<string>',
    description: '<string>',
    scopes: ['<string>'],
    metadata: {}
  })
};

fetch('https://api.truthlocks.com/v1/agents/{agentId}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'display_name' => '<string>',
    'description' => '<string>',
    'scopes' => [
        '<string>'
    ],
    'metadata' => [
        
    ]
  ]),
  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}"

	payload := strings.NewReader("{\n  \"display_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api.truthlocks.com/v1/agents/{agentId}")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"display_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"display_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\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
}

PATCH

agents

{agentId}

Update Agent

curl --request PATCH \
  --url https://api.truthlocks.com/v1/agents/{agentId} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "display_name": "<string>",
  "description": "<string>",
  "scopes": [
    "<string>"
  ],
  "metadata": {}
}
'

import requests

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

payload = {
    "display_name": "<string>",
    "description": "<string>",
    "scopes": ["<string>"],
    "metadata": {}
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    display_name: '<string>',
    description: '<string>',
    scopes: ['<string>'],
    metadata: {}
  })
};

fetch('https://api.truthlocks.com/v1/agents/{agentId}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'display_name' => '<string>',
    'description' => '<string>',
    'scopes' => [
        '<string>'
    ],
    'metadata' => [
        
    ]
  ]),
  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}"

	payload := strings.NewReader("{\n  \"display_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api.truthlocks.com/v1/agents/{agentId}")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"display_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"display_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"scopes\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\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
}

Update Agent

PATCH /v1/agents/{agentID} Updates mutable fields on an existing machine agent identity. Only the fields provided in the request body are modified; all other fields remain unchanged. At least one field must be provided.

To change an agent’s scopes, use the delegation system or re-register the agent. Scopes cannot be modified directly through this endpoint to preserve the audit trail of scope changes.

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

All fields are optional, but at least one must be provided.

string

Updated human-readable name. Maximum 256 characters.

string

Updated description. Maximum 2048 characters.

object

Replacement metadata object. Replaces the entire metadata field (not a merge). Maximum 16 KB serialized.

string

Update the agent’s lifecycle status. One of: "active", "suspended". Use the dedicated suspend or revoke endpoints for status changes that require a reason for audit compliance.

Response

Returns the full updated agent identity object.

string

Internal UUID primary key.

string

MAIP-compliant agent identifier.

string

The updated display name.

string

The updated description.

object

The updated metadata object.

string

Current lifecycle status after update.

string

ISO 8601 timestamp reflecting the update.

Example

curl -X PATCH https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Customer Support Bot v2",
    "description": "Upgraded to handle Tier-1 and Tier-2 support with escalation",
    "metadata": {
      "team": "support",
      "model": "claude-opus-4",
      "environment": "production",
      "version": "2.0"
    }
  }'

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

display_name

string

Maximum string length: 256

description

string

scopes

string[]

metadata

object

Response

Agent updated

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>

​Update Agent

​Authentication

​Path Parameters

​Request Body

​Response

​Example

Authorizations

Path Parameters

Body

Response

Update Agent

Authentication

Path Parameters

Request Body

Response

Example