Users

Get multiple users by user IDs

post

Body

userIdsinteger[] · min: 1 · max: 500Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

500

Internal server error

application/json

post/users/by/ids

POST /api/v2/users/by/ids HTTP/1.1
Host: api.ethos.network
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "userIds": [
    1
  ]
}

[
  {
    "id": 1,
    "profileId": 1,
    "displayName": "text",
    "username": "text",
    "avatarUrl": "https://example.com",
    "description": "text",
    "score": 1,
    "status": "ACTIVE",
    "userkeys": [
      "text"
    ],
    "xpTotal": 1,
    "xpStreakDays": 1,
    "xpRemovedDueToAbuse": true,
    "influenceFactor": 1,
    "influenceFactorPercentile": 1,
    "humanVerificationStatus": "REQUESTED",
    "validatorNftCount": 1,
    "links": {
      "profile": "https://example.com",
      "scoreBreakdown": "https://example.com"
    },
    "stats": {
      "review": {
        "received": {
          "negative": 1,
          "neutral": 1,
          "positive": 1
        }
      },
      "vouch": {
        "given": {
          "amountWeiTotal": 1,
          "count": 1
        },
        "received": {
          "amountWeiTotal": 1,
          "count": 1
        }
      },
      "vouchTotals": [
        {
          "balance": {
            "given": 1,
            "received": 1
          },
          "count": {
            "given": 1,
            "received": 1
          },
          "token": {
            "address": "text",
            "decimals": 1,
            "id": "text"
          }
        }
      ]
    }
  }
]

Get multiple users by Ethereum addresses

post

Body

addressesstring[] · min: 1 · max: 500Required

Ethereum address (0x-prefixed, 20 bytes)

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

500

Internal server error

application/json

post/users/by/address

POST /api/v2/users/by/address HTTP/1.1
Host: api.ethos.network
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "addresses": [
    "text"
  ]
}

[
  {
    "id": 1,
    "profileId": 1,
    "displayName": "text",
    "username": "text",
    "avatarUrl": "https://example.com",
    "description": "text",
    "score": 1,
    "status": "ACTIVE",
    "userkeys": [
      "text"
    ],
    "xpTotal": 1,
    "xpStreakDays": 1,
    "xpRemovedDueToAbuse": true,
    "influenceFactor": 1,
    "influenceFactorPercentile": 1,
    "humanVerificationStatus": "REQUESTED",
    "validatorNftCount": 1,
    "links": {
      "profile": "https://example.com",
      "scoreBreakdown": "https://example.com"
    },
    "stats": {
      "review": {
        "received": {
          "negative": 1,
          "neutral": 1,
          "positive": 1
        }
      },
      "vouch": {
        "given": {
          "amountWeiTotal": 1,
          "count": 1
        },
        "received": {
          "amountWeiTotal": 1,
          "count": 1
        }
      },
      "vouchTotals": [
        {
          "balance": {
            "given": 1,
            "received": 1
          },
          "count": {
            "given": 1,
            "received": 1
          },
          "token": {
            "address": "text",
            "decimals": 1,
            "id": "text"
          }
        }
      ]
    }
  }
]

Get multiple users by profile IDs

post

Body

profileIdsinteger[] · min: 1 · max: 500Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

500

Internal server error

application/json

post/users/by/profile-id

POST /api/v2/users/by/profile-id HTTP/1.1
Host: api.ethos.network
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "profileIds": [
    1
  ]
}

[
  {
    "id": 1,
    "profileId": 1,
    "displayName": "text",
    "username": "text",
    "avatarUrl": "https://example.com",
    "description": "text",
    "score": 1,
    "status": "ACTIVE",
    "userkeys": [
      "text"
    ],
    "xpTotal": 1,
    "xpStreakDays": 1,
    "xpRemovedDueToAbuse": true,
    "influenceFactor": 1,
    "influenceFactorPercentile": 1,
    "humanVerificationStatus": "REQUESTED",
    "validatorNftCount": 1,
    "links": {
      "profile": "https://example.com",
      "scoreBreakdown": "https://example.com"
    },
    "stats": {
      "review": {
        "received": {
          "negative": 1,
          "neutral": 1,
          "positive": 1
        }
      },
      "vouch": {
        "given": {
          "amountWeiTotal": 1,
          "count": 1
        },
        "received": {
          "amountWeiTotal": 1,
          "count": 1
        }
      },
      "vouchTotals": [
        {
          "balance": {
            "given": 1,
            "received": 1
          },
          "count": {
            "given": 1,
            "received": 1
          },
          "token": {
            "address": "text",
            "decimals": 1,
            "id": "text"
          }
        }
      ]
    }
  }
]

