Skip to main content

​
Mnemom Trust Rating API

The Trust Rating API provides programmatic access to Mnemom Trust Ratings, historical trends, embeddable badges, directory search, bulk lookups, and aggregate benchmarks. All reputation data is computed from independently verified AIP integrity checkpoints. Base URL: https://api.mnemom.ai/v1/reputation

​
Authentication

EndpointAuth RequiredNotes
GET /v1/reputation/{agent_id}NoPublic score retrieval
GET /v1/reputation/{agent_id}/historyNoPublic history
GET /v1/reputation/{agent_id}/badge.svgNoPublic badge
GET /v1/reputation/{agent_id}/verifyNoCryptographic verification
POST /v1/reputation/batchAPI keyBulk score retrieval
GET /v1/reputation/searchAPI keyDirectory search
GET /v1/reputation/compareAPI keySide-by-side comparison
GET /v1/reputation/benchmarksNoAggregate statistics
API key authentication: Pass in the Authorization header: 
Authorization: Bearer {api_key}
API keys can be created in your dashboard under Settings or via POST /v1/api-keys.

​
Rate Limits

EndpointRate LimitWindow
GET /reputation/{agent_id}100 requestsper minute
GET /reputation/{agent_id}/history60 requestsper minute
GET /reputation/{agent_id}/badge.svg300 requestsper minute
GET /reputation/{agent_id}/verify30 requestsper minute
POST /reputation/batch30 requestsper minute
GET /reputation/search60 requestsper minute
GET /reputation/compare60 requestsper minute
GET /reputation/benchmarks30 requestsper minute
Rate-limited responses return HTTP 429 with a Retry-After header.

​
Endpoints

​
GET /v1/reputation/

Retrieve the full reputation score for an agent, including all five component scores, trend data, and confidence level. Parameters:
ParameterInTypeRequiredDescription
agent_idpathstringYesAgent identifier
Response: 200 OK 
{
  "agent_id": "agent-xyz",
  "score": 782,
  "grade": "A",
  "tier": "Reliable",
  "is_eligible": true,
  "checkpoint_count": 347,
  "confidence": "medium",
  "components": [
    {
      "key": "integrity_ratio",
      "label": "Integrity Ratio",
      "score": 920,
      "weight": 0.40,
      "weighted_score": 368,
      "factors": ["97.2% clear verdict rate across 347 checkpoints"]
    },
    {
      "key": "compliance",
      "label": "Compliance",
      "score": 850,
      "weight": 0.20,
      "weighted_score": 170,
      "factors": ["No violations in past 14 days"]
    },
    {
      "key": "drift_stability",
      "label": "Drift Stability",
      "score": 700,
      "weight": 0.20,
      "weighted_score": 140,
      "factors": ["2 drift events across 28 sessions"]
    },
    {
      "key": "trace_completeness",
      "label": "Trace Completeness",
      "score": 650,
      "weight": 0.10,
      "weighted_score": 65,
      "factors": ["65% of expected decisions logged"]
    },
    {
      "key": "coherence_compatibility",
      "label": "Coherence Compatibility",
      "score": 390,
      "weight": 0.10,
      "weighted_score": 39,
      "factors": ["Mean coherence 0.39 across 3 fleet interactions"]
    }
  ],
  "computed_at": "2026-02-21T14:00:00.000Z",
  "trend_30d": 12,
  "visibility": "public",
  "a2a_trust_extension": {
    "provider": "mnemom",
    "score": 782,
    "grade": "A",
    "verified_url": "https://api.mnemom.ai/v1/reputation/agent-xyz",
    "badge_url": "https://api.mnemom.ai/v1/reputation/agent-xyz/badge.svg",
    "verify_url": "https://api.mnemom.ai/v1/reputation/agent-xyz/verify"
  }
}
Response fields:
FieldTypeDescription
agent_idstringAgent identifier
scorenumberComposite score (0 — 1000)
gradestringLetter grade: AAA, AA, A, BBB, BB, B, CCC, or NR
tierstringHuman-readable tier label
is_eligiblebooleanWhether the agent has met the 50-checkpoint minimum
checkpoint_countnumberTotal analyzed checkpoints
confidencestringinsufficient, low, medium, or high
componentsarrayFive component scores with keys, weights, and factors
computed_atstringISO 8601 timestamp of last computation
trend_30dnumberSigned delta vs. 30 days ago
visibilitystringpublic, unlisted, or private
a2a_trust_extensionobjectPre-built trust block for A2A Agent Cards
a2a_trust_extension object:
FieldTypeDescription
providerstringTrust provider identifier (always "mnemom")
scorenumberCurrent reputation score
gradestringCurrent letter grade
verified_urlstringAPI endpoint returning the full reputation response
badge_urlstringDynamic SVG badge URL
verify_urlstringCryptographic verification endpoint
Component object:
FieldTypeDescription
keystringComponent identifier
labelstringHuman-readable name
scorenumberComponent score (0 — 1000)
weightnumberWeight in composite formula (0 — 1)
weighted_scorenumberscore * weight contribution to composite
factorsstring[]Human-readable factors affecting this component
Error responses:
StatusMeaning
404Agent not found

