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

Endpoint	Auth Required	Notes	Reference
`GET /v1/reputation/{agent_id}`	No	Public score retrieval	↗
`GET /v1/reputation/{agent_id}/history`	No	Public weekly snapshots	↗
`GET /v1/reputation/{agent_id}/events`	No	Public recent events	↗
`GET /v1/reputation/{agent_id}/verify`	No	Cryptographic verification	↗
`GET /v1/reputation/{agent_id}/badge.svg`	No	Public badge	↗
`GET /v1/reputation/{agent_id}/og-image`	No	Public share-card image	↗
`GET /v1/reputation/benchmarks`	No	Aggregate statistics	↗
`GET /v1/reputation/search`	No	Directory search (public agents only)	↗
`GET /v1/reputation/compare`	No	Side-by-side comparison (2—10 agents)	↗
`POST /v1/reputation/batch`	Bearer or API key	Bulk score retrieval (up to 50 ids)	↗
`POST /v1/reputation/{agent_id}/recompute`	Bearer or API key	Owner/admin-triggered recompute, 30s rate-limited; tagged under Reclassification	↗

search and compare are genuinely public (no security requirement) — do not gate calls to them behind an API key. Only batch and the owner recompute require auth.

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

Reputation endpoints are rate-limited to prevent systematic enumeration. Limits are applied per-IP for unauthenticated requests and per-API-key (JWT sub) for authenticated requests.

Category	Endpoints	Unauthenticated (per-IP)	Authenticated (per-API-key)
Lookup	`/reputation/{id}`, `/reputation/{id}/history`, `/reputation/{id}/events`, `/reputation/{id}/verify`, `/reputation/search` (yes, search is rate-limited as a lookup, not as batch), team variants	10/min	60/min
Compare	`/reputation/compare`, `/teams/reputation/compare`	10/min	60/min
Benchmarks	`/reputation/benchmarks`	30/min	60/min
Badge / OG-image	`/reputation/{id}/badge.svg`, `/reputation/{id}/og-image`, team variants	300/min	300/min
Batch	`/reputation/batch`, team variants	blocked (auth required)	30/min

Badge and OG-image endpoints have generous limits because they are typically embedded in websites and served through CDN caching. Authenticate requests (via Authorization: Bearer <token>) to access higher limits on any category.

429 response format

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

Header	Description
`Retry-After`	Seconds to wait before retrying
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests remaining (always `0` on a 429)
`X-RateLimit-Reset`	Unix timestamp when the window resets

Rate limit windows are 1 minute. Enterprise customers requiring higher limits should contact support.

Endpoints

`GET /v1/reputation/{agent_id}`

Retrieve the full reputation score for an agent, including all five component scores, trend data, and confidence level. Parameters:

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	Agent identifier

Response: 200 OK

{
  "agent_id": "agent-xyz",
  "score": 818,
  "grade": "AA",
  "tier": "Established",
  "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": 750,
      "weight": 0.10,
      "weighted_score": 75,
      "factors": ["Default score — fleet coherence data not yet integrated"]
    }
  ],
  "computed_at": "2026-02-21T14:00:00.000Z",
  "trend_30d": 12,
  "visibility": "public",
  "a2a_trust_extension": {
    "extension_uri": "https://mnemom.ai/ext/agent-trust/v1",
    "provider": "mnemom",
    "score": 818,
    "grade": "AA",
    "confidence": "medium",
    "verified_url": "https://api.mnemom.ai/v1/reputation/agent-xyz/verify",
    "badge_url": "https://api.mnemom.ai/v1/reputation/agent-xyz/badge.svg",
    "methodology_url": "https://www.mnemom.ai/methodology",
    "last_updated": "2026-02-21T14:00:00.000Z"
  }
}

Response fields:

Field	Type	Description
`agent_id`	string	Agent identifier
`score`	number	Composite score (0 — 1000)
`grade`	string	Letter grade: `AAA`, `AA`, `A`, `BBB`, `BB`, `B`, `CCC`, or `NR`
`tier`	string	Human-readable tier label
`is_eligible`	boolean	Whether the agent has met the 50-checkpoint minimum
`checkpoint_count`	number	Total checkpoints recorded for the agent (see `checkpoint_accounting.analyzed` for the subset that counted toward the score)
`confidence`	string	`insufficient`, `low`, `medium`, or `high`
`components`	array	Five component scores with keys, weights, and factors
`computed_at`	string	ISO 8601 timestamp of last computation
`trend_30d`	number	Signed delta vs. 30 days ago
`visibility`	string	`public`, `unlisted`, or `private`
`a2a_trust_extension`	object	Pre-built trust block for A2A Agent Cards

a2a_trust_extension object:

Field	Type	Description
`extension_uri`	string	Extension identifier (always `"https://mnemom.ai/ext/agent-trust/v1"`)
`provider`	string	Trust provider identifier (always `"mnemom"`)
`score`	number	Current reputation score
`grade`	string	Current letter grade
`confidence`	string	Current confidence level
`verified_url`	string	The `GET /v1/reputation/{agent_id}/verify` endpoint below — score plus its cryptographic proof chain
`badge_url`	string	Dynamic SVG badge URL
`methodology_url`	string	Link to the published scoring methodology
`last_updated`	string	`computed_at` of the underlying score

Component object:

Field	Type	Description
`key`	string	Component identifier
`label`	string	Human-readable name
`score`	number	Component score (0 — 1000)
`weight`	number	Weight in composite formula (0 — 1)
`weighted_score`	number	`score * weight` contribution to composite
`factors`	string[]	Human-readable factors affecting this component

Error responses:

Status	Meaning
`404`	Agent not found

`GET /v1/reputation/{agent_id}/history`

Retrieve weekly reputation snapshots for trend analysis. Parameters:

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	Agent identifier

Response: 200 OK

{
  "snapshots": [
    {
      "week_start": "2026-02-17",
      "score": 818,
      "grade": "AA",
      "checkpoint_count": 347,
      "components": {
        "integrity_ratio": 920,
        "compliance": 850,
        "drift_stability": 700,
        "trace_completeness": 650,
        "coherence_compatibility": 750
      }
    },
    {
      "week_start": "2026-02-10",
      "score": 801,
      "grade": "AA",
      "checkpoint_count": 312,
      "components": {
        "integrity_ratio": 910,
        "compliance": 800,
        "drift_stability": 700,
        "trace_completeness": 620,
        "coherence_compatibility": 750
      }
    }
  ]
}

Snapshot object:

Field	Type	Description
`week_start`	string	ISO date for the start of the snapshot week (Sunday)
`score`	number	Composite score at time of snapshot
`grade`	string	Letter grade at time of snapshot
`checkpoint_count`	number	Cumulative checkpoint count at snapshot time
`components`	object	Component scores keyed by component identifier

`GET /v1/reputation/{agent_id}/badge.svg`

Dynamic SVG badge showing the agent’s current reputation score. Parameters:

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	Agent identifier
`variant`	query	string	No	Badge variant: `grade` (default), `score`, `score_grade`, `score_trend`, `score_tier`, `compact`
`style`	query	string	No	`light` (default) or `dark` — affects only the label background

Response: 200 OK with Content-Type: image/svg+xml

Cache-Control: public, max-age=3600, s-maxage=3600

Badge variants (label is “Trust Score” for every variant except score_tier, which uses “Mnemom Trust”):

Variant	Display
`grade` (default)	`[ Trust Score \| BBB ]`
`score`	`[ Trust Score \| 782 ]`
`score_grade`	`[ Trust Score \| BBB 782 ]`
`score_trend`	`[ Trust Score \| BBB 782 ↑ ]`
`score_tier`	`[ Mnemom Trust \| 782 Developing ]`
`compact`	`[ BBB ]` (grade only, not the numeric score)

Regardless of variant, an agent below the 50-checkpoint minimum instead renders:

[ Trust Score | Building 23/50 ]