Get multiple users by Twitter/X account IDs or usernames

post

Body

accountIdsOrUsernamesstring[] · min: 1 · max: 500Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

500

Internal server error

application/json

post/users/by/x

POST /api/v2/users/by/x HTTP/1.1
Host: api.ethos.network
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "accountIdsOrUsernames": [
    "text"
  ]
}

[
  {
    "id": 1,
    "profileId": 1,
    "displayName": "text",
    "username": "text",
    "avatarUrl": "https://example.com",
    "description": "text",
    "score": 1,
    "status": "ACTIVE",
    "userkeys": [
      "text"
    ],
    "xpTotal": 1,
    "xpStreakDays": 1,
    "xpRemovedDueToAbuse": true,
    "influenceFactor": 1,
    "influenceFactorPercentile": 1,
    "humanVerificationStatus": "REQUESTED",
    "validatorNftCount": 1,
    "links": {
      "profile": "https://example.com",
      "scoreBreakdown": "https://example.com"
    },
    "stats": {
      "review": {
        "received": {
          "negative": 1,
          "neutral": 1,
          "positive": 1
        }
      },
      "vouch": {
        "given": {
          "amountWeiTotal": 1,
          "count": 1
        },
        "received": {
          "amountWeiTotal": 1,
          "count": 1
        }
      },
      "vouchTotals": [
        {
          "balance": {
            "given": 1,
            "received": 1
          },
          "count": {
            "given": 1,
            "received": 1
          },
          "token": {
            "address": "text",
            "decimals": 1,
            "id": "text"
          }
        }
      ]
    }
  }
]

Get multiple users by Discord user IDs

post

Body

discordIdsstring[] · min: 1 · max: 500Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

500

Internal server error

application/json

post/users/by/discord

POST /api/v2/users/by/discord HTTP/1.1
Host: api.ethos.network
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "discordIds": [
    "text"
  ]
}

[
  {
    "id": 1,
    "profileId": 1,
    "displayName": "text",
    "username": "text",
    "avatarUrl": "https://example.com",
    "description": "text",
    "score": 1,
    "status": "ACTIVE",
    "userkeys": [
      "text"
    ],
    "xpTotal": 1,
    "xpStreakDays": 1,
    "xpRemovedDueToAbuse": true,
    "influenceFactor": 1,
    "influenceFactorPercentile": 1,
    "humanVerificationStatus": "REQUESTED",
    "validatorNftCount": 1,
    "links": {
      "profile": "https://example.com",
      "scoreBreakdown": "https://example.com"
    },
    "stats": {
      "review": {
        "received": {
          "negative": 1,
          "neutral": 1,
          "positive": 1
        }
      },
      "vouch": {
        "given": {
          "amountWeiTotal": 1,
          "count": 1
        },
        "received": {
          "amountWeiTotal": 1,
          "count": 1
        }
      },
      "vouchTotals": [
        {
          "balance": {
            "given": 1,
            "received": 1
          },
          "count": {
            "given": 1,
            "received": 1
          },
          "token": {
            "address": "text",
            "decimals": 1,
            "id": "text"
          }
        }
      ]
    }
  }
]

Get multiple users by Farcaster user IDs

post

Body

farcasterIdsstring[] · min: 1 · max: 500Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

500

Internal server error

application/json

post/users/by/farcaster

POST /api/v2/users/by/farcaster HTTP/1.1
Host: api.ethos.network
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "farcasterIds": [
    "text"
  ]
}