​
GET /v1/reputation//history

Retrieve weekly reputation snapshots for trend analysis. Parameters:
ParameterInTypeRequiredDescription
agent_idpathstringYesAgent identifier
Response: 200 OK 
{
  "snapshots": [
    {
      "week_start": "2026-02-17",
      "score": 782,
      "grade": "A",
      "checkpoint_count": 347,
      "components": {
        "integrity_ratio": 920,
        "compliance": 850,
        "drift_stability": 700,
        "trace_completeness": 650,
        "coherence_compatibility": 390
      }
    },
    {
      "week_start": "2026-02-10",
      "score": 770,
      "grade": "A",
      "checkpoint_count": 312,
      "components": {
        "integrity_ratio": 910,
        "compliance": 800,
        "drift_stability": 700,
        "trace_completeness": 620,
        "coherence_compatibility": 390
      }
    }
  ]
}
Snapshot object:
FieldTypeDescription
week_startstringISO date for the start of the snapshot week (Sunday)
scorenumberComposite score at time of snapshot
gradestringLetter grade at time of snapshot
checkpoint_countnumberCumulative checkpoint count at snapshot time
componentsobjectComponent scores keyed by component identifier

​
GET /v1/reputation//badge.svg

Dynamic SVG badge showing the agent’s current reputation score. Parameters:
ParameterInTypeRequiredDescription
agent_idpathstringYesAgent identifier
variantquerystringNoBadge variant: score (default), score_tier, score_trend, compact
Response: 200 OK with Content-Type: image/svg+xml 
Cache-Control: public, max-age=3600
Badge variants:
VariantDisplay
score[ Mnemom Trust | 782 ]
score_tier[ Mnemom Trust | 782 Established ]
score_trend[ Mnemom Trust | 782 ↑ ]
compact[ 782 ]
For agents below the 50-checkpoint minimum: 
[ Mnemom | Building... 23/50 ]
See Embeddable Badges for embed code in Markdown, HTML, React, and A2A formats.

​
GET /v1/reputation//verify

Cryptographic verification of a reputation score. Returns the proof chain that independently confirms the score was computed from authentic, tamper-evident integrity checkpoints. Parameters:
ParameterInTypeRequiredDescription
agent_idpathstringYesAgent identifier
Response: 200 OK 
{
  "agent_id": "agent-xyz",
  "score": 782,
  "grade": "A",
  "verified": true,
  "verification": {
    "certificate_hash": "sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "merkle_root": "sha256:f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5",
    "hash_chain_valid": true,
    "checkpoint_count": 347,
    "latest_checkpoint_id": "ic-abc12345",
    "latest_checkpoint_at": "2026-02-21T13:45:00.000Z",
    "proof_generated_at": "2026-02-21T14:00:00.000Z"
  },
  "computed_at": "2026-02-21T14:00:00.000Z"
}
Response fields:
FieldTypeDescription
agent_idstringAgent identifier
scorenumberComposite score at time of verification
gradestringLetter grade at time of verification
verifiedbooleanWhether the proof chain validates successfully
verificationobjectCryptographic proof chain details
computed_atstringISO 8601 timestamp of score computation
verification object:
FieldTypeDescription
certificate_hashstringSHA-256 hash of the latest integrity certificate covering this agent’s checkpoints
merkle_rootstringMerkle tree root hash over all analyzed checkpoints
hash_chain_validbooleanWhether the hash chain linking consecutive checkpoints is intact and tamper-free
checkpoint_countnumberNumber of checkpoints included in the proof
latest_checkpoint_idstringID of the most recent checkpoint in the chain
latest_checkpoint_atstringTimestamp of the most recent checkpoint
proof_generated_atstringWhen this proof was generated
Error responses:
StatusMeaning
404Agent not found
422Agent has insufficient checkpoints for verification (below 50-checkpoint minimum)
Use the verification endpoint to independently confirm that a reputation score is backed by real integrity data. The certificate_hash can be cross-referenced with the certificate endpoint and the merkle_root can be verified via the Merkle root endpoint.

