Skip to main content
POST
/
v1
/
agents
/
{agentId}
/
trust
/
compute
Recompute Trust Score
curl --request POST \
  --url https://api.truthlocks.com/v1/agents/{agentId}/trust/compute \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "include_factors": true
}
'
{
  "score": 0.5,
  "factors": {},
  "deltas": {},
  "computed_at": "2023-11-07T05:31:56Z"
}
Triggers an on-demand recomputation of the trust score for a specific agent. The score is derived from multiple weighted factors including anomaly rate, uptime history, delegation depth, and receipt volume. Use this endpoint after a significant event (key rotation, policy violation, attestation burst) to ensure the score reflects the agent’s current posture. Trust scores range from 0.0 (no trust) to 1.0 (full trust) and are used by policy engines, witness selection, and delegation gates across the platform.

​
Authentication

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

​
Path Parameters

​
agent_id
string
required
The unique identifier of the machine agent whose trust score should be recomputed. Format: maip-agent:ULID.

​
Request Body

​
include_history
boolean
default:"false"
When true, the response includes the full factor history used during computation. Useful for debugging score changes but increases response size.

​
Response

​
agent_id
string
The agent identifier that was scored.
​
score
number
The computed trust score as a float between 0.0 and 1.0.
​
factors
object
Breakdown of the individual factors that contributed to the score.
​
computed_at
string
ISO 8601 timestamp of when the computation completed.

​
Score Factor Weights

FactorWeightDescription
anomaly_rate30%Penalizes agents with high anomaly ratios
uptime25%Rewards consistent availability
delegation_depth20%Deeper chains reduce trust proportionally
receipt_count25%More receipts indicate established history

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
​
include_factors
boolean
default:true

Whether to include individual factor breakdown

Response

Recomputed trust score

​
score
number<float>
Required range: 0 <= x <= 1
​
factors
object
​
deltas
object
​
computed_at
string<date-time>