[
  {
    "id": 1,
    "profileId": 1,
    "displayName": "text",
    "username": "text",
    "avatarUrl": "https://example.com",
    "description": "text",
    "score": 1,
    "status": "ACTIVE",
    "userkeys": [
      "text"
    ],
    "xpTotal": 1,
    "xpStreakDays": 1,
    "xpRemovedDueToAbuse": true,
    "influenceFactor": 1,
    "influenceFactorPercentile": 1,
    "humanVerificationStatus": "REQUESTED",
    "validatorNftCount": 1,
    "links": {
      "profile": "https://example.com",
      "scoreBreakdown": "https://example.com"
    },
    "stats": {
      "review": {
        "received": {
          "negative": 1,
          "neutral": 1,
          "positive": 1
        }
      },
      "vouch": {
        "given": {
          "amountWeiTotal": 1,
          "count": 1
        },
        "received": {
          "amountWeiTotal": 1,
          "count": 1
        }
      },
      "vouchTotals": [
        {
          "balance": {
            "given": 1,
            "received": 1
          },
          "count": {
            "given": 1,
            "received": 1
          },
          "token": {
            "address": "text",
            "decimals": 1,
            "id": "text"
          }
        }
      ]
    }
  }
]

Get multiple users by Farcaster usernames

post

Bulk lookup of users by Farcaster usernames. Results are categorized into three arrays:

• "users": Successfully matched usernames with their Ethos user data

• "notFoundUsernames": Valid usernames with no associated Ethos users

• "errorUsernames": Usernames that failed lookup due to network/API errors

Both "users" and "notFoundUsernames" results can be cached safely.

Body

farcasterUsernamesstring[] · min: 1 · max: 500Required

Responses

200

Successful response

application/json

notFoundUsernamesstring[]Required

errorUsernamesstring[]Required

400

Invalid input data

application/json

500

Internal server error

application/json

post/users/by/farcaster/usernames

