Embeddy API Documentation

Overview

The Embeddy Bot provides a RESTful API for managing Discord server embeds, variables, and bot operations. All endpoints require authentication via JWT tokens obtained through Discord OAuth2.

ℹ️

Base URL

All API requests should be made to: https://embeddy.xyz/api-proxy.php?path=/api

Authentication

All API requests require a valid JWT token in the X-API-Token header.

GET /api/guilds

Get all guilds (servers) where the user has admin permissions and the bot is present.

Headers

X-API-Token: <your_jwt_token>

Response

[
  {
    "id": "123456789012345678",
    "name": "Server Name",
    "icon": "https://cdn.discordapp.com/icons/123456789012345678/abc123.png",
    "permissions": 8
  }
]

POST /api/auth/callback

Exchange Discord OAuth2 code for JWT token.

Request Body

{
  "code": "discord_oauth2_code"
}

Response

{
  "access_token": "jwt_token_here",
  "token_type": "bearer",
  "expires_in": 3600
}

Channel Management

GET /api/guilds/{guild_id}/emojis

Get all custom emojis for a guild. Used by the web dashboard for emoji selection in role buttons.

Parameters

guild_id

string

Discord guild ID

Response

[
  {
    "id": "123456789012345678",
    "name": "custom_emoji",
    "animated": false,
    "url": "https://cdn.discordapp.com/emojis/123456789012345678.png",
    "formatted": "<:custom_emoji:123456789012345678>"
  },
  {
    "id": "987654321098765432",
    "name": "animated_emoji",
    "animated": true,
    "url": "https://cdn.discordapp.com/emojis/987654321098765432.gif",
    "formatted": ""
  }
]

GET /api/guilds/{guild_id}/channels

Get all text channels in a guild where the bot can send messages.

Parameters

guild_id

string

Discord guild ID

Response

[
  {
    "id": "123456789012345678",
    "name": "general",
    "type": 0,
    "position": 0
  }
]

Embed Management

GET /api/guilds/{guild_id}/channels/{channel_id}/embeds

Get all embeds in a specific channel. Now includes advanced features like sticky settings and role buttons.

Parameters

guild_id

string

Discord guild ID

channel_id

string

Discord channel ID

Response

{
  "embeds": [
    {
      "embed_id": 1,
      "title": "Welcome Message",
      "description": "Welcome to our server!",
      "color": "#5865f2",
      "author": "Embeddy Bot",
      "footer": "Server Rules",
      "sticky": {
        "interval": 0,
        "randomize_ids": []
      },
      "roles": [
        {
          "idx": 0,
          "title": "Member",
          "emote": "👋",
          "color": "success",
          "role_id": "123456789"
        }
      ],

    }
  ]
}

POST /api/guilds/{guild_id}/channels/{channel_id}/embeds

Create a new embed in a specific channel.

Request Body

{
  "title": "New Embed",
  "description": "This is a new embed",
  "color": "#5865f2",
  "author": "Bot Name",
  "footer": "Footer Text"
}

Response

{
  "embed_id": 123,
  "message": "Embed created successfully"
}

PUT /api/guilds/{guild_id}/channels/{channel_id}/embeds/{embed_id}

Update an existing embed.

Parameters

embed_id

integer

Embed ID to update

Request Body

{
  "title": "Updated Title",
  "description": "Updated description"
}

DELETE /api/guilds/{guild_id}/channels/{channel_id}/embeds/{embed_id}

Delete an embed from a channel.

Parameters

embed_id

integer

Embed ID to delete

Response

{
  "message": "Embed deleted successfully"
}

POST /api/guilds/{guild_id}/channels/{channel_id}/embeds/{embed_id}/send

Send an embed to a Discord channel.

Parameters

embed_id

integer

Embed ID to send

Response

{
  "message": "Embed sent successfully",
  "message_id": "123456789012345678"
}

Advanced Embed Features

🚀

New Features

The web dashboard now supports full management of sticky embeds and role buttons. All advanced features are preserved when editing through the web interface.

POST /api/guilds/{guild_id}/channels/{channel_id}/embeds

Create a new embed with advanced features support.

Request Body (Advanced)

{
  "embed": {
    "title": "New Embed",
    "description": "This is a new embed",
    "color": "#5865f2",
    "author": "Bot Name",
    "footer": "Footer Text"
  },
  "sticky": {
    "interval": 0,
    "randomize_ids": []
  },
  "roles": [
    {
      "idx": 0,
      "title": "Member",
      "emote": "👋",
      "color": "success",
      "role_id": "123456789"
    }
  ],
  
}

Advanced Features

sticky

object

Sticky embed settings (interval in seconds, 0 = always sticky)

roles

array

Role button configurations with labels, emojis, colors, and role assignments

PUT /api/guilds/{guild_id}/channels/{channel_id}/embeds/{embed_id}