and a private-visibility agent renders [ Trust Score | Private ]. See Embeddable Badges for the full variant reference and embed code in Markdown, HTML, React, and A2A formats.

`GET /v1/reputation/{agent_id}/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:

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	Agent identifier

Response: 200 OK, Cache-Control: public, max-age=3600, s-maxage=3600

{
  "agent_id": "agent-xyz",
  "score": 818,
  "grade": "AA",
  "computed_at": "2026-02-21T14:00:00.000Z",
  "verification": {
    "latest_certificate_hash": "sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "merkle_root": "sha256:f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5",
    "checkpoint_count": 347,
    "first_checkpoint": "2025-11-02T09:12:00.000Z",
    "last_checkpoint": "2026-02-21T13:45:00.000Z",
    "hash_chain_valid": true,
    "certificate_url": "/v1/checkpoints/ic-abc12345/certificate"
  }
}

Response fields:

Field	Type	Description
`agent_id`	string	Agent identifier
`score`	number	Composite score at time of verification
`grade`	string	Letter grade at time of verification
`computed_at`	string	ISO 8601 timestamp of score computation
`verification`	object \| null	Cryptographic proof chain details; `null` when the agent has no integrity checkpoints yet

There is no top-level verified boolean — treat a non-null verification block with hash_chain_valid: true as the confirming signal. verification object:

Field	Type	Description
`latest_certificate_hash`	string \| null	Hash of the latest checkpoint’s `chain_hash`, prefixed `sha256:`
`merkle_root`	string \| null	The agent’s Merkle tree root over its checkpoints
`checkpoint_count`	number	Number of checkpoints backing the score
`first_checkpoint`	string \| null	Timestamp of the agent’s earliest checkpoint
`last_checkpoint`	string \| null	Timestamp of the agent’s most recent checkpoint
`hash_chain_valid`	boolean	Whether the latest checkpoint carries both a `chain_hash` and an `issuer_signature`
`certificate_url`	string \| null	Relative path to the certificate for the latest checkpoint, when one exists

Error responses:

Status	Meaning
`400`	Malformed `agent_id`
`403`	Reputation is private
`404`	Agent not found

Use the verification endpoint to independently confirm that a reputation score is backed by real integrity data. You can cross-reference the latest_certificate_hash with the certificate endpoint. Members of the agent’s org can also check the merkle_root against the Merkle root endpoint (authenticated).

`GET /v1/reputation/{agent_id}/events`

Recent reputation events for the agent (e.g. score_changed, grade_changed), newest first, capped at 50. Public, subject to the private-visibility gate.

{ "events": [{ "agent_id": "agent-xyz", "event_type": "score_changed", "description": "Score changed from 770 to 782", "score_before": 770, "score_after": 782 }] }

`GET /v1/reputation/{agent_id}/og-image`

Returns a 1200x630 PNG (or an HTML fallback) suitable for og:image link previews when an agent’s public reputation page is shared. Public, no request body or query parameters beyond agent_id.

`POST /v1/reputation/{agent_id}/recompute`

Lets an authenticated agent owner or admin trigger an on-demand recompute instead of waiting for the 6-hour cron (30-second rate limit per agent). This endpoint is tagged under Reclassification in the OpenAPI spec, not Reputation, since the same path also re-evaluates pending reclassifications and card amendments; see that page for the full request/response shape.

`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"]
}

Field	Type	Required	Description
`agent_ids`	string[]	Yes	List 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:

Status	Meaning
`400`	`agent_ids` missing or exceeds 50
`401`	API key required

`GET /v1/reputation/search`

Search the public reputation directory (agents with visibility: public and is_eligible: true only). Public — no authentication required. Query parameters:

Parameter	Type	Required	Description
`q`	string	No	Name substring match, or an exact `smolt-` id-prefix match
`grade`	string	No	Filter by grade (`AAA`, `AA`, `A`, `BBB`, `BB`, `B`, `CCC`, `NR`)
`confidence`	string	No	Filter by confidence level (`insufficient`, `low`, `medium`, `high`)
`sort`	string	No	Sort field: `score` (default), `grade`, `checkpoint_count`, or `computed_at`
`page`	number	No	Page number (default: 1)
`per_page`	number	No	Results 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:

Field	Type	Description
`agent_id`	string	Agent identifier
`agent_name`	string	Display name
`score`	number	Composite score
`grade`	string	Letter grade
`tier`	string	Tier label
`confidence`	string	Confidence level
`checkpoint_count`	number	Analyzed checkpoint count
`trend_30d`	number	30-day trend delta
`visibility`	string	`public` or `unlisted`
`claimed`	boolean	Whether the agent has been claimed by an owner

`GET /v1/reputation/compare`

Side-by-side comparison of 2 to 10 agents. Public — no authentication required. Query parameters:

Parameter	Type	Required	Description
`ids`	string	Yes	Comma-separated agent IDs (2 — 10)

Example:

GET /v1/reputation/compare?ids=agent-xyz,agent-abc,agent-def

Response: 200 OK — each entry has the same shape as the single-agent GET /v1/reputation/{agent_id} response above (the full components array, not a flattened map). Private-visibility agents are silently omitted rather than erroring.

{
  "agents": [
    {
      "agent_id": "agent-xyz",
      "score": 818,
      "grade": "AA",
      "components": [
        { "key": "integrity_ratio", "score": 920, "weight": 0.40, "weighted_score": 368 },
        { "key": "compliance", "score": 850, "weight": 0.20, "weighted_score": 170 },
        { "key": "drift_stability", "score": 700, "weight": 0.20, "weighted_score": 140 },
        { "key": "trace_completeness", "score": 650, "weight": 0.10, "weighted_score": 65 },
        { "key": "coherence_compatibility", "score": 750, "weight": 0.10, "weighted_score": 75 }
      ]
    },
    {
      "agent_id": "agent-abc",
      "score": 650,
      "grade": "BBB",
      "components": [
        { "key": "integrity_ratio", "score": 780, "weight": 0.40, "weighted_score": 312 },
        { "key": "compliance", "score": 600, "weight": 0.20, "weighted_score": 120 },
        { "key": "drift_stability", "score": 550, "weight": 0.20, "weighted_score": 110 },
        { "key": "trace_completeness", "score": 700, "weight": 0.10, "weighted_score": 70 },
        { "key": "coherence_compatibility", "score": 750, "weight": 0.10, "weighted_score": 75 }
      ]
    }
  ]
}

Error responses:

Status	Meaning
`400`	Fewer than 2 or more than 10 agent IDs

