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.
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.
For a complete overview of the Ethos Network, including its mechanisms and governance model, please refer to the Ethos Whitepaper.
All API requests should be made to the following base URL:
https://api.ethos.network
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.
- 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.
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 my-app@1.0.0).
X-Ethos-Client: my-cool-app@1.2.3{% hint style="warning" %} Required: Requests without this header may be subject to rate limiting. {% endhint %}
Including this header helps us:
- Attribute traffic to your app
- Diagnose issues faster
- Ensure fair and efficient resource allocation
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.
- 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
Some APIs accept a userkey as a user identifier. Below are the supported formats:
| Format | Description |
|---|---|
profileId:<id> | Ethos profile ID Example: |
address:<address> | Ethereum address Example: |
service:discord:<id> | Discord user ID Example: |
service:farcaster:<id> | Farcaster user ID Example: |
service:telegram:<id> | Telegram user ID Example: |
service:x.com:<id> | Twitter (x.com) user ID Example: |
service:x.com:username:<username> | Twitter (x.com) username Example: |