Update an existing embed with full advanced features support.

Request Body

{
  "embed": {
    "title": "Updated Title",
    "description": "Updated description"
  },
  "sticky": {
    "interval": 300,
    "randomize_ids": []
  },
  "roles": [
    {
      "idx": 0,
      "title": "VIP Member",
      "emote": "⭐",
      "color": "warning",
      "role_id": "123456789"
    }
  ]
}

Notes

All advanced features are preserved when updating
Custom Discord emojis are supported in <:name:id> format
Animated emojis are supported in <a:name:id> format
Role buttons support success, danger, primary, and secondary colors
Sticky embeds can be set to specific intervals or always sticky (0)

Variable Management

GET /api/guilds/{guild_id}/variables

Get custom variables for a guild.

Response

{
  "variables": {
    "welcome_message": "Welcome to our server!",
    "rules": "Follow the rules!"
  }
}

POST /api/guilds/{guild_id}/variables

Set a custom variable for a guild.

Request Body

{
  "name": "welcome_message",
  "value": "Welcome to our amazing server!"
}

SDK Examples

JS

JavaScript SDK

JavaScript

Node.js

// JavaScript SDK for Embeddy Bot API
class EmbeddyAPI {
  constructor(baseUrl, token) {
    this.baseUrl = baseUrl;
    this.token = token;
  }

  async request(endpoint, options = {}) {
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        'X-API-Token': this.token,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
    
    if (!response.ok) {
      throw new Error(`API Error: ${response.status}`);
    }
    
    return response.json();
  }

  async getGuilds() {
    return this.request('/guilds');
  }

  async getChannels(guildId) {
    return this.request(`/guilds/${guildId}/channels`);
  }

  async getEmbeds(guildId, channelId) {
    return this.request(`/guilds/${guildId}/channels/${channelId}/embeds`);
  }

  async createEmbed(guildId, channelId, embedData) {
    return this.request(`/guilds/${guildId}/channels/${channelId}/embeds`, {
      method: 'POST',
      body: JSON.stringify(embedData)
    });
  }
}

// Usage
const api = new EmbeddyAPI('https://embeddy.xyz/api-proxy.php?path=/api', 'your_jwt_token');
const guilds = await api.getGuilds();
            

// Node.js SDK for Embeddy Bot API
const axios = require('axios');

class EmbeddyAPI {
  constructor(baseUrl, token) {
    this.client = axios.create({
      baseURL: baseUrl,
      headers: {
        'X-API-Token': token,
        'Content-Type': 'application/json'
      }
    });
  }

  async getGuilds() {
    const response = await this.client.get('/guilds');
    return response.data;
  }

  async getChannels(guildId) {
    const response = await this.client.get(`/guilds/${guildId}/channels`);
    return response.data;
  }

  async getEmbeds(guildId, channelId) {
    const response = await this.client.get(`/guilds/${guildId}/channels/${channelId}/embeds`);
    return response.data;
  }

  async createEmbed(guildId, channelId, embedData) {
    const response = await this.client.post(`/guilds/${guildId}/channels/${channelId}/embeds`, embedData);
    return response.data;
  }
}

// Usage
const api = new EmbeddyAPI('https://embeddy.xyz/api-proxy.php?path=/api', 'your_jwt_token');
const guilds = await api.getGuilds();
            

PY

Python SDK

# Python SDK for Embeddy Bot API
import requests

class EmbeddyAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.token = token
        self.headers = {
            'X-API-Token': token,
            'Content-Type': 'application/json'
        }
    
    def request(self, method, endpoint, data=None):
        url = f"{self.base_url}{endpoint}"
        response = requests.request(method, url, headers=self.headers, json=data)
        response.raise_for_status()
        return response.json()
    
    def get_guilds(self):
        return self.request('GET', '/guilds')
    
    def get_channels(self, guild_id):
        return self.request('GET', f'/guilds/{guild_id}/channels')
    
    def get_embeds(self, guild_id, channel_id):
        return self.request('GET', f'/guilds/{guild_id}/channels/{channel_id}/embeds')
    
    def create_embed(self, guild_id, channel_id, embed_data):
        return self.request('POST', f'/guilds/{guild_id}/channels/{channel_id}/embeds', embed_data)

# Usage
api = EmbeddyAPI('https://embeddy.xyz/api-proxy.php?path=/api', 'your_jwt_token')
guilds = api.get_guilds()

Rate Limiting & Best Practices

⚡

Rate Limiting

The API implements rate limiting to ensure fair usage. Please implement appropriate delays between requests and handle rate limit responses gracefully.

🔒

Security

Keep your JWT tokens secure and never expose them in client-side code. Tokens expire after 1 hour and should be refreshed through the OAuth2 flow.

📱

Error Handling

Always check response status codes and implement proper error handling. The API returns appropriate HTTP status codes and error messages for failed requests.