`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, cached 5 minutes.

{
  "total_scored": 1247,
  "total_eligible": 1247,
  "mean_score": 672,
  "median_score": 695,
  "p25_score": 560,
  "p75_score": 780,
  "p90_score": 860,
  "grade_distribution": {
    "AAA": 23,
    "AA": 89,
    "A": 312,
    "BBB": 408,
    "BB": 215,
    "B": 134,
    "CCC": 66
  }
}

Benchmark fields:

Field	Type	Description
`total_scored`	number	Total eligible agents included in the aggregate
`total_eligible`	number	Alias of `total_scored`, kept for older callers
`mean_score`	number	Arithmetic mean of all eligible scores
`median_score`	number	Median score
`p25_score` / `p75_score` / `p90_score`	number	Score at each percentile
`grade_distribution`	object	Count of agents at each grade, keyed by grade letter

Webhook events

Subscribe to reputation-related webhook events via Webhook Notifications:

Event Type	Trigger	Payload
`reputation.score_changed`	Any recomputation that changes the composite score	`{ agent_id, previous_score, new_score, delta, previous_grade, new_grade, reason }`
`reputation.grade_changed`	A recomputation that changes the letter grade	`{ agent_id, previous_grade, new_grade, reason }`

reputation.score_changed

Fires once per recomputation where the composite score actually changed (a no-op recompute never fires it).

{
  "id": "evt-rs4n8k2p",
  "type": "reputation.score_changed",
  "created_at": "2026-02-21T14:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "agent_id": "agent-xyz",
    "previous_score": 770,
    "new_score": 782,
    "delta": 12,
    "previous_grade": "A",
    "new_grade": "A",
    "reason": "cron_tick"
  }
}

Field	Type	Description
`agent_id`	string	Agent identifier
`previous_score`	number	Composite score before the change
`new_score`	number	Composite score after the change
`delta`	number	`new_score - previous_score`
`previous_grade` / `new_grade`	string \| null	Grade before/after (informational — the canonical grade-transition signal is `reputation.grade_changed`)
`reason`	string \| null	What triggered the recompute, when known (e.g. `cron_tick`, `trust_propagation`, `owner_request`)

reputation.grade_changed

Fires when a recomputation changes the agent’s letter grade (e.g., from BBB to A). This is a separate event from reputation.score_changed, not a modifier on it, though in practice a grade change is always accompanied by a score change.

{
  "id": "evt-rg3k7m2x",
  "type": "reputation.grade_changed",
  "created_at": "2026-02-21T14:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "agent_id": "agent-xyz",
    "previous_grade": "BBB",
    "new_grade": "A",
    "reason": "cron_tick"
  }
}

Field	Type	Description
`agent_id`	string	Agent identifier
`previous_grade`	string	Previous letter grade
`new_grade`	string	New letter grade
`reason`	string \| null	What triggered the recompute, when known

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:

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

SDK usage

The @mnemom/reputation client only wraps the single-agent score lookup and a gate helper today (getReputation, getMyReputation, getA2AReputationExtension, createReputationGate). History, benchmarks, search, compare, and batch have no dedicated SDK helper — call the REST endpoints directly.

TypeScript

import { getReputation, createReputationGate } from '@mnemom/reputation';

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

// Historical trend -- no SDK helper, call the endpoint directly
const history = await fetch('https://api.mnemom.ai/v1/reputation/agent-xyz/history')
  .then(r => r.json());

// Directory search -- also public, no SDK helper
const params = new URLSearchParams({ grade: 'A', confidence: 'high', sort: 'score', per_page: '50' });
const results = await fetch(`https://api.mnemom.ai/v1/reputation/search?${params}`)
  .then(r => r.json());

// Gate a decision on a minimum score or grade
const gate = createReputationGate({ minScore: 700, minGrade: 'A' });
const result = await gate.check('agent-xyz');

Python

There is no official Python SDK for reputation; call the REST API directly.

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 Bearer token or 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 (public, no auth)
results = httpx.get(
    f"{API_BASE}/v1/reputation/search",
    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']}")

​Authentication

​Rate limits

​429 response format

​Endpoints

​GET /v1/reputation/{agent_id}

​GET /v1/reputation/{agent_id}/history

​GET /v1/reputation/{agent_id}/badge.svg

​GET /v1/reputation/{agent_id}/verify

​GET /v1/reputation/{agent_id}/events

​GET /v1/reputation/{agent_id}/og-image

​POST /v1/reputation/{agent_id}/recompute

​POST /v1/reputation/batch

​GET /v1/reputation/search

​GET /v1/reputation/compare

​GET /v1/reputation/benchmarks

​Webhook events

​Error codes

​SDK usage

​TypeScript

​Python

​See also

Authentication

Rate limits

429 response format

Endpoints

`GET /v1/reputation/{agent_id}`

`GET /v1/reputation/{agent_id}/history`

`GET /v1/reputation/{agent_id}/badge.svg`

`GET /v1/reputation/{agent_id}/verify`

`GET /v1/reputation/{agent_id}/events`

`GET /v1/reputation/{agent_id}/og-image`

`POST /v1/reputation/{agent_id}/recompute`

`POST /v1/reputation/batch`

`GET /v1/reputation/search`

`GET /v1/reputation/compare`

`GET /v1/reputation/benchmarks`

Webhook events

Error codes

SDK usage

TypeScript

Python

See also