YAGPDB

https://help.yagpdb.xyz/docs/
Admin
YAGPDB is a general-purpose Discord bot with moderation tools, custom commands, automoderator,...
Tokens:79,745
Snippets:928
Trust Score:9.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Database Key-Value Store Example

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

This example demonstrates basic database operations including setting a value, getting a value, and deleting entries using keys. It also shows how to use patterns for retrieval and deletion.

```gohtml
dbSet "myKey" "myValue"
{{dbGet "myKey"}}
{{dbDel "myKey"}}
```

--------------------------------

### Modal Creation Example

Source: https://help.yagpdb.xyz/docs/reference/custom-interactions

Example demonstrating how to create and send a modal with multiple input fields.

```APIDOC
```
{{ $modal := sdict
  "title" "My Custom Modal"
  "custom_id" "modals-my_first_modal"
  "fields" (cslice
    (sdict "label" "Name" "placeholder" "Duck" "required" true)
    (sdict "label" "Do you like ducks?" "value" "Heck no")
    (sdict "label" "Duck hate essay" "min_length" 100 "style" 2))
}}
{{ sendModal $modal }}
```
```

--------------------------------

### Stop Setup

Source: https://help.yagpdb.xyz/docs/core/all-commands

Force cancels the current setup session in the channel.

```APIDOC
## StopSetup

### Description
Force cancels the current setup session in this channel.

### Usage
StopSetup

### Aliases
- cancelsetup
```

--------------------------------

### Channel Select Menu Example

Source: https://help.yagpdb.xyz/docs/reference/custom-interactions

Example of creating a channel select menu that allows selecting up to three channels, restricted to forum and announcement types.

```APIDOC
```
{{ $issuesChannel := "1210135699135926312" }}
{{ $updatesChannel := "1210135938722693151" }}

{{ $menu := cmenu
  "type" "channel"
  "placeholder" "Choose channels which are secretly duck hideouts"
  "custom_id" "menus-duck-channels"
  "default_values" (cslice
    (sdict "type" "channel" "id" $issuesChannel)
    (sdict "type" "channel" "id" $updatesChannel)
  )
  "max_values" 3
  "channel_types" (cslice 5 15) }}

{{ sendMessage nil (complexMessage "menus" $menu) }}
```
```

--------------------------------

### Text Select Menu Example

Source: https://help.yagpdb.xyz/docs/reference/custom-interactions

Example of creating a text select menu with three options, one of which is selected by default.

```APIDOC
```
{{ $menu := cmenu
  "type" "text"
  "placeholder" "Choose a terrible thing"
  "custom_id" "menus-duck"
  "options" (cslice
    (sdict "label" "Two Ducks" "value" "opt-1" "default" true)
    (sdict "label" "A Duck" "value" "duck-option" "emoji" (sdict "name" "🦆"))
    (sdict "label" "Half a Duck" "value" "third-option" "description" "Don't let the smaller amount fool you."))
}}

{{ sendMessage nil (complexMessage "menus" $menu) }}
```
```

--------------------------------

### StopSetup Command

Source: https://help.yagpdb.xyz/docs/core/all-commands

Force cancels the current setup session in the channel.

```text
StopSetup
```

--------------------------------

### Comprehensive Message Layout Example

Source: https://help.yagpdb.xyz/docs/reference/components-v2

An example showcasing the combination of various components including text, sections, galleries, files, buttons, menus, and container styling.

```APIDOC
###### Example
This example combines text, sections, gallery, files, buttons, menus, and container styling into a single, cohesive layout.
```
{{ $section := sdict
    "text" "🍲 **Lasagna Recipe**"
    "button" (cbutton "label" "Set Servings" "custom_id" "set-servings" "style" "primary")
}}

{{ $pasta := cslice "### Ingredients" "`200g` pasta sheets" "`500g` minced beef" "`300ml` tomato sauce" "`200g` mozzarella cheese" "`1` onion, diced" }}

{{ $oven := cslice "### Oven Settings" "Mode: `Bake`" "Temp: `180°C`" "Time: `45 minutes`" }}

{{ $gallery := cslice
    (sdict "media" "https://http.cat/420" "description" "Step 1: Prep ingredients")
    (sdict "media" "https://http.cat/451" "description" "Step 2: Into the oven!" "spoiler" true)
}}

{{ $file := cslice
    (sdict
        "content" "Step 1: Boil pasta\nStep 2: Cook beef with onion\nStep 3: Layer pasta, beef, sauce, cheese\nStep 4: Bake at 180°C for 45 min"
        "name" "lasagna_recipe"
    )
    (sdict
        "content" "Tips:\n- Use fresh herbs for better flavor\n- Let it rest 10 min before serving"
        "name" "lasagna_tips"
        "spoiler" true
    )
}}

