Introduction
Welcome to the official API documentation for Ethos Network. This documentation provides detailed information about the Ethos API endpoints, request/response formats, and data models.
These docs are available at https://developers.ethos.network/ and https://github.com/trust-ethos/api-docs.
Getting Started
Ethos offers a comprehensive RESTful API that allows developers to interact with the Ethos Network. The API is organized around standard HTTP methods and uses standard HTTP response codes.
Whitepaper
For a complete overview of the Ethos Network, including its mechanisms and governance model, please refer to the Ethos Whitepaper.
Base URL
All API requests should be made to the following base URL:
https://api.ethos.networkAuthentication
Some API endpoints require authentication using a Privy token. These are usually endpoints meant to be used in the context of an active user session — for example, when performing actions tied to the currently logged-in user.
If authentication is required, you must include a valid token in the Authorization header:
Authorization: Bearer <your_privy_token>The token is stored in a privy-token cookie under the app.ethos.network domain. Note, this token is short-lived and expires after 1 hour.
⚠️ Important notes:
Most developers won’t need to use this token directly — many endpoints are public or free to use.
Tokens are tied to the current user session and are only needed when working within that user’s authenticated context.
Client Identification
To help us monitor and manage usage across different integrations, all API requests must include the X-Ethos-Client header.
This header should contain the name of your product or integration, and may optionally include a version number (e.g., my-app or [email protected]).
X-Ethos-Client: [email protected]Required: Requests without this header may be subject to rate limiting.
Including this header helps us:
Attribute traffic to your app
Diagnose issues faster
Ensure fair and efficient resource allocation
LLM-ready Documentation
Ethos API documentation is LLM-optimized, enabling AI-powered developer tools like ChatGPT, Claude, Cursor, GitHub Copilot, and other LLM assistants to retrieve accurate, contextual responses.
Developers can ask questions like “How do I get the score for a specific profile?” or “What’s the structure of an activity object?” — and receive precise answers powered by our official API documentation.
Resources
OpenAPI v3 spec The full schema of our public API in OpenAPI format, including available endpoints, methods, parameters, and response structures. 👉 https://api.ethos.network/docs/openapi.json
LLM discovery files These files help large language models discover and index relevant documentation automatically. They are auto-generated by GitBook and follow an emerging open standard:
https://developers.ethos.network/llms.txt — high-level metadata, e.g. docs structure and main entry points
https://developers.ethos.network/llms-full.txt — detailed references to all public documentation pages for deeper LLM indexing
Userkeys
Some APIs accept a userkey as a user identifier. Below are the supported formats:
profileId:<id>
Ethos profile ID
Example: profileId:10
address:<address>
Ethereum address
Example: address:0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
service:discord:<id>
Discord user ID
Example: service:discord:797130033613242441
service:farcaster:<id>
Farcaster user ID
Example: service:farcaster:1112412
service:telegram:<id>
Telegram user ID
Example: service:telegram:167380455
service:x.com:<id>
Twitter (x.com) user ID
Example: service:x.com:295218901
service:x.com:username:<username>
Twitter (x.com) username
Example: service:x.com:username:VitalikButerin
Last updated