Docs — BdfdAPI

Every endpoint returns JSON (or the relevant binary type) and is accessible over HTTPS from https://bdfdapi.xyz. There are no API keys required — all endpoints are open and free to use.

The API is designed to slot directly into any BDFD bot with a single HTTP request. Welcome cards, transcripts, leaderboards, quotes — all in one place.

⚠️

/api/transcript requires a Bot Token The transcript endpoint needs your Discord bot token to fetch messages. It is used only for that request and is never stored or logged.

🔒

End-to-end encrypted All API traffic is encrypted in transit via HTTPS/TLS. Transcript data is stored temporarily and never sold or shared.

Getting Started

All requests go to the base URL:

Base URL
https://bdfdapi.xyz

Most endpoints are GET requests with query parameters. The transcript endpoint is a POST with a JSON body. Rate limits apply only to the transcript endpoint (1 req / 5 s per IP and per Discord guild).

In BDFD, use $httpPost[] for the transcript endpoint and $httpGet[] or $image[] for all others. Image endpoints must use $image[] — they return binary PNG, not JSON.

Changelog

v1.1 — June 2025

Added /api/welcome — customizable 1000×300 PNG welcome card generator
Welcome endpoint supports background image or color, avatar, member count, server name, and per-element color control
Background image support with overlay color and opacity
Added /api/leaderboard and /api/rank endpoints with full theme, badge, and XP support

v1.0 — June 2025

Initial public release of BdfdAPI
Transcript endpoint with full embed customization and placeholder support
Image generation via canvas (1200×400 PNG)
Anime GIF proxy (hug, kiss, pat)
Quote endpoint with 50+ quotes across 5 categories
Bible verse endpoint with mood/book/length filters
DuckDuckGo search proxy

Your Safety

We take data seriously. Here's exactly what we store and what we don't:

Bot tokens — used in memory only to fetch Discord messages. Never logged, never stored.
Transcripts — stored temporarily in Vercel KV for retrieval via /api/t/[id]. Not mined or sold.
Rate limit keys — IP and guild IDs stored for 5-second TTL windows only.
Analytics — we do not run user tracking or third-party analytics scripts.

All traffic is encrypted in transit via HTTPS/TLS. We do not sell, share, or monetize any data passed through the API.

ℹ️

Questions about your data? Reach us on Discord at @Cenzo.org or join the support server.

POST /api/transcript

Fetches all messages from a Discord channel, builds a styled HTML transcript, stores it, and delivers it — as a Discord embed to a transcript channel, and optionally as a DM to the ticket creator.

⚠️

Bot Token required Pass your Discord bot token in the JSON body as botToken. Used only to fetch channel messages — never stored.

POST https://bdfdapi.xyz/api/transcript

Required

Parameter	Type	Description
botToken	string	Your Discord bot token. Used only to fetch channel data — never stored.
channelId	string	The ID of the ticket channel to transcribe.

Optional

Parameter	Type	Default	Description
transcriptChannelId	string	—	Channel to send the transcript embed to.
ticketCreatorId	string	—	User ID of the ticket opener. Used to DM transcript.
ticketCloserId	string	—	User ID of who closed the ticket.
ticketId	string	—	Ticket identifier shown in the embed and transcript header.
ticketType	string	"Support"	Category label (e.g. "Bug Report", "Purchase").
claimedBy	string	—	User ID of the staff member who claimed the ticket.
embedTitle	string	"Ticket Transcript"	Title of the Discord embed.
embedDescription	string	—	Custom embed description. Supports placeholders.
embedColor	string	"#5865F2"	Hex color for the embed border.
embedFooter	string	Guild name	Footer text. Supports placeholders.
embedTimestamp	boolean	true	Whether to show a timestamp on the embed.
timezone	string	"UTC"	IANA timezone for message timestamps.
watermark	string	—	Text displayed at the bottom of the transcript HTML.

Embed Placeholders

Placeholder	Replaced with
{ticketOpener}	Mention of the ticket creator
{ticketCloser}	Mention of the closer
{ticketID}	The ticketId value
{channelName}	Name of the ticket channel
{serverName}	Name of the Discord server
{messageCount}	Total number of messages
{closedAt}	Discord timestamp (full date)
{closedAtR}	Discord timestamp (relative)