​
POST /v1/reputation/batch

Retrieve reputation scores for multiple agents in a single request. Requires API key authentication. Request body: 
{
  "agent_ids": ["agent-xyz", "agent-abc", "agent-def"]
}
FieldTypeRequiredDescription
agent_idsstring[]YesList of agent identifiers (max 50)
Response: 200 OK 
{
  "scores": [
    {
      "agent_id": "agent-xyz",
      "score": 782,
      "grade": "A",
      "tier": "Reliable",
      "confidence": "medium",
      "trend_30d": 12
    },
    {
      "agent_id": "agent-abc",
      "score": 650,
      "grade": "BBB",
      "tier": "Developing",
      "confidence": "low",
      "trend_30d": -8
    },
    {
      "agent_id": "agent-def",
      "score": null,
      "grade": "NR",
      "tier": "Not Rated",
      "confidence": "insufficient",
      "trend_30d": 0
    }
  ]
}
Error responses:
StatusMeaning
400agent_ids missing or exceeds 50
401API key required

​
GET /v1/reputation/search

Search the reputation directory for agents by name, grade, or confidence level. Requires API key authentication. Query parameters:
ParameterTypeRequiredDescription
qstringNoSearch query (matches agent name/ID)
gradestringNoFilter by grade (AAA, AA, A, BBB, BB, B, CCC)
confidencestringNoFilter by confidence level (low, medium, high)
sortstringNoSort field: score (default), name, trend, checkpoints
pagenumberNoPage number (default: 1)
per_pagenumberNoResults per page (default: 20, max: 100)
Response: 200 OK 
{
  "agents": [
    {
      "agent_id": "agent-xyz",
      "agent_name": "Shopping Assistant",
      "score": 782,
      "grade": "A",
      "tier": "Reliable",
      "confidence": "medium",
      "checkpoint_count": 347,
      "trend_30d": 12,
      "visibility": "public",
      "claimed": true
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}
Directory agent object:
FieldTypeDescription
agent_idstringAgent identifier
agent_namestringDisplay name
scorenumberComposite score
gradestringLetter grade
tierstringTier label
confidencestringConfidence level
checkpoint_countnumberAnalyzed checkpoint count
trend_30dnumber30-day trend delta
visibilitystringpublic or unlisted
claimedbooleanWhether the agent has been claimed by an owner

​
GET /v1/reputation/compare

Side-by-side comparison of 2 to 10 agents. Requires API key authentication. Query parameters:
ParameterTypeRequiredDescription
agent_idsstringYesComma-separated agent IDs (2 — 10)
Example: 
GET /v1/reputation/compare?agent_ids=agent-xyz,agent-abc,agent-def
Response: 200 OK 
{
  "agents": [
    {
      "agent_id": "agent-xyz",
      "score": 782,
      "grade": "A",
      "components": {
        "integrity_ratio": 920,
        "compliance": 850,
        "drift_stability": 700,
        "trace_completeness": 650,
        "coherence_compatibility": 390
      }
    },
    {
      "agent_id": "agent-abc",
      "score": 650,
      "grade": "BBB",
      "components": {
        "integrity_ratio": 780,
        "compliance": 600,
        "drift_stability": 550,
        "trace_completeness": 700,
        "coherence_compatibility": 500
      }
    }
  ]
}
Error responses:
StatusMeaning
400Fewer than 2 or more than 10 agent IDs
401API key required

​
GET /v1/reputation/benchmarks

Aggregate statistics across all publicly scored agents. Useful for understanding where an agent stands relative to the ecosystem. Response: 200 OK 
{
  "total_scored": 1247,
  "mean_score": 672,
  "median_score": 695,
  "distribution": [
    { "grade": "AAA", "count": 23, "percentage": 1.8 },
    { "grade": "AA", "count": 89, "percentage": 7.1 },
    { "grade": "A", "count": 312, "percentage": 25.0 },
    { "grade": "BBB", "count": 408, "percentage": 32.7 },
    { "grade": "BB", "count": 215, "percentage": 17.2 },
    { "grade": "B", "count": 134, "percentage": 10.7 },
    { "grade": "CCC", "count": 66, "percentage": 5.3 }
  ],
  "percentiles": {
    "p10": 420,
    "p25": 560,
    "p50": 695,
    "p75": 780,
    "p90": 860
  }
}
Benchmark fields:
FieldTypeDescription
total_scorednumberTotal agents with published scores
mean_scorenumberArithmetic mean of all scores
median_scorenumberMedian score (p50)
distributionarrayCount and percentage per grade
percentilesobjectScore at each percentile (p10, p25, p50, p75, p90)

​
Webhook Events

Subscribe to reputation-related webhook events via Webhook Notifications:
Event TypeTriggerPayload
reputation.score_changedScore changed by more than 10 points{ agent_id, score_before, score_after, grade, components }
reputation.grade_changedLetter grade changed{ agent_id, grade_before, grade_after, score }
Fires when an agent’s reputation score changes by more than 10 points (positive or negative) during hourly recomputation.
{
  "id": "evt-rs4n8k2p",
  "type": "reputation.score_changed",
  "created_at": "2026-02-21T14:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "agent_id": "agent-xyz",
    "score_before": 770,
    "score_after": 782,
    "grade": "A",
    "components": {
      "integrity_ratio": 920,
      "compliance": 850,
      "drift_stability": 700,
      "trace_completeness": 650,
      "coherence_compatibility": 390
    }
  }
}
FieldTypeDescription
agent_idstringAgent identifier
score_beforenumberPrevious composite score
score_afternumberNew composite score
gradestringCurrent letter grade (after the change)
componentsobjectComponent scores at time of change, keyed by component identifier
Fires when an agent’s letter grade changes (e.g., from BBB to A). Always accompanied by a reputation.score_changed event.
{
  "id": "evt-rg3k7m2x",
  "type": "reputation.grade_changed",
  "created_at": "2026-02-21T14:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "agent_id": "agent-xyz",
    "grade_before": "BBB",
    "grade_after": "A",
    "score": 702
  }
}
FieldTypeDescription
agent_idstringAgent identifier
grade_beforestringPrevious letter grade
grade_afterstringNew letter grade
scorenumberCurrent composite score at time of grade change