{{ $buttons := cslice
    (cbutton "label" "➖ Less Cheese" "custom_id" "less-cheese" "style" "danger")
    (cbutton "label" "➕ More Cheese" "custom_id" "more-cheese" "style" "success")
    (cbutton "label" "🍷 Suggest Wine Pairing" "custom_id" "wine" "style" "secondary")
}}

{{ $menus := cmenu
    "custom_id" "sauce-select"
    "options" (cslice
        (sdict "label" "Classic Tomato" "value" "tomato")
        (sdict "label" "White Sauce" "value" "bechamel")
        (sdict "label" "Spicy Arrabbiata" "value" "arrabbiata")
    )
}}

{{ $comp := componentBuilder
    "silent" true
    "container" (sdict
        "color" 0xF5CDF6
        "components" (componentBuilder
            "section" $section
            "text" $pasta
            "separator" true
            "text" $oven
            "gallery" $gallery
            "file" $file
            "separator" true
            "buttons" $buttons
            "menus" $menus
        )
    )
}}

{{ sendMessage nil $comp }}
```
```

--------------------------------

### GET /Help

Source: https://help.yagpdb.xyz/docs/core/all-commands

Shows help information about all commands or a specific command.

```APIDOC
## GET /Help

### Description
Shows help about all or one specific command.

### Method
GET

### Endpoint
Help [command:Text]

### Parameters
#### Path Parameters
- **command** (Text) - Optional - The specific command to get help for.
```

--------------------------------

### Get Guild Roles Count

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs the total number of roles in the guild. This example demonstrates how to get the count.

```go
{{len .Guild.Roles}}
```

--------------------------------

### Calculate Member Permissions in Channel

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Calculates the full permissions an individual member has within a specific channel, considering their roles. This example shows how to get the permissions integer for the triggering member in the current channel.

```go
{{.Guild.GetMemberPermissions .Channel.ID .Member.User.ID .Member.Roles}}
```

--------------------------------

### GET /Invite

Source: https://help.yagpdb.xyz/docs/core/all-commands

Responds with the bot invite link.

```APIDOC
## GET /Invite

### Description
Responds with bot invite link.

### Method
GET

### Endpoint
Invite
```

--------------------------------

### GET /Prefix

Source: https://help.yagpdb.xyz/docs/core/all-commands

Shows the command prefix of the current or specified server.

```APIDOC
## GET /Prefix

### Description
Shows command prefix of the current server, or the specified server.

### Method
GET

### Endpoint
Prefix [Server-ID:Whole number]

### Parameters
#### Path Parameters
- **Server-ID** (Whole number) - Optional - The ID of the server to check.
```

--------------------------------

### Get Guild Name

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs the name of the guild.

```go
{{.Guild.Name}}
```

--------------------------------

### GET /Info

Source: https://help.yagpdb.xyz/docs/core/all-commands

Responds with general bot information.

```APIDOC
## GET /Info

### Description
Responds with bot information.

### Method
GET

### Endpoint
Info
```

--------------------------------

### Accessing Interaction Arguments

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Examples of accessing command arguments and joining them into a single string variable.

```text
{{index .Args 0}}
```

```text
{{$allArgs := (joinStr " " .CmdArgs)}}
```

--------------------------------

### Check Administrator Permission

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Example of using `hasPermissions` to check if the user has the Administrator permission.

```go template
{{ if hasPermissions .Permissions.Administrator }}
  You have the Administrator permission!
{{ else }}
  You do not have the Administrator permission.
{{ end }}
```

--------------------------------

### GET /CustomCommands

Source: https://help.yagpdb.xyz/docs/core/all-commands

Shows a custom command by ID, trigger, or name, or lists all.

```APIDOC
## GET /CustomCommands

### Description
Shows a custom command specified by id, trigger, or name, or lists them all.

### Method
GET

### Endpoint
CustomCommands [ID:Whole number] [Name-Or-Trigger:Text]

### Parameters
#### Query Parameters
- **file** (Switch) - Optional - Send responses in file.
- **color** (Switch) - Optional - Use syntax highlighting (Go).
- **raw** (Switch) - Optional - Force raw output.
```

--------------------------------

### Get user object

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Returns the full user object for a given ID or mention.

```text
{{ $user := userArg <input> }}
```

--------------------------------

### slice - Extract Subslice

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Returns a subslice of the input `item` (which may be an array, slice, or string) containing the elements starting at index `start` (inclusive), and ending at index `end`, exclusive. If only `start` is provided, it is interpreted as the start index and the subslice extends to the end of `item`.

