Skip to content
EthosEthosDevelopers

Search

Overview

Section titled “Overview”

The Search API allows you to search for users, addresses, and service accounts in the Ethos network. It provides a unified search experience that returns results from different sources including profiles, Twitter accounts, and ENS names.

Endpoints

Section titled “Endpoints”
Section titled “Search”
GET /api/v1/search

Description: Searches for users in the Ethos network based on a query string. The search looks across profile names, usernames, Ethereum addresses, ENS names, and Twitter handles.

Authentication Required: No

Parameters

Section titled “Parameters”

Query Parameters

Name Type Required Description
query string Yes Search query (2-100 characters)
limit number No Maximum number of results to return (default: 10)
offset number No Offset for pagination (default: 0)

Responses

Section titled “Responses”

Success Response

Code: 200 OK

{
  "ok": true,
  "data": {
    "values": [
      {
        "userkey": "profileId:123",
        "avatar": "https://example.com/avatar.jpg",
        "name": "Vitalik Buterin",
        "username": "vitalik",
        "description": "Ethereum co-founder",
        "score": 95,
        "scoreXpMultiplier": 1,
        "profileId": 123,
        "primaryAddress": "0x1234567890123456789012345678901234567890"
      },
      {
        "userkey": "service:x.com:456789",
        "avatar": "https://pbs.twimg.com/profile_images/1234567890/image.jpg",
        "name": "Vitalik.eth",
        "username": "vitalikbuterin",
        "description": "Ethereum co-founder | vitalik.eth",
        "score": 95,
        "scoreXpMultiplier": 1,
        "profileId": 124,
        "primaryAddress": "0x9876543210987654321098765432109876543210"
      }
    ],
    "limit": 10,
    "offset": 0,
    "total": 2
  }
}
Property Type Description
ok boolean Success status
data object Response data container
data.values array Array of actor objects matching the search
data.values[].userkey string Userkey that uniquely identifies this actor
data.values[].avatar string URL to the actor’s avatar
data.values[].name string Actor’s display name
data.values[].username string Actor’s username
data.values[].description string Actor’s description or bio
data.values[].score number Actor’s credibility score
data.values[].scoreXpMultiplier number Actor’s XP multiplier based on score
data.values[].profileId number Actor’s profile ID (if available)
data.values[].primaryAddress string Actor’s primary Ethereum address (if available)
data.limit number Number of results returned
data.offset number Current pagination offset
data.total number Total number of results matching the query

Example

Section titled “Example”

Request

Terminal window
http GET "https://api.ethos.network/api/v1/search?query=vitalik&limit=10&offset=0"

Notes

Section titled “Notes”
  • The search results are sorted by multiple criteria in a cascading priority:
    1. Profiles are ranked higher than non-profiles
    2. Usernames exactly matching the query are prioritized
    3. Real names exactly matching the query are prioritized
    4. Results with usernames are ranked higher than those without
    5. Results with real names are ranked higher than those without
    6. Results with addresses are ranked higher than those without
    7. Finally, results are sorted by credibility score
  • The search is case-insensitive and will match partial strings.
  • If no results are found but the query is a valid Ethereum address or ENS name, the API will attempt to look it up and return information about that address.
  • Duplicate results (same user found through different search methods) are deduplicated.