Benefits

List limited-time benefits with pagination and filtering

get

Retrieve a paginated list of limited-time benefits. Supports filtering by status and sorting.

Query parameters

statusstring · enumOptionalPossible values:

sortBystring · enumOptionalDefault: expirationDatePossible values:

sortDirectionstring · enumOptionalDefault: ascPossible values:

limitinteger · max: 50OptionalDefault: 50

offsetnumberOptionalDefault: 0

Responses

200

Successful response

application/json

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/benefits/limited-time

HTTPcURLJavaScriptPython

GET /api/v2/benefits/limited-time HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "values": [
    {
      "id": 1,
      "title": "text",
      "shortDescription": "text",
      "longDescription": "text",
      "logoImageUrl": "text",
      "carouselImageUrl": "text",
      "primaryLinkLabel": "text",
      "primaryLinkUrl": "text",
      "secondaryLinkLabel": "text",
      "secondaryLinkUrl": "text",
      "status": "ACTIVE",
      "issuer": {
        "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,
        "mommyPawnshopBingo": "REQUESTED",
        "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
            }
          }
        }
      },
      "createdAt": "text",
      "updatedAt": "text",
      "type": "LIMITED_TIME_PERK",
      "qualifications": {
        "scoreThreshold": 1,
        "isValidatorEligible": true
      },
      "startDate": "text",
      "expirationDate": "text"
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

List score-based benefits with pagination and filtering

get

Retrieve a paginated list of score-based benefits. By default, returns all benefits. Optionally filter by status, multiple category IDs, and user score.

⚠️ IMPORTANT: Due to OpenAPI UI limitations, the categoryIds parameter requires at least 2 items to work correctly. Single category selection will result in a validation error.

Query parameters

statusstring · enumOptionalPossible values:

categoryIdsinteger[]Optional

scoreintegerOptional

limitinteger · max: 50OptionalDefault: 50

offsetnumberOptionalDefault: 0

Responses

200

Successful response

application/json

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/benefits/score-based

HTTPcURLJavaScriptPython

GET /api/v2/benefits/score-based HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "values": [
    {
      "id": 1,
      "title": "text",
      "shortDescription": "text",
      "longDescription": "text",
      "logoImageUrl": "text",
      "carouselImageUrl": "text",
      "primaryLinkLabel": "text",
      "primaryLinkUrl": "text",
      "secondaryLinkLabel": "text",
      "secondaryLinkUrl": "text",
      "status": "ACTIVE",
      "issuer": {
        "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,
        "mommyPawnshopBingo": "REQUESTED",
        "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
            }
          }
        }
      },
      "createdAt": "text",
      "updatedAt": "text",
      "type": "SCORE_BASED",
      "qualifications": [
        {
          "scoreThreshold": 1,
          "label": "text"
        }
      ],
      "categoryId": 1,
      "category": {
        "id": 1,
        "name": "text",
        "displayName": "text",
        "sortOrder": 1,
        "isActive": true,
        "createdAt": "text",
        "updatedAt": "text"
      }
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

List all benefits (admin only)

get

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

typestring · enumOptionalPossible values:

statusstring · enumOptionalPossible values:

categoryIdsinteger[]Optional

limitinteger · max: 50OptionalDefault: 50

offsetnumberOptionalDefault: 0

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

/benefits/admin/all

HTTPcURLJavaScriptPython

GET /api/v2/benefits/admin/all HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "id": 1,
      "title": "text",
      "shortDescription": "text",
      "longDescription": "text",
      "logoImageUrl": "text",
      "carouselImageUrl": "text",
      "primaryLinkLabel": "text",
      "primaryLinkUrl": "text",
      "secondaryLinkLabel": "text",
      "secondaryLinkUrl": "text",
      "status": "ACTIVE",
      "issuer": {
        "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,
        "mommyPawnshopBingo": "REQUESTED",
        "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
            }
          }
        }
      },
      "createdAt": "text",
      "updatedAt": "text",
      "type": "LIMITED_TIME_PERK",
      "qualifications": {
        "scoreThreshold": 1,
        "isValidatorEligible": true
      },
      "startDate": "text",
      "expirationDate": "text"
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

