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

​
Get Agent

GET /v1/agents/{agentID} Returns the complete agent identity record for the specified agent, including cryptographic key information, current trust score, assigned scopes, delegation depth, and all metadata. The agent must belong to the authenticated tenant.

​
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).

​
Response

​
id
string
Internal UUID primary key.
​
agent_id
string
MAIP-compliant agent identifier.
​
tenant_id
string
UUID of the owning tenant.
​
agent_type
string
Agent type classification.
​
display_name
string
Human-readable agent name.
​
description
string
Agent description.
​
trust_level
string
Trust hierarchy level. One of: "platform_root", "verified_org", "verified_individual", "authenticated", "self_asserted", "anonymous".
​
trust_score
number
Numeric trust score between 0.0 and 1.0. Adjusted over time based on agent behavior, anomaly detection, and attestation history.
​
status
string
Current lifecycle status: "active", "suspended", or "revoked".
​
public_key
string
Base64url-encoded Ed25519 public key for this agent.
​
key_id
string
Unique key identifier for receipt and attestation signature verification.
​
scopes
string[]
Assigned permission scopes in resource:action format.
​
metadata
object
Arbitrary metadata attached to the agent.
​
parent_agent_id
string
If this agent was created via delegation, the parent agent’s MAIP ID.
​
delegation_depth
number
Position in the delegation chain (0 = root, max 8).
​
created_by_user_id
string
UUID of the user who registered the agent, if applicable.
​
compromised_at
string
ISO 8601 timestamp if the agent’s key was marked compromised.
​
expires_at
string
Automatic expiration timestamp, if configured.
​
created_at
string
ISO 8601 creation timestamp.
​
updated_at
string
ISO 8601 last-updated timestamp.

​
Example

curl https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH \
  -H "X-API-Key: tl_live_..."

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Path Parameters

​
agentId
string<uuid>
required

Agent identifier

Response

Agent details

​
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>