Skip to content
Coritan Docs

Organization API: Discord

Your own Discord bot: application credentials, the staff channel that receives tickets, and which Discord accounts are staff.

View as Markdown

Your own Discord bot: application credentials, the staff channel that receives tickets, and which Discord accounts are staff. The bot token is write-only: we store it encrypted and never return it.

Base URL: https://api.coritan.com/api/v1. Paths below are complete.

To try these requests in the browser, open the interactive Organization API reference.

Operations

Section titled Operations
Method Path Summary
GET /api/v1/orgs/{org_slug}/discord Get discord config
PUT /api/v1/orgs/{org_slug}/discord Put discord config
DELETE /api/v1/orgs/{org_slug}/discord Switch the bot off and forget the token
POST /api/v1/orgs/{org_slug}/discord/community/sync-channels Rebuild the public-channel allowlist from Discord's own permissions
GET /api/v1/orgs/{org_slug}/discord/diagnostics Probe the bot, the guild, the staff channel and the job queue
POST /api/v1/orgs/{org_slug}/discord/register-commands Register commands
GET /api/v1/orgs/{org_slug}/discord/role-menus List role menus
POST /api/v1/orgs/{org_slug}/discord/role-menus Create role menu
PUT /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id} Update role menu
DELETE /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id} Delete role menu
POST /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}/publish Post the menu to its channel, or edit the message already posted for it
GET /api/v1/orgs/{org_slug}/discord/roles The roles in the org's guild, so a menu can be built by picking not typing
GET /api/v1/orgs/{org_slug}/discord/staff List staff links
PUT /api/v1/orgs/{org_slug}/discord/staff Put staff link
DELETE /api/v1/orgs/{org_slug}/discord/staff/{discord_user_id} Delete staff link

Get discord config

Section titled Get discord config

GET /api/v1/orgs/{org_slug}/discord

Parameters

Section titled Parameters
Name In Type Required
org_slug path string yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Fields of a 200 response:

Field Type
configured boolean
application_id string or null
public_key string or null
guild_id string or null
staff_channel_id string or null
staff_channel_kind string
is_enabled boolean
has_bot_token boolean
commands_registered_at string (date-time) or null
interactions_url string or null
last_error string or null
gateway_status string
bot_user_id string or null
ticket_channels_enabled boolean
ticket_category_prefix string
staff_role_id string or null
max_ticket_channels integer
community_chat_enabled boolean
community_invite_url string or null
community_hidden_channels array of string

Put discord config

Section titled Put discord config

PUT /api/v1/orgs/{org_slug}/discord

Parameters

Section titled Parameters
Name In Type Required
org_slug path string yes

Request body

Section titled Request body

application/json (required)

Field Type Required
application_id string yes
public_key string yes
bot_token string or null no
guild_id string or null no
staff_channel_id string or null no
staff_channel_kind string or null no
is_enabled boolean or null no
ticket_channels_enabled boolean or null no
ticket_category_prefix string or null no
staff_role_id string or null no
max_ticket_channels integer or null no
community_chat_enabled boolean or null no
community_invite_url string or null no
community_hidden_channels array of string or null no

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Fields of a 200 response:

Field Type
configured boolean
application_id string or null
public_key string or null
guild_id string or null
staff_channel_id string or null
staff_channel_kind string
is_enabled boolean
has_bot_token boolean
commands_registered_at string (date-time) or null
interactions_url string or null
last_error string or null
gateway_status string
bot_user_id string or null
ticket_channels_enabled boolean
ticket_category_prefix string
staff_role_id string or null
max_ticket_channels integer
community_chat_enabled boolean
community_invite_url string or null
community_hidden_channels array of string

Switch the bot off and forget the token

Section titled Switch the bot off and forget the token

DELETE /api/v1/orgs/{org_slug}/discord

Switch the bot off and forget the token.

The row stays so the channel and application ids do not have to be re-entered, but the credential does not linger on a disabled integration.

Parameters

Section titled Parameters
Name In Type Required
org_slug path string yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Rebuild the public-channel allowlist from Discord's own permissions

Section titled Rebuild the public-channel allowlist from Discord's own permissions

POST /api/v1/orgs/{org_slug}/discord/community/sync-channels

Rebuild the public-channel allowlist from Discord's own permissions.

Parameters

Section titled Parameters
Name In Type Required
org_slug path string yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Probe the bot, the guild, the staff channel and the job queue

Section titled Probe the bot, the guild, the staff channel and the job queue

