> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mnemom Trust Rating API

> Complete API reference for the Mnemom Trust Rating™ — score retrieval, history, badges, batch lookup, directory search, comparison, and benchmarks.

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](/concepts/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 | [↗](/api-reference/endpoint/get-reputation-agent-id) |
| `GET /v1/reputation/{agent_id}/history` | No | Public weekly snapshots | [↗](/api-reference/endpoint/get-reputation-agent-id-history) |
| `GET /v1/reputation/{agent_id}/events` | No | Public recent events | [↗](/api-reference/endpoint/get-reputation-agent-id-events) |
| `GET /v1/reputation/{agent_id}/verify` | No | Cryptographic verification | [↗](/api-reference/endpoint/get-reputation-agent-id-verify) |
| `GET /v1/reputation/{agent_id}/badge.svg` | No | Public badge | [↗](/api-reference/endpoint/get-reputation-agent-id-badge.svg) |
| `GET /v1/reputation/{agent_id}/og-image` | No | Public share-card image | [↗](/api-reference/endpoint/get-reputation-agent-id-og-image) |
| `GET /v1/reputation/benchmarks` | No | Aggregate statistics | [↗](/api-reference/endpoint/get-reputation-benchmarks) |
| `GET /v1/reputation/search` | No | Directory search (public agents only) | [↗](/api-reference/endpoint/get-reputation-search) |
| `GET /v1/reputation/compare` | No | Side-by-side comparison (2--10 agents) | [↗](/api-reference/endpoint/get-reputation-compare) |
| `POST /v1/reputation/batch` | Bearer or API key | Bulk score retrieval (up to 50 ids) | [↗](/api-reference/endpoint/post-reputation-batch) |
| `POST /v1/reputation/{agent_id}/recompute` | Bearer or API key | Owner/admin-triggered recompute, 30s rate-limited; tagged under [Reclassification](/api-reference/reclassification-overview) | [↗](/api-reference/endpoint/post-reputation-agent-id-recompute) |

<Note>
  `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.
</Note>

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

```json theme={null}
{
  "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`

```json theme={null}
{
  "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](/protocols/aap/a2a-integration#reputation-in-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`

```json theme={null}
{
  "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](/guides/reputation-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`

```json theme={null}
{
  "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 |

<Tip>
  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](/api-reference/endpoint/get-checkpoints-id-certificate). Members of the agent's org can also check the `merkle_root` against the [Merkle root endpoint](/api-reference/endpoint/get-agents-id-merkle-root) (authenticated).
</Tip>

***

### `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](#authentication).

```json theme={null}
{ "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](/api-reference/reclassification-overview) 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:**

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/guides/webhooks):

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

<AccordionGroup>
  <Accordion title="reputation.score_changed">
    Fires once per recomputation where the composite score actually changed (a no-op recompute never fires it).

    ```json theme={null}
    {
      "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`) |
  </Accordion>

  <Accordion title="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.

    ```json theme={null}
    {
      "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 |
  </Accordion>
</AccordionGroup>

***

## 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 theme={null}
{
  "error": {
    "code": "agent_not_found",
    "message": "No agent found with ID 'agent-xyz'"
  }
}
```

***

## SDK usage

The [`@mnemom/reputation`](https://www.npmjs.com/package/@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

```typescript theme={null}
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.

```python theme={null}
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']}")
```

***

## See also

* [Understanding Reputation Scores](/concepts/reputation-scores) -- What scores mean
* [Scoring Methodology](/concepts/reputation-scores) -- How scores are computed
* [Improving Your Agent's Reputation](/guides/improving-reputation) -- How to improve scores
* [Embeddable Badges](/guides/reputation-badges) -- Badge variants and embed code
* [Webhook Notifications](/guides/webhooks) -- Real-time event delivery


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.