API Reference

💫 Sparks Reference

Spark paths match the Canvas autocomplete — context from triggers and spells, flow sparks from upstream pieces, library values from Booster Packs.

📐Under the hood — Usage

TypeScript

// Use {{path}} in any string config field on a Piece node.
// Example: "Hello {{input.user.name}}, you have {{score}} points!"
//
// Spell context: input.user.id, input.user.name, input.guild.id, input.options.*
// Event context: varies by trigger — see each event reference page
// Flow sparks: named by upstream pieces ({{result}}, {{score}}, {{item}})

💡Good to know

Wrap paths in {{double curly braces}}. Missing paths resolve to an empty string at runtime.

🪄Context sparks (Spells)

Available in every spell flow from the first node.

Path	Type	When available	Description
`{{input.guild.id}}`	string	Spells	Your Discord server's unique ID
`{{input.guild.name}}`	string	Spells	Your server's name
`{{input.guild.memberCount}}`	string	Spells	How many members are in the server
`{{input.guild.icon}}`	image	Spells	Your server's icon image (empty if it has none)
`{{input.user.id}}`	string	Spells	Who ran the command — Discord ID
`{{input.user.name}}`	string	Spells	Who ran the command — username
`{{input.user.displayName}}`	string	Spells	Who ran the command — their display name
`{{input.channel.id}}`	string	Spells	The channel this command was used in
`{{input.channel.name}}`	string	Spells	The channel's name
`{{input.user.avatar}}`	image	Spells	Who ran the command — avatar image (animated ones stay animated)

⏱️Context sparks (Timers)

Path	Type	When available	Description
`{{input.guild.id}}`	string	Timers	Your Discord server's unique ID
`{{input.guild.name}}`	string	Timers	Your server's name
`{{input.guild.memberCount}}`	string	Timers	How many members are in the server
`{{input.guild.icon}}`	image	Timers	Your server's icon image (empty if it has none)
`{{timestamp}}`	string	Timers	Current time in ISO format
`{{date}}`	string	Timers	Today's date

⚡Context sparks (Triggers)

Paths differ by event type — open a trigger reference for the full list.

🟢 Bot is ready →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Bot is ready	Your Discord server's unique ID
`{{input.guild.name}}`	string	Bot is ready	Your server's name
`{{input.guild.memberCount}}`	string	Bot is ready	How many members are in the server
`{{input.guild.icon}}`	image	Bot is ready	Your server's icon image (empty if it has none)

👋 Member joins →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Member joins	Your Discord server's unique ID
`{{input.guild.name}}`	string	Member joins	Your server's name
`{{input.guild.memberCount}}`	string	Member joins	How many members are in the server
`{{input.guild.icon}}`	image	Member joins	Your server's icon image (empty if it has none)
`{{member.id}}`	string	Member joins	The new member's Discord ID
`{{member.username}}`	string	Member joins	Their Discord username
`{{member.displayName}}`	string	Member joins	Their nickname in this server, or username if none
`{{member.name}}`	string	Member joins	Their username (alias for member.username)
`{{member.joinedAt}}`	string	Member joins	When they joined (ISO timestamp)
`{{member.avatar}}`	image	Member joins	Their avatar — server avatar if they set one

👋 Member leaves →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Member leaves	Your Discord server's unique ID
`{{input.guild.name}}`	string	Member leaves	Your server's name
`{{input.guild.memberCount}}`	string	Member leaves	How many members are in the server
`{{input.guild.icon}}`	image	Member leaves	Your server's icon image (empty if it has none)
`{{member.id}}`	string	Member leaves	The member who left — their Discord ID
`{{member.username}}`	string	Member leaves	Their username
`{{member.displayName}}`	string	Member leaves	Their display name (may be unavailable if uncached)
`{{member.name}}`	string	Member leaves	Their username (alias for member.username)
`{{member.avatar}}`	image	Member leaves	Their avatar — server avatar if they set one

🔨 Member banned →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Member banned	Your Discord server's unique ID
`{{input.guild.name}}`	string	Member banned	Your server's name
`{{input.guild.memberCount}}`	string	Member banned	How many members are in the server
`{{input.guild.icon}}`	image	Member banned	Your server's icon image (empty if it has none)
`{{ban.user.id}}`	string	Member banned	Discord ID of the banned user
`{{ban.user.username}}`	string	Member banned	Username of the banned user
`{{ban.reason}}`	string	Member banned	Reason provided for the ban (may be empty)