GET /api/v1/orgs/{org_slug}/discord/diagnostics

Probe the bot, the guild, the staff channel and the job queue.

Answers "why did my ticket not appear in Discord?" without needing shell access.

Parameters

Section titled Parameters
Name In Type Required
org_slug path string yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Register commands

Section titled Register commands

POST /api/v1/orgs/{org_slug}/discord/register-commands

Parameters

Section titled Parameters
Name In Type Required
org_slug path string yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

List role menus

Section titled List role menus

GET /api/v1/orgs/{org_slug}/discord/role-menus

Parameters

Section titled Parameters
Name In Type Required
org_slug path string yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

A 200 response is a list; each item has these fields:

Field Type
[].id integer
[].channel_id string or null
[].menu_key string or null
[].message_id string or null
[].title string
[].description string or null
[].options array of RoleOption
[].options[].role_id string
[].options[].label string
[].options[].key string or null
[].options[].emoji string or null
[].options[].description string or null
[].is_enabled boolean
[].published boolean

Create role menu

Section titled Create role menu

POST /api/v1/orgs/{org_slug}/discord/role-menus

Parameters

Section titled Parameters
Name In Type Required
org_slug path string yes

Request body

Section titled Request body

application/json (required)

Field Type Required
channel_id string or null no
menu_key string or null no
title string yes
description string or null no
options array of RoleOption no
options[].role_id string yes
options[].label string yes
options[].key string or null no
options[].emoji string or null no
options[].description string or null no
is_enabled boolean no

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Fields of a 200 response:

Field Type
id integer
channel_id string or null
menu_key string or null
message_id string or null
title string
description string or null
options array of RoleOption
options[].role_id string
options[].label string
options[].key string or null
options[].emoji string or null
options[].description string or null
is_enabled boolean
published boolean

Update role menu

Section titled Update role menu

PUT /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}

Parameters

Section titled Parameters
Name In Type Required
menu_id path integer yes
org_slug path string yes

Request body

Section titled Request body

application/json (required)

Field Type Required
channel_id string or null no
menu_key string or null no
title string yes
description string or null no
options array of RoleOption no
options[].role_id string yes
options[].label string yes
options[].key string or null no
options[].emoji string or null no
options[].description string or null no
is_enabled boolean no

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Fields of a 200 response:

Field Type
id integer
channel_id string or null
menu_key string or null
message_id string or null
title string
description string or null
options array of RoleOption
options[].role_id string
options[].label string
options[].key string or null
options[].emoji string or null
options[].description string or null
is_enabled boolean
published boolean

Delete role menu

Section titled Delete role menu

DELETE /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}

Parameters

Section titled Parameters
Name In Type Required
menu_id path integer yes
org_slug path string yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Post the menu to its channel, or edit the message already posted for it

Section titled Post the menu to its channel, or edit the message already posted for it

POST /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}/publish

Post the menu to its channel, or edit the message already posted for it.

Parameters

Section titled Parameters
Name In Type Required
menu_id path integer yes
org_slug path string yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

The roles in the org's guild, so a menu can be built by picking not typing

Section titled The roles in the org's guild, so a menu can be built by picking not typing

GET /api/v1/orgs/{org_slug}/discord/roles

The roles in the org's guild, so a menu can be built by picking not typing.

Parameters

Section titled Parameters
Name In Type Required
org_slug path string yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

List staff links

Section titled List staff links

GET /api/v1/orgs/{org_slug}/discord/staff

Parameters

Section titled Parameters
Name In Type Required
org_slug path string yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

A 200 response is a list; each item has these fields:

Field Type
[].discord_user_id string
[].user_id integer or null
[].admin_user_id integer or null
[].role string
[].email string or null

Put staff link

Section titled Put staff link

PUT /api/v1/orgs/{org_slug}/discord/staff

Parameters

Section titled Parameters
Name In Type Required
org_slug path string yes

Request body

Section titled Request body

application/json (required)

Field Type Required
discord_user_id string yes
user_id integer or null no
admin_user_id integer or null no
role string no

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.

Fields of a 200 response:

Field Type
discord_user_id string
user_id integer or null
admin_user_id integer or null
role string
email string or null

Delete staff link

Section titled Delete staff link

DELETE /api/v1/orgs/{org_slug}/discord/staff/{discord_user_id}

Parameters

Section titled Parameters
Name In Type Required
discord_user_id path string yes
org_slug path string yes

Responses

Section titled Responses
Status Meaning
200 Success.
422 The request is not valid. detail lists each problem.