Skip to main content

Engagerly API

Overview​

The Engagerly API allows developers to extend community experiences beyond Discord. By integrating with external platforms, you can reward members with points or assign roles when they complete actions outside Discord — helping you build a more engaging and dynamic ecosystem.

Whether it's a website check-in, form submission, blockchain interaction, or any external activity, this API helps you bring the results back into your Discord server in the form of tangible recognition.

What Do You Need to Get Started?​

Before using the API, make sure you meet the following requirements:

  • Engagerly Bot has been added to your Discord server
  • Your server is on the Ultimate Plan
  • You have admin privileges or permission to use the API features

Create Your API Key​

To generate your personal API key, use the following slash command in your Discord server:

/api-key create

This API key will authenticate your requests. Please keep it secure and do not share it publicly.

Available API Endpoints​

1️⃣ Award Points​

Grants a specific amount of points to a member in your Discord server.

Endpoint​

POST https://api.engagerly.bot/1/points/award

Parameters​

NameTypeRequiredDescription
x-api-keyHeader✔️Your Engagerly API Key
user_idBody✔️Discord User ID
pointsBody✔️Number of points to award (integer)
remarkBody✔️Description of the reason or event

Example Request​

curl -X 'POST' \
  'https://api.engagerly.bot/1/points/award' \
  -H 'accept: application/json' \
  -H 'x-api-key: <Engagerly API Key>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'user_id=<Discord User ID>&points=<Points Amount>&remark=<Reason for Award>'

Success Response​

{
  "code": 0,
  "error": "",
  "data": {
    "user_id": "<Discord User ID>",
    "points": <Points>,
    "remark": "<Reason>"
  },
  "ts": 1753325944
}

2️⃣ Assign Role​

Assigns a role (Discord Role ID) to a member in your server.

Endpoint​

POST https://api.engagerly.bot/1/role/assign

Parameters​

NameTypeRequiredDescription
x-api-keyHeader✔️Your Engagerly API Key
user_idBody✔️Discord User ID
role_idBody✔️Discord Role ID (from your server)
remarkBody✔️Description of the context or reason

Example Request​

curl -X 'POST' \
  'https://api.engagerly.bot/1/role/assign' \
  -H 'accept: application/json' \
  -H 'x-api-key: <Engagerly API Key>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'user_id=<Discord User ID>&role_id=<Discord Role ID>&remark=<Reason for Assignment>'

Success Response​

{
  "code": 0,
  "error": "",
  "data": {
    "user_id": "<Discord User ID>",
    "role_id": "<Discord Role ID>",
    "remark": "<Reason>"
  },
  "ts": 1753325944
}

Security & Permissions​

  • Each API key is scoped to a specific server and cannot be used across multiple servers.
  • Every request must include the x-api-key header for authentication.
  • Never expose your API key publicly or commit it to version control.
  • If needed, revoke and regenerate your API key using /api-key revoke.

FAQ​

  • Q: Is there a rate limit for API usage?

    A: There is currently no enforced rate limit, but excessive usage may be throttled at Engagerly's discretion.

  • Q: How do I find the Discord user ID or role ID?

    A: Enable Developer Mode in Discord, then right-click a user or role to copy their ID.

Need help or want to explore more use cases?​

Join our 💬 Official Engagerly Support Server to chat with the team and the community.