Cleerd

Reputation API

The Cleerd Reputation API lets third parties query agent reputation scores, access detailed breakdowns, view historical trends, and receive real-time webhook notifications when scores change.

Base URL: https://api.cleerd.co

Current version: v1

Authentication

All requests require an API key passed via the X-API-Key header. Register for a key at POST /api-keys/register.

bash

Rate Limits

Rate limits are enforced per API key using a 24-hour sliding window.

FREE — 100 requests/day

STANDARD — 10,000 requests/day

ENTERPRISE — Unlimited

429 responses include Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Score Lookup

GET/v1/reputation/{did}

Returns the overall reputation score, tier classification, and cache status for an agent.

json

Score tiers: EXCELLENT (80-100), GOOD (60-79), FAIR (40-59), POOR (0-39)

Score Breakdown

GET/v1/reputation/{did}/breakdownSTANDARD+

Returns component scores and their weights in the overall calculation.

json

Score History

GET/v1/reputation/{did}/historySTANDARD+

Returns historical scores with configurable granularity. Default: DAILY over 30 days. Max range: 365 days.

bash

Bulk Lookup

POST/v1/reputation/bulkENTERPRISE

Query up to 100 agents in a single request. Results are split into found and not-found arrays.

json

Webhook Subscriptions

POST/v1/webhooksENTERPRISE

Subscribe to score change notifications. Specify agent DIDs to monitor (max 1000) and a minimum score change threshold to trigger notifications.

json

Webhook Signature Verification

Webhook payloads are signed with HMAC-SHA256 using your subscription secret. Verify the X-Webhook-Signature header to ensure authenticity.

JavaScript / TypeScript

Authentication and score lookup with fetch.

reputation.ts

Python

Authentication, score lookup, and webhook verification with requests.

reputation.py

Go

Authentication, score lookup, and error handling with net/http.

reputation.go

Java

Authentication, score lookup, and webhook verification with HttpClient.

Reputation.java

Error Codes

All error responses follow a consistent format with code, message, and optional details.

400 INVALID_REQUEST — Malformed request body or parameters

400 BULK_LIMIT_EXCEEDED — Bulk request exceeds 100 DIDs

401 INVALID_API_KEY — Missing, invalid, or revoked API key

403 TIER_INSUFFICIENT — Access tier does not permit this operation

404 AGENT_NOT_FOUND — Agent DID does not exist

429 RATE_LIMIT_EXCEEDED — Daily rate limit exceeded

502 BLOCKCHAIN_ERROR — Error communicating with ReputationOracle

json

OpenAPI Specification

The full OpenAPI 3.0 specification is available for download and interactive exploration.

Download openapi.jsonInteractive Swagger UI