Categories

List categories

get
Query parameters
showOnLeaderboardbooleanOptional
showInDailyServicebooleanOptional
withUserCountbooleanOptional
limitnumberOptionalDefault: 50
offsetnumberOptionalDefault: 0
Responses
200
Successful response
application/json
get
GET /api/v2/categories HTTP/1.1
Host: api.ethos.network
Accept: */*
{
  "categories": [
    {
      "id": 1,
      "slug": "text",
      "name": "text",
      "description": "text",
      "showOnLeaderboard": true,
      "showInDailyService": true,
      "bannerImageUrl": "https://example.com",
      "userCount": 1
    }
  ],
  "total": 1
}

Create a new category

post
Authorizations
Body
slugstring · min: 1 · max: 50Optional
namestringRequired
descriptionstringOptional
showOnLeaderboardbooleanRequired
showInDailyServicebooleanRequired
bannerImageUrlstring · uriOptional
Responses
200
Successful response
application/json
post
POST /api/v2/categories HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "slug": "text",
  "name": "text",
  "description": "text",
  "showOnLeaderboard": true,
  "showInDailyService": true,
  "bannerImageUrl": "https://example.com"
}
{
  "id": 1,
  "slug": "text",
  "name": "text",
  "description": "text",
  "showOnLeaderboard": true,
  "showInDailyService": true,
  "bannerImageUrl": "https://example.com",
  "userCount": 1
}

Get a specific category by ID

get
Path parameters
idintegerRequired
Responses
200
Successful response
application/json
get
GET /api/v2/categories/{id} HTTP/1.1
Host: api.ethos.network
Accept: */*
{
  "id": 1,
  "slug": "text",
  "name": "text",
  "description": "text",
  "showOnLeaderboard": true,
  "showInDailyService": true,
  "bannerImageUrl": "https://example.com",
  "userCount": 1
}

Get summaries for multiple categories

get
Query parameters
showOnLeaderboardbooleanOptional
showInDailyServicebooleanOptional
topUsersLimitnumber · max: 50OptionalDefault: 10
Responses
200
Successful response
application/json
get
GET /api/v2/categories/summaries/bulk HTTP/1.1
Host: api.ethos.network
Accept: */*
[
  {
    "id": 1,
    "slug": "text",
    "name": "text",
    "description": "text",
    "showOnLeaderboard": true,
    "showInDailyService": true,
    "bannerImageUrl": "https://example.com",
    "topUsers": [
      {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          }
        }
      }
    ],
    "userStats": {
      "totalUsers": 1,
      "averageScore": 1,
      "totalXp": 1,
      "averageXpTotal": 1,
      "totalXpStreakDays": 1,
      "averageXpStreakDays": 1,
      "totalReviewReceivedPositive": 1,
      "averageReviewReceivedPositive": 1,
      "totalReviewReceivedNegative": 1,
      "averageReviewReceivedNegative": 1,
      "totalReviewReceivedNeutral": 1,
      "averageReviewReceivedNeutral": 1,
      "totalVouchReceivedCount": 1,
      "averageVouchReceivedCount": 1,
      "totalVouchGivenCount": 1,
      "averageVouchGivenCount": 1,
      "totalVouchReceivedAmountWei": 1,
      "averageVouchReceivedAmountWei": 1,
      "totalVouchGivenAmountWei": 1,
      "averageVouchGivenAmountWei": 1
    }
  }
]

Update an existing category

put
Authorizations
Path parameters
categoryIdintegerRequired
Body
slugstring · min: 1 · max: 50Optional
namestringOptional
descriptionstringOptional
showOnLeaderboardbooleanOptional
showInDailyServicebooleanOptional
bannerImageUrlstring · uriOptional
Responses
200
Successful response
application/json
put
PUT /api/v2/categories/{categoryId} HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "slug": "text",
  "name": "text",
  "description": "text",
  "showOnLeaderboard": true,
  "showInDailyService": true,
  "bannerImageUrl": "https://example.com"
}
{
  "id": 1,
  "slug": "text",
  "name": "text",
  "description": "text",
  "showOnLeaderboard": true,
  "showInDailyService": true,
  "bannerImageUrl": "https://example.com",
  "userCount": 1
}

Delete a category

delete
Authorizations
Path parameters
categoryIdintegerRequired
Responses
200
Successful response
application/json
delete
DELETE /api/v2/categories/{categoryId} HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "id": 1,
  "slug": "text",
  "name": "text",
  "description": "text",
  "showOnLeaderboard": true,
  "showInDailyService": true,
  "bannerImageUrl": "https://example.com",
  "userCount": 1
}

Get users belonging to a category

get
Path parameters
categoryIdintegerRequired
Query parameters
limitnumberOptionalDefault: 50
offsetnumberOptionalDefault: 0
searchTextstringOptional
orderBystring · enumOptionalDefault: createdAtPossible values:
Responses
200
Successful response
application/json
get
GET /api/v2/categories/{categoryId}/users HTTP/1.1
Host: api.ethos.network
Accept: */*
{
  "users": [
    {
      "id": 1,
      "profileId": 1,
      "displayName": "text",
      "username": "text",
      "avatarUrl": "https://example.com",
      "description": "text",
      "score": 1,
      "status": "ACTIVE",
      "userkeys": [
        "text"
      ],
      "xpTotal": 1,
      "xpStreakDays": 1,
      "stats": {
        "review": {
          "received": {
            "negative": 1,
            "neutral": 1,
            "positive": 1
          }
        },
        "vouch": {
          "given": {
            "amountWeiTotal": 1,
            "count": 1
          },
          "received": {
            "amountWeiTotal": 1,
            "count": 1
          }
        }
      },
      "addedAt": "text"
    }
  ],
  "total": 1
}

Add users to a category

post
Authorizations
Path parameters
categoryIdintegerRequired
Body
userIdsinteger[] · min: 1Required
Responses
200
Successful response
application/json
post
POST /api/v2/categories/{categoryId}/users HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

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

Remove users from a category

delete
Authorizations
Path parameters
categoryIdintegerRequired
Query parameters
userIdsinteger[] · min: 1Required
Responses
200
Successful response
application/json
delete
DELETE /api/v2/categories/{categoryId}/users HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "id": 1,
  "slug": "text",
  "name": "text",
  "description": "text",
  "showOnLeaderboard": true,
  "showInDailyService": true,
  "bannerImageUrl": "https://example.com",
  "userCount": 1
}

Bulk import users to a category via Twitter URLs

post
Authorizations
Path parameters
categoryIdintegerRequired
Body
twitterUrlsstring[]Required
Responses
200
Successful response
application/json
post
POST /api/v2/categories/{categoryId}/bulk-import HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "twitterUrls": [
    "text"
  ]
}
{
  "total": 1,
  "added": 1,
  "alreadyInCategory": 1,
  "notFound": 1,
  "invalid": 1,
  "duplicates": 1,
  "errors": [
    {
      "url": "text",
      "reason": "text"
    }
  ]
}