```APIDOC
## slice

### Description
Returns a subslice of the input `item` containing elements from `start` (inclusive) to `end` (exclusive).

### Syntax
```go
{{ $result := slice <item> <start> [end] }}
```

### Parameters
- **item** (array/slice/string) - The input data structure to slice.
- **start** (integer) - The starting index (inclusive).
- **end** (integer) - The ending index (exclusive). Optional; if omitted, slices to the end of the item.

### Example
```go
{{ $firstThree := slice .User.Roles 0 3 }}
{{ $restOfRoles := slice .User.Roles 2 }}
```
```

--------------------------------

### Create a Basic Embed

Source: https://help.yagpdb.xyz/docs/reference/custom-embeds

Initializes a simple embed with a title and description, then sends it to the current channel.

```text
{{ $embed := cembed "title" "This is my title" "description" "This is my description." }}
{{ sendMessage nil $embed }}
```

--------------------------------

### seq - Generate Integer Sequence

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Creates a new slice with integer-type elements, starting from `start` and ending at `stop-1`. `start` and `stop` must be whole numbers. Limited to 10,000 elements.

```APIDOC
## seq

### Description
Creates a new slice with integer-type elements, starting from `start` and ending at `stop-1`. `start` and `stop` must be whole numbers. Limited to 10,000 elements.

### Syntax
```go
{{ $sequence := seq <start> <stop> }}
```

### Parameters
- **start** (integer) - The starting number of the sequence (inclusive).
- **stop** (integer) - The ending number of the sequence (exclusive).

### Example
```go
{{ $mySequence := seq 1 5 }}
```

### Notes
- Limited to 10,000 elements.
```

--------------------------------

### Get Guild Verification Level

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs the required verification level for new members joining the guild.

```go
{{.Guild.VerificationLevel}}
```

--------------------------------

### Database Pattern Matching Example

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Demonstrates using PostgreSQL-like patterns for retrieving and deleting multiple database entries. Underscore (_) matches any single character, and percent (%) matches any sequence of zero or more characters.

```gohtml
{{dbGetPattern "user_id" "prefix_%%"}}
{{dbDelMultiple "user_id" "prefix_%%"}}
```

--------------------------------

### Get Channel ID via Mention

Source: https://help.yagpdb.xyz/docs/reference/how-to-get-ids

To get a channel ID, mention the channel and append a backslash.

```text
\#announcements
```

--------------------------------

### Create a 10-second countdown timer

Source: https://help.yagpdb.xyz/docs/reference/custom-commands-examples

This example requires two custom commands. The first command initiates the countdown by sending a message with the target time and then calls the second command using `execCC`. Replace `REPLACE-WITH-NEXT-CC-ID` with the actual ID of the second custom command.

```go-template
{{$args := parseArgs 2 "" (carg "duration" "countdown-duration") (carg "string" "countdown-message")}}

{{$t := currentTime.Add ($args.Get 0)}}
{{$mID := sendMessageRetID nil (print "countdown starting... " $t.String)}}
{{execCC REPLACE-WITH-NEXT-CC-ID nil 0 (sdict "MessageID" $mID "T" $t "Message" ($args.Get 1)) }}
```

```go-template
{{$timeLeft := .ExecData.T.Sub currentTime}}
{{$cntDownMessageHeader := print "Countdown Timer: " .ExecData.Message}}
{{$formattedTimeLeft := humanizeDurationSeconds $timeLeft}}

{{$t := .ExecData.T}}
{{$mID := .ExecData.MessageID}}
{{$ts := .TimeSecond}}

{{if lt $timeLeft (mult .TimeSecond 30)}}
  {{range seq 1 (toInt $timeLeft.Seconds) }}
    {{$timeLeft := $t.Sub currentTime}}
    {{$formattedTimeLeft := humanizeDurationSeconds $timeLeft}}

    {{editMessage nil $mID (print $cntDownMessageHeader "\nTime left: " $formattedTimeLeft " seconds)}}
    {{if gt $timeLeft $ts}} {{sleep 1}} {{end}}
  {{end}}
  {{editMessage nil  .ExecData.MessageID (print $cntDownMessageHeader "\nTime left: **ENDED**")}} 
{{else}}
    {{editMessage nil .ExecData.MessageID (print $cntDownMessageHeader "\nTime left: " $formattedTimeLeft)}}
    {{execCC .CCID nil 10 .ExecData}}
{{end}}
```

--------------------------------

### Get User ID via Mention

Source: https://help.yagpdb.xyz/docs/reference/how-to-get-ids

To get a user ID, mention the user and append a backslash.

```text
\@YAGPDB.xyz#8760
```

