Benefits

List limited-time benefits with pagination and filtering

get

Retrieve a paginated list of limited-time benefits (perks and codes). 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

totalnumberRequired

limitnumberRequired

offsetnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/benefits/limited-time

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

{
  "values": [
    {
      "id": 1,
      "type": "LIMITED_TIME_CODE",
      "shortDescription": "text",
      "longDescription": "text",
      "logoImageUrl": "https://example.com",
      "carouselImageUrl": "https://example.com",
      "secondaryLinkLabel": "text",
      "secondaryLinkUrl": "https://example.com",
      "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,
        "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
            }
          }
        }
      },
      "isLocked": true,
      "createdAt": "text",
      "updatedAt": "text",
      "qualifications": {
        "scoreThreshold": 1
      },
      "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

totalnumberRequired

limitnumberRequired

offsetnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/benefits/score-based

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

{
  "values": [
    {
      "id": 1,
      "type": "SCORE_BASED",
      "shortDescription": "text",
      "longDescription": "text",
      "logoImageUrl": "https://example.com",
      "carouselImageUrl": "https://example.com",
      "secondaryLinkLabel": "text",
      "secondaryLinkUrl": "https://example.com",
      "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,
        "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
            }
          }
        }
      },
      "isLocked": true,
      "createdAt": "text",
      "updatedAt": "text",
      "qualifications": [
        {
          "scoreThreshold": 1,
          "label": "text"
        }
      ],
      "primaryLinkLabel": "text",
      "primaryLinkUrl": "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

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

totalnumberRequired

limitnumberRequired

offsetnumberRequired

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

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

{
  "values": [
    {
      "id": 1,
      "type": "LIMITED_TIME_CODE",
      "shortDescription": "text",
      "longDescription": "text",
      "logoImageUrl": "https://example.com",
      "carouselImageUrl": "https://example.com",
      "secondaryLinkLabel": "text",
      "secondaryLinkUrl": "https://example.com",
      "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,
        "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
            }
          }
        }
      },
      "isLocked": true,
      "createdAt": "text",
      "updatedAt": "text",
      "qualifications": {
        "scoreThreshold": 1
      },
      "startDate": "text",
      "expirationDate": "text"
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

Get all categories

get

Query parameters

activeOnlybooleanOptionalDefault: false

Responses

200

Successful response

application/json

idnumberRequired

namestringRequired

displayNamestringRequired

sortOrdernumberRequired

isActivebooleanRequired

createdAtstringRequired

updatedAtstringRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/benefits/categories

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

namestring · min: 1 · max: 100Required

displayNamestring · min: 1 · max: 100Required

sortOrderintegerOptional

isActivebooleanOptional

Responses

200

Successful response

application/json

idnumberRequired

namestringRequired

displayNamestringRequired

sortOrdernumberRequired

isActivebooleanRequired

createdAtstringRequired

updatedAtstringRequired

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

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idintegerRequired

Body

namestring · min: 1 · max: 100Optional

displayNamestring · min: 1 · max: 100Optional

sortOrderintegerOptional

isActivebooleanOptional

Responses

200

Successful response

application/json

idnumberRequired

namestringRequired

displayNamestringRequired

sortOrdernumberRequired

isActivebooleanRequired

createdAtstringRequired

updatedAtstringRequired

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}

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idintegerRequired

Responses

200

Successful response

application/json

idnumberRequired

namestringRequired

displayNamestringRequired

sortOrdernumberRequired

isActivebooleanRequired

createdAtstringRequired

updatedAtstringRequired

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}

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

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

typestring · enumRequiredPossible values:

shortDescriptionstring · min: 1 · max: 256Required

longDescriptionstring · min: 1Required

logoImageUrlstringOptional

carouselImageUrlstringOptional

secondaryLinkLabelstringOptional

secondaryLinkUrlstring · uriOptional

statusstring · enumOptionalDefault: INACTIVEPossible values:

issuerUserIdinteger · max: 2147483647Optional

isLockedbooleanOptionalDefault: false

primaryLinkLabelstringOptional

primaryLinkUrlstring · uriOptional

qualificationsany ofOptional

startDatestringOptional

expirationDatestringOptional

categoryIdintegerOptional

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

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

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

{
  "id": 1,
  "type": "LIMITED_TIME_CODE",
  "shortDescription": "text",
  "longDescription": "text",
  "logoImageUrl": "https://example.com",
  "carouselImageUrl": "https://example.com",
  "secondaryLinkLabel": "text",
  "secondaryLinkUrl": "https://example.com",
  "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,
    "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
        }
      }
    }
  },
  "isLocked": true,
  "createdAt": "text",
  "updatedAt": "text",
  "qualifications": {
    "scoreThreshold": 1
  },
  "startDate": "text",
  "expirationDate": "text"
}

Update an existing benefit

put

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

benefitIdintegerRequired

Body

shortDescriptionstring · min: 1 · max: 256Optional