🔓 Member unbanned →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Member unbanned	Your Discord server's unique ID
`{{input.guild.name}}`	string	Member unbanned	Your server's name
`{{input.guild.memberCount}}`	string	Member unbanned	How many members are in the server
`{{input.guild.icon}}`	image	Member unbanned	Your server's icon image (empty if it has none)
`{{ban.user.id}}`	string	Member unbanned	Discord ID of the unbanned user
`{{ban.user.username}}`	string	Member unbanned	Username of the unbanned user

💬 Message sent →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Message sent	Your Discord server's unique ID
`{{input.guild.name}}`	string	Message sent	Your server's name
`{{input.guild.memberCount}}`	string	Message sent	How many members are in the server
`{{input.guild.icon}}`	image	Message sent	Your server's icon image (empty if it has none)
`{{message.id}}`	string	Message sent	The message's unique ID
`{{message.content}}`	string	Message sent	The full text of the message
`{{message.channelId}}`	string	Message sent	ID of the channel the message was sent in
`{{message.author.id}}`	string	Message sent	Discord ID of who sent the message
`{{message.author.username}}`	string	Message sent	Sender's Discord username
`{{message.author.displayName}}`	string	Message sent	Sender's display name (or username if they have none)
`{{message.author.name}}`	string	Message sent	Sender's username (alias for message.author.username)
`{{channel.id}}`	string	Message sent	ID of the channel (same as message.channelId)
`{{channel.name}}`	string	Message sent	Name of the channel
`{{message.image}}`	image	Message sent	First image on the message — attachment, embed image or sticker
`{{message.images}}`	array	Message sent	Every image on the message, as a list
`{{message.imageCount}}`	number	Message sent	How many images the message carries
`{{message.attachments}}`	array	Message sent	Every file attached to the message (images or not)
`{{message.author.avatar}}`	image	Message sent	Avatar of whoever sent the message
`{{message.url}}`	string	Message sent	Link that jumps straight to the message
`{{message.replyTo}}`	string	Message sent	ID of the message this one replies to (empty if it isn't a reply)

🗑️ Message deleted →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Message deleted	Your Discord server's unique ID
`{{input.guild.name}}`	string	Message deleted	Your server's name
`{{input.guild.memberCount}}`	string	Message deleted	How many members are in the server
`{{input.guild.icon}}`	image	Message deleted	Your server's icon image (empty if it has none)
`{{message.id}}`	string	Message deleted	The deleted message's ID
`{{message.content}}`	string	Message deleted	The deleted message's text (empty if message was not cached)
`{{message.channelId}}`	string	Message deleted	ID of the channel the message was in
`{{message.author.id}}`	string	Message deleted	Who sent the message (may be empty for uncached messages)
`{{message.author.name}}`	string	Message deleted	Sender's username (may be empty for uncached messages)
`{{channel.id}}`	string	Message deleted	ID of the channel (same as message.channelId)

✏️ Message edited →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Message edited	Your Discord server's unique ID
`{{input.guild.name}}`	string	Message edited	Your server's name
`{{input.guild.memberCount}}`	string	Message edited	How many members are in the server
`{{input.guild.icon}}`	image	Message edited	Your server's icon image (empty if it has none)
`{{oldMessage.content}}`	string	Message edited	The message before the edit (empty if uncached)
`{{newMessage.content}}`	string	Message edited	The message after the edit
`{{message.id}}`	string	Message edited	The message's unique ID
`{{message.author.id}}`	string	Message edited	Discord ID of who sent the message
`{{message.author.name}}`	string	Message edited	Author's username
`{{message.channelId}}`	string	Message edited	ID of the channel
`{{channel.id}}`	string	Message edited	ID of the channel (same as message.channelId)
`{{channel.name}}`	string	Message edited	Name of the channel
`{{message.image}}`	image	Message edited	First image on the edited message — attachment, embed image or sticker
`{{message.images}}`	array	Message edited	Every image on the edited message, as a list
`{{message.imageCount}}`	number	Message edited	How many images the edited message carries
`{{message.attachments}}`	array	Message edited	Every file attached to the edited message (images or not)
`{{message.author.avatar}}`	image	Message edited	Avatar of whoever sent the edited message
`{{message.url}}`	string	Message edited	Link that jumps straight to the edited message

😀 Reaction added →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Reaction added	Your Discord server's unique ID
`{{input.guild.name}}`	string	Reaction added	Your server's name
`{{input.guild.memberCount}}`	string	Reaction added	How many members are in the server
`{{input.guild.icon}}`	image	Reaction added	Your server's icon image (empty if it has none)
`{{reaction.emoji}}`	string	Reaction added	The emoji that was reacted with
`{{reaction.userId}}`	string	Reaction added	Discord ID of who reacted
`{{reaction.messageId}}`	string	Reaction added	ID of the message that was reacted to
`{{reaction.channelId}}`	string	Reaction added	ID of the channel where the reaction happened

😶 Reaction removed →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Reaction removed	Your Discord server's unique ID
`{{input.guild.name}}`	string	Reaction removed	Your server's name
`{{input.guild.memberCount}}`	string	Reaction removed	How many members are in the server
`{{input.guild.icon}}`	image	Reaction removed	Your server's icon image (empty if it has none)
`{{reaction.emoji}}`	string	Reaction removed	The emoji that was removed
`{{reaction.userId}}`	string	Reaction removed	Discord ID of who removed the reaction
`{{reaction.messageId}}`	string	Reaction removed	ID of the message
`{{reaction.channelId}}`	string	Reaction removed	ID of the channel

🎙️ Voice state changes →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Voice state changes	Your Discord server's unique ID
`{{input.guild.name}}`	string	Voice state changes	Your server's name
`{{input.guild.memberCount}}`	string	Voice state changes	How many members are in the server
`{{input.guild.icon}}`	image	Voice state changes	Your server's icon image (empty if it has none)
`{{voice.userId}}`	string	Voice state changes	Discord ID of the user who changed voice state
`{{voice.channelId}}`	string	Voice state changes	Voice channel ID (empty string if they left)
`{{voice.joined}}`	boolean	Voice state changes	True when the user joined a voice channel
`{{voice.left}}`	boolean	Voice state changes	True when the user left a voice channel

⚡ Interaction received →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Interaction received	Your Discord server's unique ID
`{{input.guild.name}}`	string	Interaction received	Your server's name
`{{input.guild.memberCount}}`	string	Interaction received	How many members are in the server
`{{input.guild.icon}}`	image	Interaction received	Your server's icon image (empty if it has none)
`{{interaction.user.id}}`	string	Interaction received	Discord ID of who triggered the interaction
`{{interaction.user.username}}`	string	Interaction received	Username of the person who triggered the interaction
`{{interaction.channelId}}`	string	Interaction received	ID of the channel the interaction came from
`{{interaction.type}}`	string	Interaction received	Interaction type (Button, SelectMenu, ModalSubmit, etc.) — slash commands go to Spells

🔘 Button pressed →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Button pressed	Your Discord server's unique ID
`{{input.guild.name}}`	string	Button pressed	Your server's name
`{{input.guild.memberCount}}`	string	Button pressed	How many members are in the server
`{{input.guild.icon}}`	image	Button pressed	Your server's icon image (empty if it has none)
`{{component.customId}}`	string	Button pressed	The custom id of the button or dropdown that was used
`{{component.args}}`	string	Button pressed	Anything after the colon in the custom id — how you carry data through a click
`{{component.user.id}}`	string	Button pressed	Discord ID of whoever clicked
`{{component.user.username}}`	string	Button pressed	Username of whoever clicked
`{{component.messageId}}`	string	Button pressed	ID of the message the button is on
`{{component.channelId}}`	string	Button pressed	ID of the channel the message is in

🔽 Dropdown chosen →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Dropdown chosen	Your Discord server's unique ID
`{{input.guild.name}}`	string	Dropdown chosen	Your server's name
`{{input.guild.memberCount}}`	string	Dropdown chosen	How many members are in the server
`{{input.guild.icon}}`	image	Dropdown chosen	Your server's icon image (empty if it has none)
`{{component.customId}}`	string	Dropdown chosen	The custom id of the button or dropdown that was used
`{{component.args}}`	string	Dropdown chosen	Anything after the colon in the custom id — how you carry data through a click
`{{component.user.id}}`	string	Dropdown chosen	Discord ID of whoever clicked
`{{component.user.username}}`	string	Dropdown chosen	Username of whoever clicked
`{{component.messageId}}`	string	Dropdown chosen	ID of the message the button is on
`{{component.channelId}}`	string	Dropdown chosen	ID of the channel the message is in
`{{component.value}}`	string	Dropdown chosen	The chosen value — the bit before the \| on that line of your dropdown
`{{component.values}}`	array	Dropdown chosen	Every chosen value, when the dropdown allows more than one

🪟 Form submitted →

Path	Type	When available	Description
`{{input.guild.id}}`	string	Form submitted	Your Discord server's unique ID
`{{input.guild.name}}`	string	Form submitted	Your server's name
`{{input.guild.memberCount}}`	string	Form submitted	How many members are in the server
`{{input.guild.icon}}`	image	Form submitted	Your server's icon image (empty if it has none)
`{{form.customId}}`	string	Form submitted	Custom id of the form that was submitted
`{{form.args}}`	string	Form submitted	Anything after the colon in the form's custom id
`{{component.user.id}}`	string	Form submitted	Discord ID of whoever submitted the form
`{{component.user.username}}`	string	Form submitted	Username of whoever submitted the form
`{{component.channelId}}`	string	Form submitted	Channel the form was opened from

📥Option spark shapes (by Discord type)

Discord type	type int	Sub-paths
STRING	3	—
INTEGER	4	—
BOOLEAN	5	—
NUMBER	10	—
USER	6	.id .username .displayName
CHANNEL	7	.id .name
ROLE	8	.id .name

📝Flow sparks (from Pieces)

Downstream pieces expose sparks by the name you configure (as / name fields).

Path	Type	When available	Description
`{{<name>}}`	varies	After Save Spark (base.variable)	Named spark you set — use {{score}}, not vars.score
`{{<as>}}`	array	After Read from Vault (base.db.read)	All matching rows — e.g. {{result}}
`{{<as>.length}}`	number	After Read from Vault	Number of rows returned
`{{<as>.0.<column>}}`	varies	After Read from Vault	First row column — e.g. {{result.0.coins}}
`{{<as>}}`	varies	After Loop (each port)	Current loop item — name from “Call each item” field
`{{<as>}}`	string \| number	After Random Pick, Math, Format, text/list utilities	Result spark named in the piece config

See each Piece reference for the exact sparks it adds.

🎴Library sparks (Packs)

Path	Type	When available	Description
`{{lib.filter.profanity}}`	array	The Naughty List	Array of common profanity and strong language
`{{lib.filter.slurs}}`	array	The Naughty List	Array of racial, ethnic, and identity-based slurs
`{{lib.filter.spam_phrases}}`	array	The Naughty List	Array of common spam and scam phrases
`{{lib.filter.discord_invite}}`	string (regex)	The Naughty List	Regex — detects Discord invite links (discord.gg/...)
`{{lib.filter.external_links}}`	string (regex)	The Naughty List	Regex — detects any http or https URL
`{{lib.filter.excessive_caps}}`	string (regex)	The Naughty List	Regex — detects 4+ consecutive uppercase characters (SHOUTING)
`{{lib.validate.email}}`	string (regex)	The Pattern Lab	Regex — validates email address format (user@domain.tld)
`{{lib.validate.url}}`	string (regex)	The Pattern Lab	Regex — validates http/https URLs
`{{lib.validate.phone}}`	string (regex)	The Pattern Lab	Regex — validates international phone numbers (E.164 style, optional +)
`{{lib.validate.discord_id}}`	string (regex)	The Pattern Lab	Regex — validates Discord snowflake IDs (17–20 digit numbers)
`{{lib.validate.discord_invite}}`	string (regex)	The Pattern Lab	Regex — validates a Discord invite link or code
`{{lib.validate.hex_color}}`	string (regex)	The Pattern Lab	Regex — validates hex color codes (#RGB or #RRGGBB)
`{{lib.validate.ip_address}}`	string (regex)	The Pattern Lab	Regex — validates IPv4 addresses (0.0.0.0 – 255.255.255.255)
`{{lib.validate.number_only}}`	string (regex)	The Pattern Lab	Regex — validates that a string contains only digits (0–9)
`{{lib.fun.eight_ball}}`	array	The Party Pack	The 20 classic Magic 8-Ball answers
`{{lib.fun.jokes}}`	array	The Party Pack	30 clean one-liners and dad jokes
`{{lib.fun.compliments}}`	array	The Party Pack	25 wholesome compliments
`{{lib.fun.roasts}}`	array	The Party Pack	20 gentle, friendly roasts
`{{lib.fun.would_you_rather}}`	array	The Party Pack	25 "Would you rather…" questions
`{{lib.fun.truths}}`	array	The Party Pack	20 truth questions for truth or dare
`{{lib.fun.dares}}`	array	The Party Pack	20 dares you can actually do in Discord
`{{lib.fun.fortunes}}`	array	The Party Pack	20 fortune-cookie fortunes
`{{lib.fun.icebreakers}}`	array	The Party Pack	25 conversation starters — great for a question of the day

Packs docs →

Kit Schema Reference →Sparks guide →