--------------------------------

### Example Command Usage with Flags - YAGPDB

Source: https://help.yagpdb.xyz/docs/core/command-settings

Demonstrates how to use flags and switches with YAGPDB commands, noting that they are not affected by the command prefix.

```text
?wouldyourather -raw
```

--------------------------------

### Database Set with User ID Example

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Shows how to set a database entry associated with a specific user ID. A UserID of 0 can be used to make the entry global.

```gohtml
dbSet "1234567890" "userSpecificData"
// Global entry
dbSet "0" "globalData"
```

--------------------------------

### Get Custom Emoji ID

Source: https://help.yagpdb.xyz/docs/reference/how-to-get-ids

To get a custom emoji ID, prepend a backslash to the emoji. This displays the emoji name along with its ID.

```text
\:yag:<:yag:277569741932068864>
```

--------------------------------

### Database Count Entries Example

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Demonstrates how to count the number of database entries that match a specific key and user ID. This can be used for tracking or statistics.

```gohtml
{{dbCount "user_id" "some_key_pattern%"}}
```

--------------------------------

### Build Gallery Component

Source: https://help.yagpdb.xyz/docs/reference/components-v2

Create a 'gallery' component using `componentBuilder` and `cslice` to display one or more media items. Each item can have an optional description and spoiler flag.

```go
{{ $gallery := componentBuilder
    "gallery" (cslice
        (sdict "media" "https://http.cat/103")
        (sdict "media" "https://http.cat/420" "description" "I dont have food pics")
        (sdict "media" "https://http.cat/451" "description" "So have random cats" "spoiler" true)
    )
}}
```

--------------------------------

### GET /Whois

Source: https://help.yagpdb.xyz/docs/core/all-commands

Shows information about a user.

```APIDOC
## GET /Whois

### Description
Shows information about a user.

### Method
GET

### Endpoint
Whois [User:Member]

### Parameters
#### Path Parameters
- **User** (Member) - Optional - The user to look up.
```

--------------------------------

### Get Random Noun

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Returns a random noun.

```text
{{ $noun := noun }}
```

--------------------------------

### Check Permissions in a Channel with Bitwise Operations

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Example demonstrating how to calculate and check specific permissions for a user in a channel other than the current one using bitwise operations.

```go template
{{ $perms := getTargetPermissionsIn .User.ID $someChannel }}
{{ $mask := bitwiseAnd .Permissions.ManageRoles $perms }}
{{ if eq $mask .Permissions.ManageRoles }}
  You have the permissions to manage roles!
{{ else }}
  You do not have the permissions to manage roles!
{{ end }}
```

--------------------------------

### Get random adjective

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Returns a random adjective.

```text
{{ $adj := adjective }}
```

--------------------------------

### Accessing Message Components

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Example of how to index the first button or menu within a message's components. Ensure the message has components before attempting to access them.

```go template
( index ( index .Message.Components 0 ).Components 0 )
```

--------------------------------

### Initialize and Merge Component Builders

Source: https://help.yagpdb.xyz/docs/reference/components-v2

Demonstrates creating multiple component builders, populating them with sections and slices, and merging them into a single builder.

```YAGPDB
{{ $builder1 := componentBuilder }}
{{ $builder2 := componentBuilder }}
{{ $oven := cslice
    "### Oven Settings"
    "Mode: `Bake`"
    "Temp: `180°C`"
    "Time: `45 minutes`"
}}
{{ $section := sdict
    "text" "🍲 **Lasagna Recipe**"
    "button" (cbutton "label" "Set Servings" "custom_id" "set-servings" "style" "primary")
}}
{{ $builder1.Add "section" $section }}
{{ $builder2.AddSlice "text" $oven }}
{{ $builder1.Merge $builder2 }}
```

--------------------------------

### GET /Undelete

Source: https://help.yagpdb.xyz/docs/core/all-commands

Views recently deleted messages.

```APIDOC
## GET /Undelete

### Description
Views the recent deleted messages.

### Method
GET

### Endpoint
Undelete

### Parameters
#### Query Parameters
- **a** (Switch) - Optional - From all users.
- **u** (Mention/ID) - Optional - From a specific user.
- **count** (Whole number) - Optional - Number of messages to show (Min: 1, Max 10).
- **channel** (Channel) - Optional - Target channel.
```

--------------------------------

### General cslice Operations

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Demonstrates creating a cslice, appending elements, setting values at specific indices, and appending another slice. It also shows how to check the type of the variable.