BDFD Examples

BDFD · Basic

$httpPost[
https://bdfdapi.xyz/api/transcript;
{
  "botToken":"YOUR_BOT_TOKEN",
  "channelId":"$channelID",
  "transcriptChannelId":"LOG_CHANNEL_ID"
}
]

BDFD · Ticket transcript

$httpPost[
https://bdfdapi.xyz/api/transcript;
{
  "botToken":"YOUR_BOT_TOKEN",
  "channelId":"$channelID",
  "transcriptChannelId":"LOG_CHANNEL_ID",
  "ticketId":"ticket-001",
  "ticketCreatorId":"$authorID",
  "ticketCloserId":"$authorID"
}
]

BDFD · Custom embed

$httpPost[
https://bdfdapi.xyz/api/transcript;
{
  "botToken":"YOUR_BOT_TOKEN",
  "channelId":"$channelID",
  "transcriptChannelId":"LOG_CHANNEL_ID",
  "embedTitle":"Support Ticket",
  "embedDescription":"Thanks for contacting our support team!",
  "embedColor":"#5865F2"
}
]

Responses

{
  "success": true,
  "transcriptId": "a1b2c3d4-...",
  "link": "https://bdfdapi.xyz/api/t/a1b2c3d4-..."
}

{ "error": "Missing required field: channelId" }

{ "error": "You have been rate limited. Please try again after 3 seconds." }

GET /api/welcome

Generates a 1000×300 PNG welcome card with a circular avatar, username, member count, server name, and fully customizable colors. Designed to drop straight into a BDFD on_join command with $image[].

ℹ️

Use $image[], not $httpGet[] This endpoint returns a binary PNG. In BDFD, use $image[URL] to embed it — $httpGet returns raw bytes.

GET https://bdfdapi.xyz/api/welcome

Content

Parameter	Type	Default	Description
username	string	"Username"	Display name. Max 22 chars — font scales down automatically.
avatar	url	—	Discord CDN avatar URL from `$authorAvatar`.
memberCount	number	—	Shows `Member #N` below the username.
serverName	string	—	Server name. Max 40 chars.
message	string	"Welcome!"	Top welcome line. Max 60 chars.

Background & Colors

