Information
- OpenAPI version:
3.1.0
Overview
Ethos API v2
Section titled “Ethos API v2”Ethos is an onchain reputation network. This API exposes credibility scores, reviews, vouches, profiles, XP and reputation markets over REST.
Base URL: https://api.ethos.network/api/v2. Send an X-Ethos-Client header naming your app, for example my-app@1.0.0. Requests without it share one strict rate limit across all anonymous callers.
Most read endpoints are public. Endpoints that require authentication take either a long-lived API key in the X-Ethos-Api-Key header, available to profiles with API key access enabled, or a short-lived Privy session token in the Authorization: Bearer header. Do not send an API key as a Bearer token. Operations that require the SessionCookie scheme are for first-party browser sessions only: they take the HttpOnly cookies set by POST /auth/exchange, which itself takes the Privy Bearer token, and mutations are refused with 403 unless the request comes from an Ethos origin. See the API Keys guide on developers.ethos.network.
A user is the person record Ethos scores; a profile is the on-chain identity a user gets when they join. A user can exist without a profile. Most endpoints accept a userkey, a string that identifies a user by any linked account:
address:0x…an Ethereum addressprofileId:123an Ethos profile idservice:x.com:123456789an X account by numeric idservice:x.com:username:handlean X account by handle (score, NFT, endorsement and connection lookups; user lookups take the handle as a path parameter instead)service:discord:<id>,service:farcaster:<id>,service:telegram:<id>,service:github:<id>other linked accounts
Scores range from 0 to 2800 and map to a named level from untrusted to renowned. List endpoints are paginated one of two ways, shown by their response shape: offset pagination takes limit and offset and returns { values, total, limit, offset }; cursor pagination takes limit and cursor and returns { values, nextCursor }.
Authentication
Section titled “Authentication”ApiKey
Section titled “ApiKey”Security scheme type: apiKey
Header parameter name: X-Ethos-Api-Key
Authorization
Section titled “Authorization”Security scheme type: http
SessionCookie
Section titled “SessionCookie”Security scheme type: apiKey
Cookie parameter name: ethos-access-token