```go template
Creating a new cslice: {{ $x := (cslice "red" "red") }} **{{ $x }}**
Appending to current cslice data
and assigning newly created cslice to same variable:
{{ $x = $x.Append "green" }} **{{ $x }}**
Setting current cslice value in position 1:
{{ $x.Set 1 "blue" }} **{{ $x }}**
Indexing that position 1:
**{{ index $x 1 }}**
Appending a slice to current cslice data
but not assigning newly created cslice to same variable:
**{{ $x.AppendSlice (cslice "yellow" "magenta") }}**
Variable is still: **{{ $x }}**
Type of variable: **{{ printf "%T" $x }}**
```

--------------------------------

### Database Set with Expiration Example

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Illustrates setting a database entry with a specific expiration time. The entry will be automatically deleted after the specified duration.

```gohtml
dbSet "tempKey" "temporaryValue" "1h"
```

--------------------------------

### Using Pipelines

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Examples of chaining function calls using the pipe operator to pass output as the last parameter of the next function.

```text
{{randInt 41| add 2}}
```

```text
{{40| add 2}}
```

```text
{{ add 2 (randInt 41) }}
```

```text
{{$x:=40| add 2}}
```

```text
{{($x:=40)| add 2}}
```

--------------------------------

### verb - Get Random Verb

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Returns a random verb.

```APIDOC
## verb

### Description
Returns a random verb.

### Syntax
```go
{{ $verb := verb }}
```

### Example
```go
{{ $randomAction := verb }}
```
```

--------------------------------

### Get Length

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Returns the length of a slice, map, or string.

```text
{{ $length := len <list> }}
```

--------------------------------

### Create a simple embed

Source: https://help.yagpdb.xyz/docs/reference/custom-embeds

Use the simpleembed command with switches to define embed fields. Values must be enclosed in quotes.

```text
-se -title "This is my title" -desc "This is my description" -thumbnail "https://via.placeholder.com/300/"
```

--------------------------------

### Get Guild ID

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs the unique ID of the guild.

```go
{{.Guild.ID}}
```

--------------------------------

### List all user notes from the database

Source: https://help.yagpdb.xyz/docs/reference/custom-commands-examples

Retrieves and lists up to 100 notes created by the user, displaying their keys and creation times. If no notes are found, it displays a message indicating that.

```go-template
{{$notes := dbGetPattern .User.ID "notes_%" 100 0}}
{{range $notes}}
{{- $strippedKey := slice .Key 6 (len .Key)}}
`{{$strippedKey}}` created {{humanizeTimeSinceDays .CreatedAt}} ago
{{- else}}
You don't have any notes :( 
{{end}}
```

--------------------------------

### Build Section Component with Thumbnail and Button

Source: https://help.yagpdb.xyz/docs/reference/components-v2

Construct a 'section' component using `componentBuilder`. Sections can include text and either a button or a thumbnail. This example demonstrates including both for brevity, though only one accessory is permitted per section.

```go
{{ $section := componentBuilder
    "section" (sdict
        "text" "🍲 **Lasagna Recipe**"
        "thumbnail" (sdict
            "media" "https://http.cat/103"
            "description" "Alt text"
            "spoiler" false
        )
        "button" (cbutton (sdict "label" "Set Servings" "custom_id" "set-servings" "style" "primary"))
    )
}}
```

--------------------------------

### GET /premiumstatus

Source: https://help.yagpdb.xyz/docs/core/all-commands

Checks the premium status of yourself or a specific user.

```APIDOC
## GET /premiumstatus

### Description
Lets you check premium status of yourself or a specific user.

### Method
GET

### Endpoint
premiumstatus

### Parameters
#### Query Parameters
- **user** (Mention/ID) - Optional - User to check premium status for (Owner only).
```

--------------------------------

### Build File Component

Source: https://help.yagpdb.xyz/docs/reference/components-v2

Attach text files to a message using the 'file' component. Each file can have content (up to 100,000 characters) and a name. The '.txt' extension is appended automatically. A spoiler flag can also be set.

```go
{{ $file := componentBuilder
    "file" (cslice
        (sdict
            "content" "Step 1: Boil pasta\nStep 2: Cook beef\nStep 3: Layer & bake"
            "name" "lasagna_recipe"
        )
        (sdict
            "content" "Tips:\n- Use fresh herbs\n- Let it rest 10 min before serving"
            "name" "lasagna_tips"
            "spoiler" true
        )
    )
}}
```

--------------------------------

### Trivia Commands

Source: https://help.yagpdb.xyz/docs/core/all-commands

Commands for starting, ranking, and managing trivia sessions.

```APIDOC
## Trivia Start

### Description
Starts a trivia session with a specified difficulty.

### Method
POST

### Endpoint
/api/trivia/start

### Parameters
#### Query Parameters
- **Difficulty** (Text) - Optional - The difficulty of the trivia questions (e.g., 'easy', 'medium', 'hard'). Defaults to 'medium'.

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the trivia session has started.

#### Response Example
```json
{
  "message": "Trivia session started with medium difficulty."
}
```
```