Get all categories

get

Query parameters

activeOnlybooleanOptionalDefault: false

Responses

200

Successful response

application/json

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/benefits/categories

HTTPcURLJavaScriptPython

GET /api/v2/benefits/categories HTTP/1.1
Host: api.ethos.network
Accept: */*

[
  {
    "id": 1,
    "name": "text",
    "displayName": "text",
    "sortOrder": 1,
    "isActive": true,
    "createdAt": "text",
    "updatedAt": "text"
  }
]

Create a new category

post

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

namestring · min: 1 · max: 100Required

displayNamestring · min: 1 · max: 100Required

sortOrderintegerOptional

isActivebooleanOptional

Responses

200

Successful response

application/json

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

500

Internal server error

application/json

post

/benefits/categories

HTTPcURLJavaScriptPython

POST /api/v2/benefits/categories HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "name": "text",
  "displayName": "text",
  "sortOrder": 1,
  "isActive": true
}

{
  "id": 1,
  "name": "text",
  "displayName": "text",
  "sortOrder": 1,
  "isActive": true,
  "createdAt": "text",
  "updatedAt": "text"
}

Update a category

put

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idintegerRequired

Body

application/json

namestring · min: 1 · max: 100Optional

displayNamestring · min: 1 · max: 100Optional

sortOrderintegerOptional

isActivebooleanOptional

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

put

/benefits/categories/{id}

HTTPcURLJavaScriptPython

PUT /api/v2/benefits/categories/{id} HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "name": "text",
  "displayName": "text",
  "sortOrder": 1,
  "isActive": true
}

{
  "id": 1,
  "name": "text",
  "displayName": "text",
  "sortOrder": 1,
  "isActive": true,
  "createdAt": "text",
  "updatedAt": "text"
}

Delete a category

delete

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idintegerRequired

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

delete

/benefits/categories/{id}

HTTPcURLJavaScriptPython

DELETE /api/v2/benefits/categories/{id} HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "name": "text",
  "displayName": "text",
  "sortOrder": 1,
  "isActive": true,
  "createdAt": "text",
  "updatedAt": "text"
}

Create a new benefit

post

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

typestring · enumRequiredPossible values:

titlestring · min: 1 · max: 255Required

shortDescriptionstring · min: 1 · max: 256Required

longDescriptionstring · min: 1Required

logoImageUrlstringOptional

carouselImageUrlstringOptional

primaryLinkLabelstring · min: 1Required

primaryLinkUrlstring · uriRequired

secondaryLinkLabelstringOptional

secondaryLinkUrlstringOptional

statusstring · enumOptionalDefault: INACTIVEPossible values:

issuerUserIdinteger · max: 2147483647Optional

qualificationsany ofRequired

or

startDatestringOptional

expirationDatestringOptional

categoryIdintegerOptional

Responses

200

Successful response

application/json

Responseone of

or

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

500

Internal server error

application/json

post

/benefits

HTTPcURLJavaScriptPython

POST /api/v2/benefits HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 421

{
  "type": "LIMITED_TIME_PERK",
  "title": "text",
  "shortDescription": "text",
  "longDescription": "text",
  "logoImageUrl": "text",
  "carouselImageUrl": "text",
  "primaryLinkLabel": "text",
  "primaryLinkUrl": "https://example.com",
  "secondaryLinkLabel": "text",
  "secondaryLinkUrl": "text",
  "status": "INACTIVE",
  "issuerUserId": 1,
  "qualifications": {
    "scoreThreshold": 1,
    "isValidatorEligible": true
  },
  "startDate": "text",
  "expirationDate": "text",
  "categoryId": 1
}

{
  "id": 1,
  "title": "text",
  "shortDescription": "text",
  "longDescription": "text",
  "logoImageUrl": "text",
  "carouselImageUrl": "text",
  "primaryLinkLabel": "text",
  "primaryLinkUrl": "text",
  "secondaryLinkLabel": "text",
  "secondaryLinkUrl": "text",
  "status": "ACTIVE",
  "issuer": {
    "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,
    "mommyPawnshopBingo": "REQUESTED",
    "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
        }
      }
    }
  },
  "createdAt": "text",
  "updatedAt": "text",
  "type": "LIMITED_TIME_PERK",
  "qualifications": {
    "scoreThreshold": 1,
    "isValidatorEligible": true
  },
  "startDate": "text",
  "expirationDate": "text"
}

Update an existing benefit

put

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

benefitIdintegerRequired

Body

application/json

titlestring · min: 1 · max: 255Optional

shortDescriptionstring · min: 1 · max: 256Optional

longDescriptionstring · min: 1Optional

logoImageUrlstringOptional

carouselImageUrlstringOptional

primaryLinkLabelstring · min: 1Optional

primaryLinkUrlstring · uriOptional

secondaryLinkLabelstringOptional

secondaryLinkUrlstringOptional

qualificationsany ofOptional

or

statusstring · enumOptionalPossible values:

issuerUserIdinteger | nullableOptional

startDatestringOptional

expirationDatestringOptional

categoryIdintegerOptional

Responses

200

Successful response

application/json

Responseone of

or

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

put

/benefits/{benefitId}

HTTPcURLJavaScriptPython

PUT /api/v2/benefits/{benefitId} HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 392

{
  "title": "text",
  "shortDescription": "text",
  "longDescription": "text",
  "logoImageUrl": "text",
  "carouselImageUrl": "text",
  "primaryLinkLabel": "text",
  "primaryLinkUrl": "https://example.com",
  "secondaryLinkLabel": "text",
  "secondaryLinkUrl": "text",
  "qualifications": {
    "scoreThreshold": 1,
    "isValidatorEligible": true
  },
  "status": "ACTIVE",
  "issuerUserId": 1,
  "startDate": "text",
  "expirationDate": "text",
  "categoryId": 1
}

{
  "id": 1,
  "title": "text",
  "shortDescription": "text",
  "longDescription": "text",
  "logoImageUrl": "text",
  "carouselImageUrl": "text",
  "primaryLinkLabel": "text",
  "primaryLinkUrl": "text",
  "secondaryLinkLabel": "text",
  "secondaryLinkUrl": "text",
  "status": "ACTIVE",
  "issuer": {
    "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,
    "mommyPawnshopBingo": "REQUESTED",
    "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
        }
      }
    }
  },
  "createdAt": "text",
  "updatedAt": "text",
  "type": "LIMITED_TIME_PERK",
  "qualifications": {
    "scoreThreshold": 1,
    "isValidatorEligible": true
  },
  "startDate": "text",
  "expirationDate": "text"
}

Delete a benefit

delete

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

benefitIdintegerRequired

Responses

200

Successful response

application/json

Responseone of

or

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

delete

/benefits/{benefitId}

HTTPcURLJavaScriptPython

DELETE /api/v2/benefits/{benefitId} HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "title": "text",
  "shortDescription": "text",
  "longDescription": "text",
  "logoImageUrl": "text",
  "carouselImageUrl": "text",
  "primaryLinkLabel": "text",
  "primaryLinkUrl": "text",
  "secondaryLinkLabel": "text",
  "secondaryLinkUrl": "text",
  "status": "ACTIVE",
  "issuer": {
    "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,
    "mommyPawnshopBingo": "REQUESTED",
    "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
        }
      }
    }
  },
  "createdAt": "text",
  "updatedAt": "text",
  "type": "LIMITED_TIME_PERK",
  "qualifications": {
    "scoreThreshold": 1,
    "isValidatorEligible": true
  },
  "startDate": "text",
  "expirationDate": "text"
}