POST /api/v2/users/by/farcaster/usernames HTTP/1.1
Host: api.ethos.network
Content-Type: application/json
Accept: */*
Content-Length: 31

{
  "farcasterUsernames": [
    "text"
  ]
}

{
  "users": [
    {
      "user": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          },
          "vouchTotals": [
            {
              "balance": {
                "given": 1,
                "received": 1
              },
              "count": {
                "given": 1,
                "received": 1
              },
              "token": {
                "address": "text",
                "decimals": 1,
                "id": "text"
              }
            }
          ]
        }
      },
      "username": "text"
    }
  ],
  "notFoundUsernames": [
    "text"
  ],
  "errorUsernames": [
    "text"
  ]
}

Get multiple users by Telegram user IDs

post

Body

telegramIdsstring[] · min: 1 · max: 500Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

500

Internal server error

application/json

post/users/by/telegram

POST /api/v2/users/by/telegram HTTP/1.1
Host: api.ethos.network
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "telegramIds": [
    "text"
  ]
}

[
  {
    "id": 1,
    "profileId": 1,
    "displayName": "text",
    "username": "text",
    "avatarUrl": "https://example.com",
    "description": "text",
    "score": 1,
    "status": "ACTIVE",
    "userkeys": [
      "text"
    ],
    "xpTotal": 1,
    "xpStreakDays": 1,
    "xpRemovedDueToAbuse": true,
    "influenceFactor": 1,
    "influenceFactorPercentile": 1,
    "humanVerificationStatus": "REQUESTED",
    "validatorNftCount": 1,
    "links": {
      "profile": "https://example.com",
      "scoreBreakdown": "https://example.com"
    },
    "stats": {
      "review": {
        "received": {
          "negative": 1,
          "neutral": 1,
          "positive": 1
        }
      },
      "vouch": {
        "given": {
          "amountWeiTotal": 1,
          "count": 1
        },
        "received": {
          "amountWeiTotal": 1,
          "count": 1
        }
      },
      "vouchTotals": [
        {
          "balance": {
            "given": 1,
            "received": 1
          },
          "count": {
            "given": 1,
            "received": 1
          },
          "token": {
            "address": "text",
            "decimals": 1,
            "id": "text"
          }
        }
      ]
    }
  }
]

Search users by query string

get

Query parameters

querystring · min: 2 · max: 100Required

userKeyTypestring · enumOptionalPossible values:

limitinteger · max: 50OptionalDefault: 50

offsetinteger · max: 2147483647OptionalDefault: 0

Responses

200

Successful response

application/json

totalnumberRequired

limitnumberRequired

offsetnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/users/search

GET /api/v2/users/search?query=text HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "values": [
    {
      "id": 1,
      "profileId": 1,
      "displayName": "text",
      "username": "text",
      "avatarUrl": "https://example.com",
      "description": "text",
      "score": 1,
      "status": "ACTIVE",
      "userkeys": [
        "text"
      ],
      "xpTotal": 1,
      "xpStreakDays": 1,
      "xpRemovedDueToAbuse": true,
      "influenceFactor": 1,
      "influenceFactorPercentile": 1,
      "humanVerificationStatus": "REQUESTED",
      "validatorNftCount": 1,
      "links": {
        "profile": "https://example.com",
        "scoreBreakdown": "https://example.com"
      },
      "stats": {
        "review": {
          "received": {
            "negative": 1,
            "neutral": 1,
            "positive": 1
          }
        },
        "vouch": {
          "given": {
            "amountWeiTotal": 1,
            "count": 1
          },
          "received": {
            "amountWeiTotal": 1,
            "count": 1
          }
        },
        "vouchTotals": [
          {
            "balance": {
              "given": 1,
              "received": 1
            },
            "count": {
              "given": 1,
              "received": 1
            },
            "token": {
              "address": "text",
              "decimals": 1,
              "id": "text"
            }
          }
        ]
      }
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

Get a specific user by user ID

get

Path parameters

userIdinteger · max: 2147483647Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/user/{userId}

GET /api/v2/user/{userId} HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "id": 1,
  "profileId": 1,
  "displayName": "text",
  "username": "text",
  "avatarUrl": "https://example.com",
  "description": "text",
  "score": 1,
  "status": "ACTIVE",
  "userkeys": [
    "text"
  ],
  "xpTotal": 1,
  "xpStreakDays": 1,
  "xpRemovedDueToAbuse": true,
  "influenceFactor": 1,
  "influenceFactorPercentile": 1,
  "humanVerificationStatus": "REQUESTED",
  "validatorNftCount": 1,
  "links": {
    "profile": "https://example.com",
    "scoreBreakdown": "https://example.com"
  },
  "stats": {
    "review": {
      "received": {
        "negative": 1,
        "neutral": 1,
        "positive": 1
      }
    },
    "vouch": {
      "given": {
        "amountWeiTotal": 1,
        "count": 1
      },
      "received": {
        "amountWeiTotal": 1,
        "count": 1
      }
    },
    "vouchTotals": [
      {
        "balance": {
          "given": 1,
          "received": 1
        },
        "count": {
          "given": 1,
          "received": 1
        },
        "token": {
          "address": "text",
          "decimals": 1,
          "id": "text"
        }
      }
    ]
  }
}

Get a user by Ethereum address

get

Path parameters

addressstringRequired

Ethereum address (0x-prefixed, 20 bytes)

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/user/by/address/{address}

GET /api/v2/user/by/address/{address} HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "id": 1,
  "profileId": 1,
  "displayName": "text",
  "username": "text",
  "avatarUrl": "https://example.com",
  "description": "text",
  "score": 1,
  "status": "ACTIVE",
  "userkeys": [
    "text"
  ],
  "xpTotal": 1,
  "xpStreakDays": 1,
  "xpRemovedDueToAbuse": true,
  "influenceFactor": 1,
  "influenceFactorPercentile": 1,
  "humanVerificationStatus": "REQUESTED",
  "validatorNftCount": 1,
  "links": {
    "profile": "https://example.com",
    "scoreBreakdown": "https://example.com"
  },
  "stats": {
    "review": {
      "received": {
        "negative": 1,
        "neutral": 1,
        "positive": 1
      }
    },
    "vouch": {
      "given": {
        "amountWeiTotal": 1,
        "count": 1
      },
      "received": {
        "amountWeiTotal": 1,
        "count": 1
      }
    },
    "vouchTotals": [
      {
        "balance": {
          "given": 1,
          "received": 1
        },
        "count": {
          "given": 1,
          "received": 1
        },
        "token": {
          "address": "text",
          "decimals": 1,
          "id": "text"
        }
      }
    ]
  }
}

Get a user by Ethos Everywhere wallet address

get

Path parameters

addressstringRequired

Ethereum address (0x-prefixed, 20 bytes)

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/user/by/ethos-everywhere-wallet/{address}

GET /api/v2/user/by/ethos-everywhere-wallet/{address} HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "id": 1,
  "profileId": 1,
  "displayName": "text",
  "username": "text",
  "avatarUrl": "https://example.com",
  "description": "text",
  "score": 1,
  "status": "ACTIVE",
  "userkeys": [
    "text"
  ],
  "xpTotal": 1,
  "xpStreakDays": 1,
  "xpRemovedDueToAbuse": true,
  "influenceFactor": 1,
  "influenceFactorPercentile": 1,
  "humanVerificationStatus": "REQUESTED",
  "validatorNftCount": 1,
  "links": {
    "profile": "https://example.com",
    "scoreBreakdown": "https://example.com"
  },
  "stats": {
    "review": {
      "received": {
        "negative": 1,
        "neutral": 1,
        "positive": 1
      }
    },
    "vouch": {
      "given": {
        "amountWeiTotal": 1,
        "count": 1
      },
      "received": {
        "amountWeiTotal": 1,
        "count": 1
      }
    },
    "vouchTotals": [
      {
        "balance": {
          "given": 1,
          "received": 1
        },
        "count": {
          "given": 1,
          "received": 1
        },
        "token": {
          "address": "text",
          "decimals": 1,
          "id": "text"
        }
      }
    ]
  }
}

Get a user by profile ID

get

Path parameters

profileIdinteger · max: 2147483647Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/user/by/profile-id/{profileId}

GET /api/v2/user/by/profile-id/{profileId} HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "id": 1,
  "profileId": 1,
  "displayName": "text",
  "username": "text",
  "avatarUrl": "https://example.com",
  "description": "text",
  "score": 1,
  "status": "ACTIVE",
  "userkeys": [
    "text"
  ],
  "xpTotal": 1,
  "xpStreakDays": 1,
  "xpRemovedDueToAbuse": true,
  "influenceFactor": 1,
  "influenceFactorPercentile": 1,
  "humanVerificationStatus": "REQUESTED",
  "validatorNftCount": 1,
  "links": {
    "profile": "https://example.com",
    "scoreBreakdown": "https://example.com"
  },
  "stats": {
    "review": {
      "received": {
        "negative": 1,
        "neutral": 1,
        "positive": 1
      }
    },
    "vouch": {
      "given": {
        "amountWeiTotal": 1,
        "count": 1
      },
      "received": {
        "amountWeiTotal": 1,
        "count": 1
      }
    },
    "vouchTotals": [
      {
        "balance": {
          "given": 1,
          "received": 1
        },
        "count": {
          "given": 1,
          "received": 1
        },
        "token": {
          "address": "text",
          "decimals": 1,
          "id": "text"
        }
      }
    ]
  }
}

Get a user by username

get

Path parameters

usernamestring · min: 1Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/user/by/username/{username}

GET /api/v2/user/by/username/{username} HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "id": 1,
  "profileId": 1,
  "displayName": "text",
  "username": "text",
  "avatarUrl": "https://example.com",
  "description": "text",
  "score": 1,
  "status": "ACTIVE",
  "userkeys": [
    "text"
  ],
  "xpTotal": 1,
  "xpStreakDays": 1,
  "xpRemovedDueToAbuse": true,
  "influenceFactor": 1,
  "influenceFactorPercentile": 1,
  "humanVerificationStatus": "REQUESTED",
  "validatorNftCount": 1,
  "links": {
    "profile": "https://example.com",
    "scoreBreakdown": "https://example.com"
  },
  "stats": {
    "review": {
      "received": {
        "negative": 1,
        "neutral": 1,
        "positive": 1
      }
    },
    "vouch": {
      "given": {
        "amountWeiTotal": 1,
        "count": 1
      },
      "received": {
        "amountWeiTotal": 1,
        "count": 1
      }
    },
    "vouchTotals": [
      {
        "balance": {
          "given": 1,
          "received": 1
        },
        "count": {
          "given": 1,
          "received": 1
        },
        "token": {
          "address": "text",
          "decimals": 1,
          "id": "text"
        }
      }
    ]
  }
}

Get a user by Twitter/X account ID or username

get

Path parameters

accountIdOrUsernamestring · min: 1Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/user/by/x/{accountIdOrUsername}

GET /api/v2/user/by/x/{accountIdOrUsername} HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "id": 1,
  "profileId": 1,
  "displayName": "text",
  "username": "text",
  "avatarUrl": "https://example.com",
  "description": "text",
  "score": 1,
  "status": "ACTIVE",
  "userkeys": [
    "text"
  ],
  "xpTotal": 1,
  "xpStreakDays": 1,
  "xpRemovedDueToAbuse": true,
  "influenceFactor": 1,
  "influenceFactorPercentile": 1,
  "humanVerificationStatus": "REQUESTED",
  "validatorNftCount": 1,
  "links": {
    "profile": "https://example.com",
    "scoreBreakdown": "https://example.com"
  },
  "stats": {
    "review": {
      "received": {
        "negative": 1,
        "neutral": 1,
        "positive": 1
      }
    },
    "vouch": {
      "given": {
        "amountWeiTotal": 1,
        "count": 1
      },
      "received": {
        "amountWeiTotal": 1,
        "count": 1
      }
    },
    "vouchTotals": [
      {
        "balance": {
          "given": 1,
          "received": 1
        },
        "count": {
          "given": 1,
          "received": 1
        },
        "token": {
          "address": "text",
          "decimals": 1,
          "id": "text"
        }
      }
    ]
  }
}

Get a user by Discord user ID

get

Path parameters

discordUserIdstring · min: 1Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/user/by/discord/{discordUserId}

GET /api/v2/user/by/discord/{discordUserId} HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "id": 1,
  "profileId": 1,
  "displayName": "text",
  "username": "text",
  "avatarUrl": "https://example.com",
  "description": "text",
  "score": 1,
  "status": "ACTIVE",
  "userkeys": [
    "text"
  ],
  "xpTotal": 1,
  "xpStreakDays": 1,
  "xpRemovedDueToAbuse": true,
  "influenceFactor": 1,
  "influenceFactorPercentile": 1,
  "humanVerificationStatus": "REQUESTED",
  "validatorNftCount": 1,
  "links": {
    "profile": "https://example.com",
    "scoreBreakdown": "https://example.com"
  },
  "stats": {
    "review": {
      "received": {
        "negative": 1,
        "neutral": 1,
        "positive": 1
      }
    },
    "vouch": {
      "given": {
        "amountWeiTotal": 1,
        "count": 1
      },
      "received": {
        "amountWeiTotal": 1,
        "count": 1
      }
    },
    "vouchTotals": [
      {
        "balance": {
          "given": 1,
          "received": 1
        },
        "count": {
          "given": 1,
          "received": 1
        },
        "token": {
          "address": "text",
          "decimals": 1,
          "id": "text"
        }
      }
    ]
  }
}

Get a user by Farcaster user ID

get

Path parameters

farcasterUserIdstring · min: 1Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/user/by/farcaster/{farcasterUserId}

GET /api/v2/user/by/farcaster/{farcasterUserId} HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "id": 1,
  "profileId": 1,
  "displayName": "text",
  "username": "text",
  "avatarUrl": "https://example.com",
  "description": "text",
  "score": 1,
  "status": "ACTIVE",
  "userkeys": [
    "text"
  ],
  "xpTotal": 1,
  "xpStreakDays": 1,
  "xpRemovedDueToAbuse": true,
  "influenceFactor": 1,
  "influenceFactorPercentile": 1,
  "humanVerificationStatus": "REQUESTED",
  "validatorNftCount": 1,
  "links": {
    "profile": "https://example.com",
    "scoreBreakdown": "https://example.com"
  },
  "stats": {
    "review": {
      "received": {
        "negative": 1,
        "neutral": 1,
        "positive": 1
      }
    },
    "vouch": {
      "given": {
        "amountWeiTotal": 1,
        "count": 1
      },
      "received": {
        "amountWeiTotal": 1,
        "count": 1
      }
    },
    "vouchTotals": [
      {
        "balance": {
          "given": 1,
          "received": 1
        },
        "count": {
          "given": 1,
          "received": 1
        },
        "token": {
          "address": "text",
          "decimals": 1,
          "id": "text"
        }
      }
    ]
  }
}

Get a user by Farcaster username

get

Path parameters

farcasterUsernamestring · min: 1Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/user/by/farcaster/username/{farcasterUsername}

GET /api/v2/user/by/farcaster/username/{farcasterUsername} HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "id": 1,
  "profileId": 1,
  "displayName": "text",
  "username": "text",
  "avatarUrl": "https://example.com",
  "description": "text",
  "score": 1,
  "status": "ACTIVE",
  "userkeys": [
    "text"
  ],
  "xpTotal": 1,
  "xpStreakDays": 1,
  "xpRemovedDueToAbuse": true,
  "influenceFactor": 1,
  "influenceFactorPercentile": 1,
  "humanVerificationStatus": "REQUESTED",
  "validatorNftCount": 1,
  "links": {
    "profile": "https://example.com",
    "scoreBreakdown": "https://example.com"
  },
  "stats": {
    "review": {
      "received": {
        "negative": 1,
        "neutral": 1,
        "positive": 1
      }
    },
    "vouch": {
      "given": {
        "amountWeiTotal": 1,
        "count": 1
      },
      "received": {
        "amountWeiTotal": 1,
        "count": 1
      }
    },
    "vouchTotals": [
      {
        "balance": {
          "given": 1,
          "received": 1
        },
        "count": {
          "given": 1,
          "received": 1
        },
        "token": {
          "address": "text",
          "decimals": 1,
          "id": "text"
        }
      }
    ]
  }
}

Get a user by Telegram user ID

get

Path parameters

telegramUserIdstring · min: 1Required

Responses

200

Successful response

application/json

idnumberRequired

profileIdnumber · nullableRequired

displayNamestringRequired

usernamestring · nullableRequired

avatarUrlstring · uriRequired

descriptionstring · nullableRequired

scorenumberRequired

statusstring · enumRequiredPossible values:

userkeysstring[]Required

xpTotalnumberRequired

xpStreakDaysnumberRequired

xpRemovedDueToAbusebooleanRequired

influenceFactornumberRequired

influenceFactorPercentilenumberRequired

humanVerificationStatusstring · enum · nullableOptionalPossible values:

validatorNftCountnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/user/by/telegram/{telegramUserId}

GET /api/v2/user/by/telegram/{telegramUserId} HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "id": 1,
  "profileId": 1,
  "displayName": "text",
  "username": "text",
  "avatarUrl": "https://example.com",
  "description": "text",
  "score": 1,
  "status": "ACTIVE",
  "userkeys": [
    "text"
  ],
  "xpTotal": 1,
  "xpStreakDays": 1,
  "xpRemovedDueToAbuse": true,
  "influenceFactor": 1,
  "influenceFactorPercentile": 1,
  "humanVerificationStatus": "REQUESTED",
  "validatorNftCount": 1,
  "links": {
    "profile": "https://example.com",
    "scoreBreakdown": "https://example.com"
  },
  "stats": {
    "review": {
      "received": {
        "negative": 1,
        "neutral": 1,
        "positive": 1
      }
    },
    "vouch": {
      "given": {
        "amountWeiTotal": 1,
        "count": 1
      },
      "received": {
        "amountWeiTotal": 1,
        "count": 1
      }
    },
    "vouchTotals": [
      {
        "balance": {
          "given": 1,
          "received": 1
        },
        "count": {
          "given": 1,
          "received": 1
        },
        "token": {
          "address": "text",
          "decimals": 1,
          "id": "text"
        }
      }
    ]
  }
}

Get position in each category for user

get

Path parameters

userkeystringRequired

Responses

200

Successful response

application/json

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/users/{userkey}/categories

GET /api/v2/users/{userkey}/categories HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "categoryRanks": [
    {
      "rank": 1,
      "category": {
        "id": 1,
        "slug": "text",
        "name": "text",
        "description": "text",
        "showOnLeaderboard": true,
        "showInDailyService": true,
        "showInDailyBounty": true,
        "bannerImageUrl": "https://example.com",
        "userCount": 1
      }
    }
  ]
}

Refresh x.com profile details like name, avatar, etc.

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Successful response

application/json

okbooleanRequired

messagestringRequired

401

Authorization not provided

application/json

403

Insufficient access

application/json

500

Internal server error

application/json

post/users/refresh/twitter

POST /api/v2/users/refresh/twitter HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ok": true,
  "message": "text"
}

Refresh x.com profile details like name, avatar, etc.

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

userkeystringRequired

Responses

200

Successful response

application/json

okbooleanRequired

messagestringRequired

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

500

Internal server error

application/json

post/users/{userkey}/refresh/twitter

POST /api/v2/users/{userkey}/refresh/twitter HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ok": true,
  "message": "text"
}

Refresh user streak calculation in the users table

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

userkeystringRequired

Responses

200

Successful response

application/json

okbooleanRequired

messagestringRequired

oldStreaknumberRequired

newStreaknumberRequired

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

500

Internal server error

application/json

post/users/{userkey}/refresh/streak

POST /api/v2/users/{userkey}/refresh/streak HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ok": true,
  "message": "text",
  "oldStreak": 1,
  "newStreak": 1
}

Get suggested Ethos users for the current user to review

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · min: 1 · max: 50OptionalDefault: 50

Responses

200

Successful response

application/json

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

404

Not found

application/json

500

Internal server error

application/json

get/users/me/review-suggestions

GET /api/v2/users/me/review-suggestions HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "id": 1,
      "profileId": 1,
      "displayName": "text",
      "username": "text",
      "avatarUrl": "https://example.com",
      "description": "text",
      "score": 1,
      "status": "ACTIVE",
      "userkeys": [
        "text"
      ],
      "xpTotal": 1,
      "xpStreakDays": 1,
      "xpRemovedDueToAbuse": true,
      "influenceFactor": 1,
      "influenceFactorPercentile": 1,
      "humanVerificationStatus": "REQUESTED",
      "validatorNftCount": 1,
      "links": {
        "profile": "https://example.com",
        "scoreBreakdown": "https://example.com"
      },
      "stats": {
        "review": {
          "received": {
            "negative": 1,
            "neutral": 1,
            "positive": 1
          }
        },
        "vouch": {
          "given": {
            "amountWeiTotal": 1,
            "count": 1
          },
          "received": {
            "amountWeiTotal": 1,
            "count": 1
          }
        },
        "vouchTotals": [
          {
            "balance": {
              "given": 1,
              "received": 1
            },
            "count": {
              "given": 1,
              "received": 1
            },
            "token": {
              "address": "text",
              "decimals": 1,
              "id": "text"
            }
          }
        ]
      }
    }
  ]
}

Get suggested users to review, endorsed by your connections

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

endorserSampleSizeinteger · min: 1 · max: 10OptionalDefault: 3

limitinteger · min: 1 · max: 50OptionalDefault: 50

Responses

200

Successful response

application/json

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

404

Not found

application/json

500

Internal server error

application/json

get/users/me/discover-suggestions

GET /api/v2/users/me/discover-suggestions HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "user": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          },
          "vouchTotals": [
            {
              "balance": {
                "given": 1,
                "received": 1
              },
              "count": {
                "given": 1,
                "received": 1
              },
              "token": {
                "address": "text",
                "decimals": 1,
                "id": "text"
              }
            }
          ]
        }
      },
      "endorsers": [
        {
          "id": 1,
          "profileId": 1,
          "displayName": "text",
          "username": "text",
          "avatarUrl": "https://example.com",
          "description": "text",
          "score": 1,
          "status": "ACTIVE",
          "userkeys": [
            "text"
          ],
          "xpTotal": 1,
          "xpStreakDays": 1,
          "xpRemovedDueToAbuse": true,
          "influenceFactor": 1,
          "influenceFactorPercentile": 1,
          "humanVerificationStatus": "REQUESTED",
          "validatorNftCount": 1,
          "links": {
            "profile": "https://example.com",
            "scoreBreakdown": "https://example.com"
          },
          "stats": {
            "review": {
              "received": {
                "negative": 1,
                "neutral": 1,
                "positive": 1
              }
            },
            "vouch": {
              "given": {
                "amountWeiTotal": 1,
                "count": 1
              },
              "received": {
                "amountWeiTotal": 1,
                "count": 1
              }
            },
            "vouchTotals": [
              {
                "balance": {
                  "given": 1,
                  "received": 1
                },
                "count": {
                  "given": 1,
                  "received": 1
                },
                "token": {
                  "address": "text",
                  "decimals": 1,
                  "id": "text"
                }
              }
            ]
          }
        }
      ],
      "endorserCount": 1,
      "connectionDegree": "1st",
      "source": "connections"
    }
  ]
}

Get the user’s top-scoring wallet address by wallet quality

get

Path parameters

userkeystringRequired

Responses

200

Successful response

application/json

addressstring · nullableRequired

Ethereum address (0x-prefixed, 20 bytes)

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/users/{userkey}/top-quality-wallet

GET /api/v2/users/{userkey}/top-quality-wallet HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "address": "text"
}