```APIDOC
## Trivia Rank

### Description
Shows the trivia rank for the authenticated user or a specified user.

### Method
GET

### Endpoint
/api/trivia/rank

### Parameters
#### Query Parameters
- **user** (Mention/ID) - Optional - The user whose rank to check. Defaults to the authenticated user.

### Response
#### Success Response (200)
- **rank_data** (object) - Object containing rank information.
  - **user_id** (string) - The user's ID.
  - **score** (integer) - The user's trivia score.
  - **rank** (integer) - The user's overall rank.

#### Response Example
```json
{
  "rank_data": {
    "user_id": "1234567890",
    "score": 500,
    "rank": 10
  }
}
```
```

```APIDOC
## Trivia Leaderboard

### Description
Shows the trivia leaderboard, sortable by different criteria.

### Method
GET

### Endpoint
/api/trivia/leaderboard

### Parameters
#### Query Parameters
- **Sort** (Text) - Optional - The criteria to sort the leaderboard by (e.g., 'score', 'streak', 'maxstreak', 'correct', 'incorrect'). Defaults to 'score'.

### Response
#### Success Response (200)
- **leaderboard** (array) - An array of users and their trivia statistics.
  - **user_id** (string) - The user's ID.
  - **username** (string) - The user's name.
  - **score** (integer) - The user's trivia score.
  - **streak** (integer) - The user's current streak.
  - **max_streak** (integer) - The user's maximum streak.
  - **correct** (integer) - The number of correct answers.
  - **incorrect** (integer) - The number of incorrect answers.

#### Response Example
```json
{
  "leaderboard": [
    {
      "user_id": "1234567890",
      "username": "ExampleUser",
      "score": 500,
      "streak": 5,
      "max_streak": 10,
      "correct": 50,
      "incorrect": 5
    }
  ]
}
```
```

```APIDOC
## Trivia ResetLeaderboard

### Description
Resets the trivia leaderboard for the server. This action is irreversible.

### Method
POST

### Endpoint
/api/trivia/leaderboard/reset

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the leaderboard has been reset.

#### Response Example
```json
{
  "message": "Trivia leaderboard reset successfully."
}
```
```

--------------------------------

### Initialize Modal Builder

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Creates a new modal builder instance. This builder simplifies the construction of components for use in modals.

```go
{{ $builder := modalBuilder }}
```

--------------------------------

### Get Role Name

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Retrieves a role object by its name, case-insensitive.

```YAGPDB
{{ $role := getRoleName <roleName> }}
```

--------------------------------

### componentBuilder

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Simplifies building Discord’s ComponentsV2 in custom commands.

```APIDOC
## componentBuilder

### Description
Returns a complex message object with the given components for interactive message layouts.

### Parameters
- **text** (string/slice) - Optional - Message content.
- **section** (sdict) - Optional - Layout block with text and accessory.
- **gallery** (sdict) - Optional - Media display block.
- **file** (sdict) - Optional - File attachment block.
- **separator** (bool) - Optional - Adds spacing.
- **container** (sdict) - Optional - Top-level layout container.
```

--------------------------------

### Get Guild Emojis

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs a list of all emojis present in the guild.

```go
{{.Guild.Emojis}}
```

--------------------------------

### Create dictionary

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Creates a dictionary from key-value pairs.

```text
{{ $dict := dict [values...] }}
```

--------------------------------

### GET /Logs

Source: https://help.yagpdb.xyz/docs/core/all-commands

Creates a log of the last messages in the current channel.

```APIDOC
## GET /Logs

### Description
Creates a log of the last messages in the current channel.

### Method
GET

### Endpoint
Logs [Count:Whole number]

### Parameters
#### Path Parameters
- **Count** (Whole number) - Optional - Number of messages to log.
#### Query Parameters
- **channel** (Channel) - Optional - Target channel to log.
```

--------------------------------

### Database Top/Bottom Entries Example

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Shows how to retrieve the top or bottom entries from the database based on a specified key and user ID. This is useful for leaderboards or ordered data retrieval.

```gohtml
{{dbTopEntries "user_id" "leaderboard" 10}}
{{dbBottomEntries "user_id" "leaderboard" 10}}
```

--------------------------------

### GET /Stats

Source: https://help.yagpdb.xyz/docs/core/all-commands

Shows server statistics if public stats are enabled.

```APIDOC
## GET /Stats

### Description
Shows server stats (if public stats are enabled).

### Method
GET

### Endpoint
Stats
```

