Documentation

TrustGraph API Reference

The TrustGraph API is a RESTful HTTP API that returns trust scores, evidence graphs, and signed receipts for any entity, claim, or transaction. All requests are authenticated with an API key and all responses are JSON.

Authentication

All API requests must include your API key in the X-API-Key header. You can generate a key from your dashboard after signing up.

http

X-API-Key: sk_trust_your_key_here

Never expose your API key in client-side code or public repositories. Rotate compromised keys immediately from your dashboard.

Base URL

All API endpoints are versioned under /v1.

text

https://api.odemicroservices.llewellynsystems.com/v1

POST /trust/score

POSThttps://api.odemicroservices.llewellynsystems.com/v1/trust/score

Submit an entity, claim, or transaction for trust scoring. Specify which dimensions you want evaluated. Results are returned synchronously with a signed receipt.

bash

curl -X POST https://api.odemicroservices.llewellynsystems.com/v1/trust/score \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_trust_your_key_here" \
  -d '{
    "entity_id": "usr_7f3a9b2e",
    "entity_type": "user",
    "dimensions": ["identity", "behavior", "permission"],
    "context": {
      "platform": "marketplace",
      "transaction_value": 4500,
      "region": "us-east-1"
    }
  }'

Request Body

Field	Type	Required	Description
`entity_id`	string	Yes	Your unique identifier for the entity being scored
`entity_type`	string	Yes	One of: user, organization, content, transaction, claim
`dimensions`	string[]	Yes	Array of dimension keys to score (e.g. ["identity", "behavior"])
`context`	object	No	Arbitrary key-value pairs providing scoring context (platform, region, value, etc.)

Response

A successful request returns HTTP 200 with the following JSON body:

json

{
  "score": 87,
  "confidence": 0.94,
  "receipt_id": "treceipt_01J4X8KZ3WNQ5BV0GFPRTMYD7C",
  "scored_at": "2026-05-14T09:22:11.432Z",
  "entity_id": "usr_7f3a9b2e",
  "entity_type": "user",
  "dimensions": {
    "identity": { "score": 91, "weight": 0.40, "signals": 14, "verdict": "verified" },
    "behavior": { "score": 83, "weight": 0.35, "signals": 22, "verdict": "normal" },
    "permission": { "score": 88, "weight": 0.25, "signals": 7, "verdict": "authorized" }
  },
  "evidence_graph": {
    "nodes": 43,
    "edges": 61,
    "graph_id": "egraph_9fk2mq7"
  },
  "flags": []
}

Available Dimensions

Use the key values in your dimensions array. Starter plan provides identity and source only. Professional and Enterprise unlock all eight.

Key	Dimension	Description
`identity`	Identity Trust	Verify who the entity is
`source`	Source Trust	Trace provenance and chain of custody
`claim`	Claim Trust	Factual accuracy against knowledge graphs
`content`	Content Trust	Detect synthetic or manipulated content
`transaction`	Transaction Trust	Risk and settlement confidence
`behavior`	Behavior Trust	Anomaly detection across sequences
`permission`	Permission Trust	Authorization and delegation chains
`deliverable`	Deliverable Trust	Evidence-backed completion

Trust Receipt Schema

Every response includes a trust receipt. On Professional and above, the receipt is HMAC-signed. Store the receipt_id for your audit trail.

json

{
  "receipt_id":   "string   — immutable receipt UUID (treceipt_...)",
  "score":        "integer  — 0-100 composite trust score",
  "confidence":   "float    — 0.0-1.0 model confidence",
  "scored_at":    "string   — ISO 8601 UTC timestamp",
  "entity_id":    "string   — your identifier for this entity",
  "entity_type":  "string   — user | organization | content | transaction | claim",
  "dimensions":   "object   — per-dimension breakdown (see above)",
  "evidence_graph": {
    "nodes":      "integer  — number of evidence nodes traversed",
    "edges":      "integer  — number of graph relationships evaluated",
    "graph_id":   "string   — reference ID for graph replay"
  },
  "flags":        "string[] — anomaly flags, empty if clean",
  "signature":    "string   — HMAC-SHA256 receipt signature (Professional+)"
}

Evidence Graph Schema

The evidence graph is available on Professional and above via GET /trust/graph/{graph_id}. It exposes every node and relationship the scoring engine traversed.

json

{
  "graph_id": "egraph_9fk2mq7",
  "nodes": [
    {
      "id":     "string  — node identifier",
      "type":   "string  — identity_provider | behavior_log | permission_record | ...",
      "weight": "float   — relative influence on score (0.0-1.0)",
      "label":  "string  — human-readable node description"
    }
  ],
  "edges": [
    {
      "from":       "string  — source node id",
      "to":         "string  — target node id",
      "relation":   "string  — corroborates | contradicts | delegates | inherits",
      "confidence": "float   — edge confidence score"
    }
  ]
}

Error Codes

HTTP	Code	Description
400	`bad_request`	Malformed request body or missing required fields
401	`unauthorized`	Missing or invalid X-API-Key header
402	`quota_exceeded`	Daily check quota reached for your plan
404	`entity_not_found`	entity_id could not be resolved in any dimension
422	`dimension_unavailable`	Requested dimension not available on your plan
429	`rate_limited`	Too many requests; back off and retry
500	`internal_error`	TrustGraph engine error; retry with exponential backoff