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 '
{
  "description": "<string>",
  "display_name": "<string>",
  "metadata": "<unknown>",
  "status": "<string>"
}
'

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

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

import requests

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

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

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

print(response.text)

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"description\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"metadata\": \"<unknown>\",\n  \"status\": \"<string>\"\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))

}

{
  "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 '
{
  "description": "<string>",
  "display_name": "<string>",
  "metadata": "<unknown>",
  "status": "<string>"
}
'

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

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

import requests

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

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

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

print(response.text)

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"description\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"metadata\": \"<unknown>\",\n  \"status\": \"<string>\"\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))

}

{
  "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. The workspace is derived from the authenticated credential; do not send X-Tenant-ID.

Request Body

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

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

description

string | null

display_name

string | null

Maximum string length: 256

metadata

any

status

string | null

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

​Request Body

​Response

​Example

Authorizations

Path Parameters

Body

Response

Update Agent

Authentication

Request Body

Response

Example