--------------------------------

### Create and Send Message with Buttons

Source: https://help.yagpdb.xyz/docs/reference/custom-interactions

This snippet demonstrates how to create three different buttons with various styles and labels, then send them in a message. Note that link-style buttons require a URL and cannot have a custom ID.

```go template
{{ $button1 := cbutton "label" "Duck One" "custom_id" "buttons-duck-alpha" "style" "success" }}
{{ $button2 := cbutton "emoji" (sdict "name" "🦆") "custom_id" "buttons-duck-beta" "style" "danger" }}
{{ $button3 := cbutton "label" "Duck Three" "emoji" (sdict "name" "🦆") "url" "https://yagpdb.xyz" "style" "link" }}
{{ $message := complexMessage "buttons" (cslice $button1 $button2 $button3) }}
{{ sendMessage nil $message }}
```

--------------------------------

### Accessing Context and Variables

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Demonstrates the use of the dot cursor for context, comments, and variable assignment.

```text
{{ . }}
```

```text
{{.Bot}}
```

```text
{{.User.Bot}}
```

```text
{{/* this is a comment */}}
```

```text
{{ $ := . }}
```

```text
$variable := value
```

```text
$variable = value
```

--------------------------------

### Get Guild Member Count

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs the total number of users in the guild.

```go
{{.Guild.MemberCount}}
```

--------------------------------

### Create Forum Post

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Creates a new forum post within a specified channel. It returns a channel object upon successful creation. The `name` and `content` arguments cannot be empty. Optional `values` can include `slowmode` and `tags`.

```go template
{{ $post := createForumPost <channel> <name> <content> [values] }}
```

--------------------------------

### Create a Select Menu

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Initializes a select menu object for interaction responses.

```YAGPDB Template
{{ $menu := cmenu "list of select menu values" }}
```

```YAGPDB Template
{{ $menu := cmenu
  "type" "text"
  "placeholder" "Choose a terrible thing"
  "custom_id" "menus-duck"
  "options" (cslice
    (sdict "label" "Two Ducks" "value" "opt-1" "default" true)
    (sdict "label" "A Duck" "value" "duck-option" "emoji" (sdict "name" "🦆"))
    (sdict "label" "Half a Duck" "value" "third-option" "description" "Don't let the smaller amount fool you."))
  "max_values" 3 }}

{{ sendMessage nil (complexMessage "menus" $menu) }}
```

--------------------------------

### Get Guild Channels

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs a slice containing all channels within the guild.

```go
{{.Guild.Channels}}
```

--------------------------------

### Create a text display component

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Creates a component for displaying text, with support for Markdown.

```text
{{ $textDisplay := ctextDisplay (values...) }}
```

--------------------------------

### String Prefix and Suffix Checks

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Checks if a string starts or ends with a specific substring.

```YAGPDB
{{ $result := hasPrefix <string> <prefix> }}
```

```YAGPDB
{{ $result := hasSuffix <string> <suffix> }}
```

--------------------------------

### Create and Manipulate SDict

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Demonstrates creating an SDict, retrieving values by key, modifying existing keys, adding new keys, and deleting keys. SDict is an ordered map useful for custom commands.

```gohtml
{{ $x := sdict "color1" "green" "color2" "red" }} **{{ $x }}**
Retrieving key "color2": **{{ $x.Get "color2" }}**
Changing "color2" to "yellow": {{ $x.Set "color2" "yellow" }} **{{ $x }}**
Adding "color3" as "blue": {{ $x.Set "color3" "blue" }} **{{ $x }}**
Deleting key "color1" {{ $x.Del "color1" }} and whole sdict: **{{ $x }}**
```

--------------------------------

### Get Database Entry

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Returns a specific database entry by user ID and key.

```YAGPDB
{{ $entry := dbGet <userID> <key> }}
```

--------------------------------

### Execute template with block action

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

The block action defines and executes a template in one step.

```text
{{ $name := "YAG" }}
{{ block "sayHi" $name }}
    hi there, {{ . }}
{{ end }}

{{/* equivalent to above */}}
{{ define "sayHi" }}
    hi there, {{ . }}
{{ end }}
{{ template "sayHi" $name }}
```

--------------------------------

### Get Pin Count

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Returns the number of pinned messages in the specified channel.

```go template
{{ $numPins := getPinCount <channel> }}
```

--------------------------------

### Initialize Modal Builder with Values

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Initializes a modal builder with a title, custom ID, and components. This provides a convenient way to set initial modal properties.

```go
{{ $builder := modalBuilder title custom_id components... }}
```

--------------------------------

### Get Guild Stickers

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs a slice containing all sticker objects available in the guild.