longDescriptionstring · min: 1Optional

logoImageUrlstringOptional

carouselImageUrlstringOptional

primaryLinkLabelstringOptional

primaryLinkUrlstring · uriOptional

secondaryLinkLabelstringOptional

secondaryLinkUrlstring · uriOptional

qualificationsany ofOptional

statusstring · enumOptionalPossible values:

issuerUserIdinteger · max: 2147483647 · nullableOptional

isLockedbooleanOptional

startDatestringOptional

expirationDatestringOptional

categoryIdintegerOptional

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/{benefitId}

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

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

{
  "id": 1,
  "type": "LIMITED_TIME_CODE",
  "shortDescription": "text",
  "longDescription": "text",
  "logoImageUrl": "https://example.com",
  "carouselImageUrl": "https://example.com",
  "secondaryLinkLabel": "text",
  "secondaryLinkUrl": "https://example.com",
  "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,
    "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
        }
      }
    }
  },
  "isLocked": true,
  "createdAt": "text",
  "updatedAt": "text",
  "qualifications": {
    "scoreThreshold": 1
  },
  "startDate": "text",
  "expirationDate": "text"
}

Delete a benefit

delete

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

benefitIdintegerRequired

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/{benefitId}

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

{
  "id": 1,
  "type": "LIMITED_TIME_CODE",
  "shortDescription": "text",
  "longDescription": "text",
  "logoImageUrl": "https://example.com",
  "carouselImageUrl": "https://example.com",
  "secondaryLinkLabel": "text",
  "secondaryLinkUrl": "https://example.com",
  "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,
    "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
        }
      }
    }
  },
  "isLocked": true,
  "createdAt": "text",
  "updatedAt": "text",
  "qualifications": {
    "scoreThreshold": 1
  },
  "startDate": "text",
  "expirationDate": "text"
}

Get benefit code info

get

Get information about exclusive access codes for a benefit. Returns code availability and the current user's claimed code if logged in.

Path parameters

benefitIdintegerRequired

Responses

200

Successful response

application/json

hasAccessCodesbooleanRequired

totalCodesnumberRequired

claimedCodesnumberRequired

availableCodesnumberRequired

userClaimedCodestring · nullableRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/benefits/{benefitId}/codes/info

GET /api/v2/benefits/{benefitId}/codes/info HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "hasAccessCodes": true,
  "totalCodes": 1,
  "claimedCodes": 1,
  "availableCodes": 1,
  "userClaimedCode": "text"
}

Claim an exclusive access code

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

benefitIdintegerRequired

Responses

200

Successful response

application/json

codestring · nullableRequired

alreadyClaimedbooleanRequired

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/{benefitId}/codes/claim

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

{
  "code": "text",
  "alreadyClaimed": true
}

List exclusive access codes for a benefit

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

benefitIdintegerRequired

Query parameters

filterstring · enumOptionalDefault: allPossible values:

limitinteger · max: 50OptionalDefault: 50

offsetnumberOptionalDefault: 0

Responses

200

Successful response

application/json

totalnumberRequired

limitnumberRequired

offsetnumberRequired

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/{benefitId}/codes

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

{
  "values": [
    {
      "id": 1,
      "code": "text",
      "claimedByProfileId": 1,
      "claimedByUsername": "text",
      "claimedAt": "text",
      "createdAt": "text"
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

Add exclusive access codes to a benefit

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

benefitIdintegerRequired

Body

codesstring[] · min: 1 · max: 10000Required

Responses

200

Successful response

application/json

addednumberRequired

duplicatesSkippednumberRequired

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/{benefitId}/codes

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

{
  "codes": [
    "text"
  ]
}

{
  "added": 1,
  "duplicatesSkipped": 1
}

Delete all unclaimed codes for a benefit

delete

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

benefitIdintegerRequired

Responses

200

Successful response

application/json

deletednumberRequired

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}/codes/unclaimed

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

{
  "deleted": 1
}

PreviousAuctions NextBroker

Last updated 17 hours ago

hashtagList limited-time benefits with pagination and filtering

hashtagList score-based benefits with pagination and filtering

hashtagList all benefits (admin only)

hashtagGet all categories

hashtagCreate a new category

hashtagUpdate a category

hashtagDelete a category

hashtagCreate a new benefit

hashtagUpdate an existing benefit

hashtagDelete a benefit

hashtagGet benefit code info

hashtagClaim an exclusive access code

hashtagList exclusive access codes for a benefit

hashtagAdd exclusive access codes to a benefit

hashtagDelete all unclaimed codes for a benefit

List limited-time benefits with pagination and filtering

List score-based benefits with pagination and filtering

List all benefits (admin only)

Get all categories

Create a new category

Update a category

Delete a category

Create a new benefit

Update an existing benefit

Delete a benefit

Get benefit code info

Claim an exclusive access code

List exclusive access codes for a benefit

Add exclusive access codes to a benefit

Delete all unclaimed codes for a benefit