Parameter	Type	Default	Description
bg	hex or url	2f3136	Background hex (no #) or full image URL.
accent	hex	5865f2	Primary accent — avatar ring, welcome message, member count.
textColor	hex	ffffff	Username text color.
borderSize	number	4	Avatar ring thickness (0–10).
overlayOpacity	number	50	Overlay darkness (0–100) when bg is an image URL.

GET /api/leaderboard

Generates a leaderboard image for your Discord server. Pass user data as query parameters and get back a styled PNG card. Supports up to 10 users, badges, XP bars, levels, and a dark/light theme toggle.

GET https://bdfdapi.xyz/api/leaderboard

Parameters

Parameter	Type	Description
title	string	Leaderboard title (e.g. "Global Leaderboard").
userN	string	Username for slot N (e.g. `user1`, `user2` … `user10`).
xpN	number	XP value for slot N.
levelN	number	Level for slot N.
avatarN	url	Avatar image URL for slot N.
showBadges	boolean	Show rank badges (gold/silver/bronze) for top 3.
showLevels	boolean	Show level numbers on each row.
showXP	boolean	Show XP values on each row.
theme	string	`dark` or `light`.

BDFD Examples

BDFD · Basic

$image[https://bdfdapi.xyz/api/leaderboard?title=Leaderboard&user1=Alice&xp1=1250&level1=12&avatar1=https://cdn.discordapp.com/embed/avatars/0.png]

BDFD · Advanced (multi-user)

$image[https://bdfdapi.xyz/api/leaderboard?title=Global%20Leaderboard&user1=Alice&xp1=15420&level1=45&avatar1=https://cdn.discordapp.com/embed/avatars/0.png&user2=Bob&xp2=14980&level2=44&avatar2=https://cdn.discordapp.com/embed/avatars/1.png&user3=Charlie&xp3=14350&level3=43&avatar3=https://cdn.discordapp.com/embed/avatars/2.png&user4=David&xp4=13990&level4=42&avatar4=https://cdn.discordapp.com/embed/avatars/3.png&showBadges=true&showLevels=true&showXP=true&theme=dark]

GET /api/rank

Generates a rank card image showing a user's XP, level, server position, coins, bank balance, and online status. Returns a PNG ready to embed with $image[].

GET https://bdfdapi.xyz/api/rank

Parameters

Parameter	Type	Description
username	string	The user's display name.
avatar	url	Avatar URL — use `$authorAvatar` in BDFD.
level	number	Current level.
xp	number	Total XP accumulated.
rank	number	Server rank position (e.g. `1` for #1).
currentXP	number	XP earned toward current level (for progress bar).
requiredXP	number	XP required to reach next level.
coins	number	User's coin balance.
bank	number	User's bank balance.
status	string	`online`, `idle`, `dnd`, or `offline`.
background	url	Optional background image URL.

BDFD Examples

BDFD · Basic

$image[https://bdfdapi.xyz/api/rank?username=$username&avatar=$authorAvatar&level=12&xp=1250&rank=5]

BDFD · Advanced (full card)

$image[https://bdfdapi.xyz/api/rank?username=$username&avatar=$authorAvatar&level=42&xp=98765&rank=1¤tXP=2765&requiredXP=5000&coins=15420&bank=98450&status=online&background=https://images.unsplash.com/photo-1506744038136-46273834b3fb]

GET /api/quote

Returns random quotes from a curated library of 50+ quotes across 5 categories. Filter by category or author, return up to 10 at once.

GET https://bdfdapi.xyz/api/quote

Parameter	Type	Default	Description
category	string	any	`motivational`, `wisdom`, `funny`, `love`, `success`
author	string	any	Partial author name filter, case-insensitive.
limit	number	1	Number of quotes to return (max 10).

BDFD Example

BDFD

$nomention
$httpGet[https://bdfdapi.xyz/api/quote]

$description[
**$httpResult[quotes;0;text]**
— $httpResult[quotes;0;author]
]

200Success

{ "count": 1, "quotes": [ { "text": "Age is of no importance unless you're a cheese.", "author": "Billie Burke", "category": "funny" } ] }

GET /api/t/[id]

Serves a stored transcript HTML page. The id is returned by /api/transcript in the transcriptId field. Share this URL with users so they can view the transcript in any browser — no login required.

GET https://bdfdapi.xyz/api/t/[id]

Returns the full HTML transcript page. No parameters required — the UUID is the only identifier. The link is included in the 200 response from /api/transcript.

BDFD Examples

Complete, copy-paste ready examples for every endpoint. Replace placeholder IDs and tokens with your own values.

Welcome Card — on_join

BDFD · Basic

$nomention
$image[https://bdfdapi.xyz/api/welcome?username=$username&memberCount=$membersCount&serverName=$serverName[$guildID]&avatar=$authorAvatar]

BDFD · Custom colors

$nomention
$image[https://bdfdapi.xyz/api/welcome?username=$username&memberCount=$membersCount&serverName=$serverName[$guildID]&avatar=$authorAvatar&accent=00e5ff&textColor=ffffff&bg=111213&borderSize=5]

Ticket Transcript

BDFD · Basic

$httpPost[
https://bdfdapi.xyz/api/transcript;
{
  "botToken":"YOUR_BOT_TOKEN",
  "channelId":"$channelID",
  "transcriptChannelId":"LOG_CHANNEL_ID"
}
]

BDFD · Full ticket with IDs

$httpPost[
https://bdfdapi.xyz/api/transcript;
{
  "botToken":"YOUR_BOT_TOKEN",
  "channelId":"$channelID",
  "transcriptChannelId":"LOG_CHANNEL_ID",
  "ticketId":"ticket-001",
  "ticketCreatorId":"$authorID",
  "ticketCloserId":"$authorID"
}
]

BDFD · Custom embed

$httpPost[
https://bdfdapi.xyz/api/transcript;
{
  "botToken":"YOUR_BOT_TOKEN",
  "channelId":"$channelID",
  "transcriptChannelId":"LOG_CHANNEL_ID",
  "embedTitle":"Support Ticket",
  "embedDescription":"Thanks for contacting our support team!",
  "embedColor":"#5865F2"
}
]

Quote Command

BDFD

$nomention
$httpGet[https://bdfdapi.xyz/api/quote]

$description[
**$httpResult[quotes;0;text]**
— $httpResult[quotes;0;author]
]

Rank Card

BDFD · Basic

$image[https://bdfdapi.xyz/api/rank?username=$username&avatar=$authorAvatar&level=12&xp=1250&rank=5]

BDFD · Advanced

$image[https://bdfdapi.xyz/api/rank?username=$username&avatar=$authorAvatar&level=42&xp=98765&rank=1¤tXP=2765&requiredXP=5000&coins=15420&bank=98450&status=online&background=https://images.unsplash.com/photo-1506744038136-46273834b3fb]

Leaderboard

BDFD · Basic

$image[https://bdfdapi.xyz/api/leaderboard?title=Leaderboard&user1=Alice&xp1=1250&level1=12&avatar1=https://cdn.discordapp.com/embed/avatars/0.png]

BDFD · Advanced (multi-user)

$image[https://bdfdapi.xyz/api/leaderboard?title=Global%20Leaderboard&user1=Alice&xp1=15420&level1=45&avatar1=https://cdn.discordapp.com/embed/avatars/0.png&user2=Bob&xp2=14980&level2=44&avatar2=https://cdn.discordapp.com/embed/avatars/1.png&user3=Charlie&xp3=14350&level3=43&avatar3=https://cdn.discordapp.com/embed/avatars/2.png&user4=David&xp4=13990&level4=42&avatar4=https://cdn.discordapp.com/embed/avatars/3.png&showBadges=true&showLevels=true&showXP=true&theme=dark]

Parameters

All query parameters are passed as URL-encoded strings. A few rules:

String parameters are UTF-8 and URL-escaped automatically by most HTTP clients. Spaces become %20.
Hex colors should be passed without the # symbol (e.g. accent=00e5ff).
Number parameters accept integers only unless explicitly noted.
URL parameters (like avatar and bg) must be fully qualified with https://.
POST body parameters (transcript) must be sent as Content-Type: application/json.
In BDFD, image endpoints must use $image[] — not $httpGet[].

Rate Limits

Rate limits are only enforced on the /api/transcript endpoint. All other endpoints are currently unlimited.

Scope	Limit	Window	Applies to
IP address	1 request	5 seconds	/api/transcript
Discord guild	1 request	5 seconds	/api/transcript

429 Rate limited

{ "error": "You have been rate limited. Please try again after 3 seconds." }

Error Codes

All errors return a JSON body with an error key describing the issue.

Status	Meaning
400	Bad request — a required parameter is missing or invalid.
429	Rate limited — wait before retrying.
500	Server error — something went wrong on our end. Try again shortly.

⚠️

403 from Discord If the transcript endpoint returns a 403-related error, your bot token may be invalid, or the bot may not have access to the channel.

FAQ

Yes — all endpoints are free, open, and require no API key or account.

Your bot token is used only to fetch Discord channel messages for the transcript, then discarded. It is never logged, stored, or transmitted beyond that single request.

Yes. Any bot that can make HTTP requests works — Discord.js, discord.py, BDFD, and others. The API is framework-agnostic.

Image endpoints (/api/welcome, /api/rank, /api/leaderboard) return a raw PNG binary. $httpGet[] in BDFD returns the raw response as text, which won't render as an image. Use $image[URL] to embed the PNG directly in your message.

Transcripts are stored in KV storage under a random UUID. There is no hard expiry set currently, but old transcripts may be pruned periodically. Do not rely on them for permanent archival.

Join the Discord support server and open a ticket. You can also reach Cenzo directly at @Cenzo.org.

Introduction

Getting Started

Changelog

Your Safety

POST /api/transcript

Embed Placeholders

BDFD Examples

Responses

GET /api/welcome

GET /api/leaderboard

BDFD Examples

GET /api/rank

BDFD Examples

GET /api/quote

BDFD Example

GET /api/t/[id]

BDFD Examples

Welcome Card — on_join

Ticket Transcript

Quote Command

Rank Card

Leaderboard

Parameters

Rate Limits

Error Codes

FAQ