```go
{{.Guild.Stickers}}
```

--------------------------------

### Get Guild Owner ID

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs the user ID of the guild's owner.

```go
{{.Guild.OwnerID}}
```

--------------------------------

### Initialize SDict with Various Types

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Shows how to initialize an SDict with different value types, including numbers, slices, and floats. The underlying type remains interface{}, preserving the original data types.

```gohtml
sdict "one" 1 "two" 2 "three" (cslice 3 4) "five" 5.5
```

--------------------------------

### Joining Message Arguments

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Demonstrates how to join all arguments passed after a custom command trigger into a single string variable. This is useful for processing multi-word commands.

```go template
{{$allArgs := (joinStr " " .CmdArgs)}}
```

--------------------------------

### Get Guild Icon Hash

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs the hash ID of the guild's icon.

```go
{{.Guild.Icon}}
```

--------------------------------

### Get Guild Features

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs a slice of strings representing the enabled features for the guild.

```go
{{.Guild.Features}}
```

--------------------------------

### Build Menus Component

Source: https://help.yagpdb.xyz/docs/reference/components-v2

Add select menus for user options using the 'menus' component. A maximum of 5 menus can be used per message, and each menu occupies its own row. Configure options with labels and values.

```go
{{ $menu := componentBuilder
    "menus" (cmenu
        "custom_id" "unit-select"
        "options" (cslice
            (sdict "label" "Metric" "value" "metric")
            (sdict "label" "Imperial" "value" "imperial")
            (sdict "label" "Kelvin" "value" "kelvin")
        )
    )
}}
```

--------------------------------

### Get Guild AFK Channel ID

Source: https://help.yagpdb.xyz/docs/reference/templates/syntax-and-data

Outputs the ID of the AFK channel for the guild.

```go
{{.Guild.AfkChannelID}}
```

--------------------------------

### Soundboard Commands

Source: https://help.yagpdb.xyz/docs/core/all-commands

Commands for playing and managing soundboard sounds.

```APIDOC
## Soundboard

### Description
Plays a specified sound from the soundboard or lists available sounds if no name is provided.

### Method
POST

### Endpoint
/api/soundboard/play

### Parameters
#### Query Parameters
- **Name** (Text) - Required - The name of the sound to play.

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the sound is playing or a list of available sounds.

#### Response Example
```json
{
  "message": "Playing 'sound_name'."
}
```
```

```APIDOC
## SoundboardReset

### Description
Resets the soundboard player, stopping any currently playing sounds.

### Method
POST

### Endpoint
/api/soundboard/reset

### Response
#### Success Response (200)
- **message** (string) - Confirmation that the soundboard has been reset.

#### Response Example
```json
{
  "message": "Soundboard player reset."
}
```
```

--------------------------------

### Create Thread

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Creates a new thread in a specified channel, returning a channel object on success. Optional arguments for `private`, `auto_archive_duration`, and `invitable` can be provided positionally. The example demonstrates creating a public thread with specific archival and invitation settings.

```go template
{{ $thread := createThread <channel> <messageID> <name> [private] [auto_archive_duration] [invitable] }}
```

```go template
{{ createThread nil nil "new thread" false 60 true }}
```

--------------------------------

### Cron Expression Examples

Source: https://help.yagpdb.xyz/docs/custom-commands/commands

Commonly used cron expressions for scheduling tasks at specific intervals.

```text
45 23 * * 6
Run once a week, on Saturday at 23:45.

0 * * * *
Run once an hour, beginning of hour.

0 0 * * *
Run once a day, midnight.

0 0 * * 0
Run once a week, midnight between Sat/Sun.

0 0 1 * *
Run once a month, midnight, first of month.

0 0 1 1 *
Run once a year, midnight, Jan. 1st.
```

--------------------------------

### Define Embed Fields

Source: https://help.yagpdb.xyz/docs/reference/custom-embeds

Demonstrates how to use cslice and sdict to add multiple fields to an embed.

```text
"fields" (cslice
    (sdict "name" "Title of field 1" "value" "Description of field 1" "inline" false)
    (sdict "name" "Title of field 2" "value" "Description of field 2" "inline" false)
)
```

--------------------------------

### Get User Warnings

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Retrieves a slice of warnings for a specific user ID or user object.

```text
{{ $warnings := getWarnings <user> }}
```

--------------------------------

### Format String with Arguments

Source: https://help.yagpdb.xyz/docs/reference/templates/functions

Utilize `printf` for formatted string interpolation, similar to Go's `fmt` package. Ensure the format string and arguments match.

```go
{{ $result := printf <format> <args...> }}
```
Tokens:
Raw