---

## Error Codes

| Status | Code | Description |
|--------|------|-------------|
| `400` | `invalid_request` | Missing or invalid parameters |
| `401` | `unauthorized` | API key required but not provided or invalid |
| `404` | `agent_not_found` | Agent ID does not exist |
| `429` | `rate_limited` | Too many requests; check `Retry-After` header |
| `500` | `internal_error` | Server error; retry with exponential backoff |

All error responses follow the standard envelope:

```json
{
  "error": "agent_not_found",
  "message": "No agent found with ID 'agent-xyz'"
}

​
SDK Usage

​
TypeScript

import {
  fetchReputation,
  fetchReputationHistory,
  fetchReputationBenchmarks,
  searchDirectory,
} from '@mnemom/reputation';

// Single agent score
const score = await fetchReputation('agent-xyz');

// Historical trend
const history = await fetchReputationHistory('agent-xyz');

// Ecosystem benchmarks
const benchmarks = await fetchReputationBenchmarks();

// Directory search
const results = await searchDirectory({
  grade: 'A',
  confidence: 'high',
  sort: 'score',
  per_page: 50,
});

​
Python

import httpx

API_BASE = "https://api.mnemom.ai"

# Single agent score (public, no auth)
score = httpx.get(f"{API_BASE}/v1/reputation/agent-xyz").json()

# Batch lookup (requires API key)
batch = httpx.post(
    f"{API_BASE}/v1/reputation/batch",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"agent_ids": ["agent-xyz", "agent-abc"]},
).json()

# Directory search (requires API key)
results = httpx.get(
    f"{API_BASE}/v1/reputation/search",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"grade": "A", "confidence": "high", "sort": "score"},
).json()

# Benchmarks (public)
benchmarks = httpx.get(f"{API_BASE}/v1/reputation/benchmarks").json()
print(f"Ecosystem median: {benchmarks['median_score']}")
print(f"Total scored agents: {benchmarks['total_scored']}")

​
See Also