KosmoKrator

productivity

Discord Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Discord KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.discord.*. Use lua_read_doc("integrations.discord") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Discord workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.discord.api_get({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("discord"))' --json
kosmo integrations:lua --eval 'print(docs.read("discord.api_get"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local discord = app.integrations.discord
local result = discord.api_get({})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.discord, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.discord.default.* or app.integrations.discord.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Discord, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Discord

Discord tools are exposed under app.integrations.discord. The integration targets Discord REST API v10 and supports both OAuth-style Bearer tokens and bot tokens through the token_type credential.

Use token_type = "Bot" for Discord bot tokens. Use token_type = "Bearer" for OAuth access tokens. Many guild moderation, role, webhook, and message-management endpoints require bot tokens with the corresponding guild permissions.

Raw API Helpers

Use the raw helpers for Discord REST endpoints that do not yet have a first-class tool:

  • discord_api_get
  • discord_api_post
  • discord_api_patch
  • discord_api_put
  • discord_api_delete

Paths are relative to https://discord.com/api/v10.

local roles = app.integrations.discord.discord_api_get({
  path = "/guilds/1234567890/roles"
})

Guild And Channel Discovery

local me = app.integrations.discord.discord_get_current_user({})

local guilds = app.integrations.discord.discord_list_guilds({
  limit = 50
})

local channels = app.integrations.discord.discord_list_channels({
  guild_id = "1234567890"
})

Channel lifecycle tools:

  • discord_create_guild_channel
  • discord_get_channel
  • discord_edit_channel
  • discord_delete_channel
  • discord_edit_channel_positions

Most create/update tools accept first-class snake_case fields and a raw body object for Discord’s exact request schema.

Messages

local sent = app.integrations.discord.discord_send_message({
  channel_id = "2222222222",
  content = "Deployment finished."
})

local messages = app.integrations.discord.discord_list_messages({
  channel_id = "2222222222",
  limit = 25
})

Message management tools include:

  • discord_get_message
  • discord_edit_message
  • discord_delete_message
  • discord_bulk_delete_messages
  • discord_list_pinned_messages
  • discord_pin_message
  • discord_unpin_message
  • discord_create_reaction
  • discord_delete_own_reaction
  • discord_list_reaction_users

Discord restricts message reads and content fields based on bot membership, channel permissions, and privileged intents. The REST API may return messages without full content when the token is not allowed to view it.

Members, Roles, And Moderation

local members = app.integrations.discord.discord_list_guild_members({
  guild_id = "1234567890",
  limit = 100
})

app.integrations.discord.discord_add_guild_member_role({
  guild_id = "1234567890",
  user_id = "3333333333",
  role_id = "4444444444"
})

Available tools:

  • discord_list_guild_members
  • discord_get_guild_member
  • discord_edit_guild_member
  • discord_kick_guild_member
  • discord_add_guild_member_role
  • discord_remove_guild_member_role
  • discord_list_guild_roles
  • discord_create_guild_role
  • discord_edit_guild_role
  • discord_delete_guild_role
  • discord_list_guild_bans
  • discord_create_guild_ban
  • discord_remove_guild_ban

Use caution with destructive moderation tools. Discord permission errors are returned directly from the API.

Invites And Webhooks

Invite tools:

  • discord_list_guild_invites
  • discord_create_channel_invite
  • discord_get_invite
  • discord_delete_invite

Webhook tools:

  • discord_list_channel_webhooks
  • discord_list_guild_webhooks
  • discord_create_webhook
  • discord_get_webhook
  • discord_edit_webhook
  • discord_delete_webhook

Webhook execution with webhook token is intentionally left to raw API helpers because it uses token-in-path authentication and may be better handled by a dedicated unauthenticated webhook-send integration.

Output Shape

Existing compatibility tools such as discord_list_messages, discord_list_channels, and discord_get_current_user keep their normalized response shape. New endpoint-mapped tools return Discord’s parsed JSON response directly, or an empty object for 204 No Content responses.

Raw agent markdown 
# Discord

Discord tools are exposed under `app.integrations.discord`. The integration targets Discord REST API v10 and supports both OAuth-style `Bearer` tokens and bot tokens through the `token_type` credential.

Use `token_type = "Bot"` for Discord bot tokens. Use `token_type = "Bearer"` for OAuth access tokens. Many guild moderation, role, webhook, and message-management endpoints require bot tokens with the corresponding guild permissions.

## Raw API Helpers

Use the raw helpers for Discord REST endpoints that do not yet have a first-class tool:

- `discord_api_get`
- `discord_api_post`
- `discord_api_patch`
- `discord_api_put`
- `discord_api_delete`

Paths are relative to `https://discord.com/api/v10`.

```lua
local roles = app.integrations.discord.discord_api_get({
  path = "/guilds/1234567890/roles"
})
```

## Guild And Channel Discovery

```lua
local me = app.integrations.discord.discord_get_current_user({})

local guilds = app.integrations.discord.discord_list_guilds({
  limit = 50
})

local channels = app.integrations.discord.discord_list_channels({
  guild_id = "1234567890"
})
```

Channel lifecycle tools:

- `discord_create_guild_channel`
- `discord_get_channel`
- `discord_edit_channel`
- `discord_delete_channel`
- `discord_edit_channel_positions`

Most create/update tools accept first-class snake_case fields and a raw `body` object for Discord's exact request schema.

## Messages

```lua
local sent = app.integrations.discord.discord_send_message({
  channel_id = "2222222222",
  content = "Deployment finished."
})

local messages = app.integrations.discord.discord_list_messages({
  channel_id = "2222222222",
  limit = 25
})
```

Message management tools include:

- `discord_get_message`
- `discord_edit_message`
- `discord_delete_message`
- `discord_bulk_delete_messages`
- `discord_list_pinned_messages`
- `discord_pin_message`
- `discord_unpin_message`
- `discord_create_reaction`
- `discord_delete_own_reaction`
- `discord_list_reaction_users`

Discord restricts message reads and content fields based on bot membership, channel permissions, and privileged intents. The REST API may return messages without full content when the token is not allowed to view it.

## Members, Roles, And Moderation

```lua
local members = app.integrations.discord.discord_list_guild_members({
  guild_id = "1234567890",
  limit = 100
})

app.integrations.discord.discord_add_guild_member_role({
  guild_id = "1234567890",
  user_id = "3333333333",
  role_id = "4444444444"
})
```

Available tools:

- `discord_list_guild_members`
- `discord_get_guild_member`
- `discord_edit_guild_member`
- `discord_kick_guild_member`
- `discord_add_guild_member_role`
- `discord_remove_guild_member_role`
- `discord_list_guild_roles`
- `discord_create_guild_role`
- `discord_edit_guild_role`
- `discord_delete_guild_role`
- `discord_list_guild_bans`
- `discord_create_guild_ban`
- `discord_remove_guild_ban`

Use caution with destructive moderation tools. Discord permission errors are returned directly from the API.

## Invites And Webhooks

Invite tools:

- `discord_list_guild_invites`
- `discord_create_channel_invite`
- `discord_get_invite`
- `discord_delete_invite`

Webhook tools:

- `discord_list_channel_webhooks`
- `discord_list_guild_webhooks`
- `discord_create_webhook`
- `discord_get_webhook`
- `discord_edit_webhook`
- `discord_delete_webhook`

Webhook execution with webhook token is intentionally left to raw API helpers because it uses token-in-path authentication and may be better handled by a dedicated unauthenticated webhook-send integration.

## Output Shape

Existing compatibility tools such as `discord_list_messages`, `discord_list_channels`, and `discord_get_current_user` keep their normalized response shape. New endpoint-mapped tools return Discord's parsed JSON response directly, or an empty object for `204 No Content` responses.
Metadata-derived Lua example 
local result = app.integrations.discord.api_get({})
print(result)

Functions

api_get Read

Execute a raw Discord API GET request.

Lua path
app.integrations.discord.api_get
Full name
discord.discord_api_get
ParameterTypeRequiredDescription
No parameters.
api_post Write

Execute a raw Discord API POST request.

Lua path
app.integrations.discord.api_post
Full name
discord.discord_api_post
ParameterTypeRequiredDescription
No parameters.
api_patch Write

Execute a raw Discord API PATCH request.

Lua path
app.integrations.discord.api_patch
Full name
discord.discord_api_patch
ParameterTypeRequiredDescription
No parameters.
api_put Write

Execute a raw Discord API PUT request.

Lua path
app.integrations.discord.api_put
Full name
discord.discord_api_put
ParameterTypeRequiredDescription
No parameters.
api_delete Write

Execute a raw Discord API DELETE request.

Lua path
app.integrations.discord.api_delete
Full name
discord.discord_api_delete
ParameterTypeRequiredDescription
No parameters.
list_guilds Read

List guilds the current Discord user is a member of. Returns guild IDs, names, icons, and owner status. Use limit, before, and after for pagination.

Lua path
app.integrations.discord.list_guilds
Full name
discord.discord_list_guilds
ParameterTypeRequiredDescription
limit integer no Number of guilds to retrieve (1-200, default 200).
before string no Guild ID to get guilds before (for pagination).
after string no Guild ID to get guilds after (for pagination).
get_guild Read

Get information about a Discord guild by its ID. Returns the guild's ID, name, icon, description, member count, and other properties.

Lua path
app.integrations.discord.get_guild
Full name
discord.discord_get_guild
ParameterTypeRequiredDescription
guild_id string yes The ID of the guild to retrieve.
list_channels Read

List all channels in a Discord guild. Returns channel IDs, names, types, and topics.

Lua path
app.integrations.discord.list_channels
Full name
discord.discord_list_channels
ParameterTypeRequiredDescription
guild_id string yes The ID of the guild to list channels for.
create_guild_channel Write

Create a channel in a Discord guild.

Lua path
app.integrations.discord.create_guild_channel
Full name
discord.discord_create_guild_channel
ParameterTypeRequiredDescription
No parameters.
get_channel Read

Get information about a Discord channel by its ID. Returns the channel's ID, name, type, topic, and other properties.

Lua path
app.integrations.discord.get_channel
Full name
discord.discord_get_channel
ParameterTypeRequiredDescription
channel_id string yes The ID of the channel to retrieve.
edit_channel Write

Edit a Discord channel.

Lua path
app.integrations.discord.edit_channel
Full name
discord.discord_edit_channel
ParameterTypeRequiredDescription
No parameters.
delete_channel Write

Delete a Discord guild channel or close a DM.

Lua path
app.integrations.discord.delete_channel
Full name
discord.discord_delete_channel
ParameterTypeRequiredDescription
No parameters.
edit_channel_positions Write

Modify Discord guild channel positions.

Lua path
app.integrations.discord.edit_channel_positions
Full name
discord.discord_edit_channel_positions
ParameterTypeRequiredDescription
No parameters.
list_messages Read

Get messages from a Discord channel. Supports pagination with before/after and limit. Returns message IDs, content, author info, and timestamps.

Lua path
app.integrations.discord.list_messages
Full name
discord.discord_list_messages
ParameterTypeRequiredDescription
channel_id string yes The ID of the channel to get messages from.
limit integer no Number of messages to retrieve (1-100, default 50).
before string no Message ID to get messages before (for pagination).
after string no Message ID to get messages after (for pagination).
send_message Write

Send a message to a Discord channel. Supports text content and rich embeds. Returns the sent message ID and channel ID.

Lua path
app.integrations.discord.send_message
Full name
discord.discord_send_message
ParameterTypeRequiredDescription
channel_id string yes The ID of the channel to send the message to.
content string no The text content of the message.
embeds string no JSON array of embed objects for rich formatting.
tts boolean no If true, the message will be read aloud via text-to-speech.
get_message Read

Get one Discord message.

Lua path
app.integrations.discord.get_message
Full name
discord.discord_get_message
ParameterTypeRequiredDescription
No parameters.
edit_message Write

Edit a Discord message.

Lua path
app.integrations.discord.edit_message
Full name
discord.discord_edit_message
ParameterTypeRequiredDescription
No parameters.
delete_message Write

Delete a Discord message.

Lua path
app.integrations.discord.delete_message
Full name
discord.discord_delete_message
ParameterTypeRequiredDescription
No parameters.
bulk_delete_messages Write

Bulk delete Discord messages.

Lua path
app.integrations.discord.bulk_delete_messages
Full name
discord.discord_bulk_delete_messages
ParameterTypeRequiredDescription
No parameters.
list_pinned_messages Read

List pinned messages in a Discord channel.

Lua path
app.integrations.discord.list_pinned_messages
Full name
discord.discord_list_pinned_messages
ParameterTypeRequiredDescription
No parameters.
pin_message Write

Pin a Discord message.

Lua path
app.integrations.discord.pin_message
Full name
discord.discord_pin_message
ParameterTypeRequiredDescription
No parameters.
unpin_message Write

Unpin a Discord message.

Lua path
app.integrations.discord.unpin_message
Full name
discord.discord_unpin_message
ParameterTypeRequiredDescription
No parameters.
create_reaction Write

Add a reaction to a Discord message.

Lua path
app.integrations.discord.create_reaction
Full name
discord.discord_create_reaction
ParameterTypeRequiredDescription
No parameters.
delete_own_reaction Write

Delete the current user reaction from a Discord message.

Lua path
app.integrations.discord.delete_own_reaction
Full name
discord.discord_delete_own_reaction
ParameterTypeRequiredDescription
No parameters.
list_reaction_users Read

List users who reacted with an emoji.

Lua path
app.integrations.discord.list_reaction_users
Full name
discord.discord_list_reaction_users
ParameterTypeRequiredDescription
No parameters.
list_guild_members Read

List members in a Discord guild.

Lua path
app.integrations.discord.list_guild_members
Full name
discord.discord_list_guild_members
ParameterTypeRequiredDescription
No parameters.
get_guild_member Read

Get a Discord guild member.

Lua path
app.integrations.discord.get_guild_member
Full name
discord.discord_get_guild_member
ParameterTypeRequiredDescription
No parameters.
edit_guild_member Write

Edit a Discord guild member.

Lua path
app.integrations.discord.edit_guild_member
Full name
discord.discord_edit_guild_member
ParameterTypeRequiredDescription
No parameters.
kick_guild_member Write

Kick a member from a Discord guild.

Lua path
app.integrations.discord.kick_guild_member
Full name
discord.discord_kick_guild_member
ParameterTypeRequiredDescription
No parameters.
add_member_role Write

Add a role to a Discord guild member.

Lua path
app.integrations.discord.add_member_role
Full name
discord.discord_add_guild_member_role
ParameterTypeRequiredDescription
No parameters.
remove_member_role Write

Remove a role from a Discord guild member.

Lua path
app.integrations.discord.remove_member_role
Full name
discord.discord_remove_guild_member_role
ParameterTypeRequiredDescription
No parameters.
list_guild_roles Read

List roles in a Discord guild.

Lua path
app.integrations.discord.list_guild_roles
Full name
discord.discord_list_guild_roles
ParameterTypeRequiredDescription
No parameters.
create_guild_role Write

Create a Discord guild role.

Lua path
app.integrations.discord.create_guild_role
Full name
discord.discord_create_guild_role
ParameterTypeRequiredDescription
No parameters.
edit_guild_role Write

Edit a Discord guild role.

Lua path
app.integrations.discord.edit_guild_role
Full name
discord.discord_edit_guild_role
ParameterTypeRequiredDescription
No parameters.
delete_guild_role Write

Delete a Discord guild role.

Lua path
app.integrations.discord.delete_guild_role
Full name
discord.discord_delete_guild_role
ParameterTypeRequiredDescription
No parameters.
list_guild_bans Read

List bans in a Discord guild.

Lua path
app.integrations.discord.list_guild_bans
Full name
discord.discord_list_guild_bans
ParameterTypeRequiredDescription
No parameters.
create_guild_ban Write

Ban a user from a Discord guild.

Lua path
app.integrations.discord.create_guild_ban
Full name
discord.discord_create_guild_ban
ParameterTypeRequiredDescription
No parameters.
remove_guild_ban Write

Remove a ban from a Discord guild.

Lua path
app.integrations.discord.remove_guild_ban
Full name
discord.discord_remove_guild_ban
ParameterTypeRequiredDescription
No parameters.
list_guild_invites Read

List invites for a Discord guild.

Lua path
app.integrations.discord.list_guild_invites
Full name
discord.discord_list_guild_invites
ParameterTypeRequiredDescription
No parameters.
create_channel_invite Write

Create a Discord channel invite.

Lua path
app.integrations.discord.create_channel_invite
Full name
discord.discord_create_channel_invite
ParameterTypeRequiredDescription
No parameters.
get_invite Read

Get a Discord invite.

Lua path
app.integrations.discord.get_invite
Full name
discord.discord_get_invite
ParameterTypeRequiredDescription
No parameters.
delete_invite Write

Delete a Discord invite.

Lua path
app.integrations.discord.delete_invite
Full name
discord.discord_delete_invite
ParameterTypeRequiredDescription
No parameters.
list_channel_webhooks Read

List webhooks for a Discord channel.

Lua path
app.integrations.discord.list_channel_webhooks
Full name
discord.discord_list_channel_webhooks
ParameterTypeRequiredDescription
No parameters.
list_guild_webhooks Read

List webhooks for a Discord guild.

Lua path
app.integrations.discord.list_guild_webhooks
Full name
discord.discord_list_guild_webhooks
ParameterTypeRequiredDescription
No parameters.
create_webhook Write

Create a Discord webhook.

Lua path
app.integrations.discord.create_webhook
Full name
discord.discord_create_webhook
ParameterTypeRequiredDescription
No parameters.
get_webhook Read

Get a Discord webhook.

Lua path
app.integrations.discord.get_webhook
Full name
discord.discord_get_webhook
ParameterTypeRequiredDescription
No parameters.
edit_webhook Write

Edit a Discord webhook.

Lua path
app.integrations.discord.edit_webhook
Full name
discord.discord_edit_webhook
ParameterTypeRequiredDescription
No parameters.
delete_webhook Write

Delete a Discord webhook.

Lua path
app.integrations.discord.delete_webhook
Full name
discord.discord_delete_webhook
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Retrieve the currently authenticated Discord user. Returns the user's ID, username, discriminator, and avatar. Useful for identifying which account or token is in use.

Lua path
app.integrations.discord.get_current_user
Full name
discord.discord_get_current_user
ParameterTypeRequiredDescription
No parameters.