Skip to content

REST API Docs

Jump to bottom
zekro edited this page Jan 14, 2021 · 8 revisions

When enabled, shinpuru exposes a RESTful HTTP(S) API which exposes all functionalities which are also available to the web frontend.

Authentication

All requests to the API needs to be authenticated and authorized. To authenticate your requests, you need to generate an API token in shinpurus web interface.

To authenticate your requests, you need to add an Authentication header to your request with the token as Bearer token.

> GET /api/me HTTP/1.1
> Host: sp.zekro.de
> Authorization: bearer eyJhbGciOiJIUzI1...
> Accept: */*

Objects

The following are API models of objects returned from the API.

List Response

Requests which produce a list as response are wrapped in the following model:

Field Type Description
n int Number of items in the list.
data object[] The list of items.

Example:

{
  "n": 3,
  "data": [
    { ... },
    { ... },
    { ... }
  ]
}

User

A Discord User object.

The user objects has some more fields than listed below comming from the discordgo.User object which may not contain valid data.

Field Type Description
id string The snowflake ID of the user.
username string The username of the user.
avatar string The avatar hash of the user.
discriminator string The discriminator of the user.
bot boolean Whether the user is a bot.
avatar_url string Public url of the avatar image file.
created_at timestamp Timestamp of user account creation.
bot_owner boolean Whether the user is the specified bot owner.

Example:

{
  "id": "221905671296253953",
  "username": "zekro",
  "avatar": "a_752a15d01e68fb5f6f6ec83400461a6a",
  "discriminator": "0001",
  "bot": false,
  "avatar_url": "https://cdn.discordapp.com/avatars/221905671296253953/a_752a15d01e68fb5f6f6ec83400461a6a.gif",
  "created_at": "2016-09-04T08:38:26.976834845Z",
  "bot_owner": true
}

Member

A Discord Guild Member object.

The member objects has some more fields than listed below comming from the discordgo.Member object which may not contain valid data.

Field Type Description
guild_id string Snowflake ID of the Guild.
joined_at timestamp The timestamp when the member has joined the guild.
nick string The nick name of the user on this guild.
deaf boolean Whether the member is deafed on the guild.
mute boolean Whether the member is muted on the guild.
user User User model of the member.
roles string[] Role IDs of the member.
premium_since timestamp Timestamp since member has started boosting the server.
avatar_url string Public url of the avatar image file.
created_at timestamp Timestamp of user account creation.
dominance int The permission dominance of the member:
1 - Guild Admin
2 - Guild Owner
3 - Bot Owner
karma int Karma points for the member on the specified guild.
karma_total int Sum of all karma points across all guilds.

Example:

{
  "guild_id": "362162947738566657",
  "joined_at": "2020-04-09T20:53:47.658000+00:00",
  "nick": "zekuro senpai",
  "deaf": false,
  "mute": false,
  "user": {
    "id": "221905671296253953",
    "username": "zekro",
    "avatar": "a_752a15d01e68fb5f6f6ec83400461a6a",
    "discriminator": "0001",
    "bot": false
  },
  "roles": [
    "362166557721362433",
    "362169804146081802"
  ],
  "premium_since": "2020-04-15T09:24:24.174000+00:00",
  "avatar_url": "https://cdn.discordapp.com/avatars/221905671296253953/a_752a15d01e68fb5f6f6ec83400461a6a.gif",
  "created_at": "2016-09-04T08:38:26.976834845Z",
  "dominance": 1,
  "karma": 189,
  "karma_total": 784
}

Role

A Discord Guild Role object.

Field Type Description
id string The snowflake ID of the role.
name string The name of the role.
managed boolean Whether the role is managed.
mentionable boolean Whether the role is mentionable.
hoist boolean Whether the role is hoisted.
color int The color value of the role.
position int The position of the role.
permission int The permissions flags of the role.

Example:

{
  "id": "362169804146081802",
  "name": "Pleb",
  "managed": false,
  "mentionable": true,
  "hoist": true,
  "color": 0,
  "position": 8,
  "permissions": 104193600
}

Channel

A Discord Channel object.

Field Type Description
id string The snowflake ID of the channel.
guild_id string The snowflake ID of the guild the channel belongs to.
name string The name of the channel.
topic string The topic of the channel.
type int The type of the channel:
0 - text channel
2 - voice channel
4 - category
5 - news channel
6 - store channel
nfsw boolean Whether the channel is specified as NFSW.
icon string The icon hash of the channel.
position int The position of the channel.
bitrate int The bitrate of the channel (only for voice channels).
permission_overwrites PermissionOverwrite[] List of permission overwrites.
user_limit int The user limit of the channel.
parent_id string The ID of an optional parent category channel.

Example:

{
  "id": "526073401794756619",
  "guild_id": "362162947738566657",
  "name": "Gaming Private",
  "topic": "",
  "type": 2,
  "nsfw": false,
  "icon": "",
  "position": 15,
  "bitrate": 96000,
  "permission_overwrites": [
    {
      "id": "362162947738566657",
      "type": "role",
      "deny": 1049600,
      "allow": 2097152
    },
    {
      "id": "362166741373288448",
      "type": "role",
      "deny": 0,
      "allow": 1049600
    }
  ],
  "user_limit": 0,
  "parent_id": "384716117069004812"
}

Guild

A Discord Guild object.

Field Type Description
id string The snowflake ID of the guild.
name string The name of the guild.
icon string The icon hash of the guild.
region string The region of the guild.
afk_channel_id string The specified AFK channel of the guild.
owner_id string The snowflake ID of the owner of the guild.
joined_at string The timestamp the bot user has joined the guild.
splash string The splash of the guild.
member_count int The ammount of members on the guild.
verification_level int The required verification level of the guild.
large boolean Whether the guild is large.
unavaliable boolean Whether the guild is currently unavailable due to outage.
mfa_enabled boolean Whether the guild has MFA enabled for admins.
description string The description of the guild.
banner string The hash of the banner image of the guild.
premium_tier int The premium tier of the guild.
premium_subscription_ammount int The number of boosts the guild has.
roles Role[] List of roles of the guild.
channels Channel[] List of channels of the guild.
self_member Member The member object of the authenticated user on the guild.
icon_url string The resource URL of the guilds icon.
backups_enabled boolean Whether backup generation is enabled on this guild or not.
latest_backup_entry timestamp Time of the latest backup created.
invite_block_enabled boolean Whether invite blocking is enabled on this guild or not.

Example:

{
  "id": "362162947738566657",
  "name": "zekro's Privatbutze",
  "icon": "2bdf517d77a79b1d6ba60457bd00128e",
  "region": "europe",
  "afk_channel_id": "384315833104597005",
  "owner_id": "221905671296253953",
  "joined_at": "2019-01-21T18:59:09.405000+00:00",
  "splash": "",
  "member_count": 41,
  "verification_level": 4,
  "embed_enabled": false,
  "large": false,
  "unavailable": false,
  "mfa_level": 0,
  "description": "",
  "banner": "",
  "premium_tier": 1,
  "premium_subscription_count": 3,
  "roles": [
    {
      "id": "362162947738566657",
      "name": "@everyone",
      "managed": false,
      "mentionable": false,
      "hoist": false,
      "color": 0,
      "position": 0,
      "permissions": 37084224
    }
  ],
  "channels": [
    {
      "id": "596457051928920134",
      "guild_id": "362162947738566657",
      "name": "tft-stuff",
      "topic": "",
      "type": 0,
      "last_message_id": "598270124067127296",
      "last_pin_timestamp": "",
      "nsfw": false,
      "icon": "",
      "position": 14,
      "bitrate": 0,
      "recipients": null,
      "permission_overwrites": [
        {
          "id": "362162947738566657",
          "type": "role",
          "deny": 1024,
          "allow": 0
        }
      ],
      "user_limit": 0,
      "parent_id": "676181576249245697",
      "rate_limit_per_user": 0
    }
  ],
  "self_member": {
    "guild_id": "",
    "joined_at": "2020-04-09T20:53:47.658000+00:00",
    "nick": "",
    "deaf": false,
    "mute": false,
    "user": {
      "id": "221905671296253953",
      "email": "",
      "username": "zekro",
      "avatar": "a_752a15d01e68fb5f6f6ec83400461a6a",
      "locale": "",
      "discriminator": "0001",
      "token": "",
      "verified": false,
      "mfa_enabled": false,
      "bot": false
    },
    "roles": [
      "362166557721362433"
    ],
    "premium_since": "2020-04-15T09:24:24.174000+00:00",
    "avatar_url": "https://cdn.discordapp.com/avatars/221905671296253953/a_752a15d01e68fb5f6f6ec83400461a6a.gif",
    "created_at": "2016-09-04T08:38:26.976834845Z",
    "dominance": 1
  },
  "icon_url": "https://cdn.discordapp.com/icons/362162947738566657/2bdf517d77a79b1d6ba60457bd00128e.png",
  "backups_enabled": true,
  "latest_backup_entry": "2020-07-20T17:59:59+02:00",
  "invite_block_enabled": true
}

GuildReduced

A Discord Guild object reduced to fewer necessary fields.

Field Type Description
id string The snowflake ID of the guild.
name string The name of the guild.
icon string The icon hash of the guild.
region string The region of the guild.
owner_id string The snowflake ID of the owner of the guild.
joined_at string The timestamp the bot user has joined the guild.
member_count int The ammount of members on the guild.
icon_url string The resource URL of the guilds icon.

Example:

{
  "id": "362162947738566657",
  "name": "zekro's Privatbutze",
  "icon": "2bdf517d77a79b1d6ba60457bd00128e",
  "icon_url": "https://cdn.discordapp.com/icons/362162947738566657/2bdf517d77a79b1d6ba60457bd00128e.png",
  "region": "europe",
  "owner_id": "221905671296253953",
  "joined_at": "2019-01-21T18:59:09.405000+00:00",
  "member_count": 41
}

Report

A shinpuru Report record object.

Field Type Description
id string The snowflake ID of the report.
type int The type of the report:
0 - kick
1 - ban
2 - mute
4 - warn
5 - advertisement
guild_id string The snowflake ID of the guild the report belongs to.
executor_id string The snowflake ID of the executor of the report.
victim_id string The snowflake ID of the victim of the report.
message string The message of the report.
attachment_url string The resource URL of an optional attachment.
type_name string The name of the type of the report.
created timestamp The creation timestamp of the report.

Example:

{
  "id": "6678266303259619328",
  "type": 3,
  "guild_id": "547762913876639754",
  "executor_id": "221905671296253953",
  "victim_id": "455819141245304832",
  "message": "Bad language",
  "attachment_url": "https://sp-canary.zekro.de/imagestore/6678266279931420672.png",
  "type_name": "WARN",
  "created": "2020-07-03T09:29:57Z"
}

GuildSettings

A wrapper object for all guild specific preferences and settings.

Field Type Description
prefix string The guild specific prefix.
perms { string: string[] } A map of role-sepcific permission rules.
autorole string The snowflake ID of the set autorole.
modlogchannel string The snowflake ID of the set modlog channel.
voicelogchannel string The snowflake ID of the set voicelog channel.
joinmessagechannel string The snowflake ID of the channel where join messages are sent to.
joinmessagetext string The text which is sent into the join message channel when a user joins the guild.
leavemessagechannel string The snowflake ID of the channel where leave messages are sent to.
leavemessagetext string The text which is sent into the leave message channel when a user leaves the guild.

Example:

{
  "prefix": "!",
  "perms": {
    "362166741373288448": [
      "+sp.guild.mod.*",
      "-sp.guild.mod.ban",
      "-sp.guild.mod.kick"
    ],
    "406891236407115777": [
      "+sp.guild.config.*"
    ]
  },
  "autorole": "362169804146081802",
  "modlogchannel": "529279471350710314",
  "voicelogchannel": "454618414258978839",
  "joinmessagechannel": "381119295632965655",
  "joinmessagetext": "Welcome, [user]!",
  "leavemessagechannel": "",
  "leavemessagetext": ""
}

GlobalInviteSettings

An object which specifies the global invite settings.

Field Type Description
invite_url string The invite URL to the guild.
message string The displayed message.
guild Guild Guild object of the guild to be invited to.

Example:

{
  "invite_url": "https://discord.gg/sxUnqAn",
  "message": "Join the shinpuru Canary test guild to test the latest dev build!",
  "guild": {
    "id": "547762913876639754",
    "name": "shinpuru Canary Testing",
    "icon": "48684c3ad6e9b42793675fda9b09d64c",
    "region": "eu-central",
    "afk_channel_id": "",
    "owner_id": "221905671296253953",
    "joined_at": "",
    "splash": "",
    "member_count": 0,
    "verification_level": 0,
    "embed_enabled": false,
    "large": false,
    "unavailable": false,
    "mfa_level": 0,
    "description": "",
    "banner": "",
    "premium_tier": 0,
    "premium_subscription_count": 0,
    "roles": [
      {
        "id": "547762913876639754",
        "name": "@everyone",
        "managed": false,
        "mentionable": false,
        "hoist": false,
        "color": 0,
        "position": 0,
        "permissions": 104193601
      }
    ],
    "channels": null,
    "self_member": null,
    "icon_url": "https://cdn.discordapp.com/icons/547762913876639754/48684c3ad6e9b42793675fda9b09d64c.png"
  }
}

GlobalPresence

An object which specifies the bot instance's presence.

Field Type Description
game string The game text.
status string The online status:
- online
- away
- dnd
- invisible

Example:

{
  "game": "sp-canary.zekro.de",
  "status": "online"
}

SystemInfo

An object which wraps general information about the instance and the system where the instance is running on.

Field Type Description
version string The build version of shinpuru.
commit_hash string The commit hash of the build of shinpuru.
build_date timestamp The timestamp when the build was created.
go_version string The Go version used to compile the build.
uptime int Number of seconds since instance initialization.
uptime_str string Number of seconds since instance initialization as string.
os string The os identifier the instance is running on.
arch string The architecture the instance is running on.
cpus int Number of CPU threads allocated.
go_routines int Number of concurrently running goroutines.
stack_use int Number of bytes allocated on the stack.
stack_use_str string Number of bytes allocated on the stack as string.
heap_use int Number of bytes allocated on the heap.
heap_use_str string Number of bytes allocated on the heap as string.
bot_user_id string The ID of the bot account used.
bot_invite string The URL to invite the bot including needed permissions.
guilds int Number of guilds the instance is running on.

Example:

{
  "version": "0.17.0-99-g8c1ce6b",
  "commit_hash": "8c1ce6b9c07412067f955a654003c8e6f030353b",
  "build_date": "2020-07-03T09:23:40Z",
  "go_version": "go1.14.4",
  "uptime": 5308,
  "uptime_str": "5308",
  "os": "linux",
  "arch": "amd64",
  "cpus": 6,
  "go_routines": 29,
  "stack_use": 720896,
  "stack_use_str": "720896",
  "heap_use": 4866048,
  "heap_use_str": "4866048",
  "bot_user_id": "536916384026722314",
  "bot_invite": "https://discordapp.com/api/oauth2/authorize?client_id=536916384026722314&scope=bot&permissions=2080894065",
  "guilds": 9
}

APIToken

An object representing information about an API token.

Field Type Description
created timestamp The creation timestamp of the token.
expires timestamp The expiration timestamp of the token.
last_access timestamp The creation timestamp of the token.
hits int The number of authentications processed with this token.
token? string The token string. This data is only hydrated on token generation!

Example:

{
  "created": "2020-07-03T10:59:06.100282743Z",
  "expires": "2021-07-03T10:59:06.100282743Z",
  "last_access": "0001-01-01T00:00:00Z",
  "hits": 0,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MjUzMDk5NDYsImlhdCI6MTU5Mzc3Mzk0NiwiaXNzIjoic2hpbnB1cnUgdi4wLjE3LjAtOTktZzhjMWNlNmIiLCJuYmYiOjE1OTM3NzM5NDYsInN1YiI6IjIyMTkwNTY3MTI5NjI1Mzk1MyIsInNwX3NhbHQiOiJNd2RhUUxpcUJDNWZhNXFkaHdjdVpnPT0ifQ.2kifiXUHJTS-CNw-n8dUMSWD44Dwzb73EsvDtJjS8aE"
}

GuildBackup

An object wrapping details about a guild backup entry.

Field Type Description
guild_id string The ID of the guild.
timestamp timestamp The timestamp where the guild backup was created.
file_id string The file ID of the backup.

Example:

{
  "guild_id": "526196711962705925",
  "timestamp": "2020-07-21T10:13:12+02:00",
  "file_id": "6684769970976866304"
}

Endpoints

Get Self User

GET /api/me

Shows general user information about the authenticated user.

Example Response

{
  "id": "221905671296253953",
  "email": "",
  "username": "zekro",
  "avatar": "a_752a15d01e68fb5f6f6ec83400461a6a",
  "locale": "",
  "discriminator": "0001",
  "token": "",
  "verified": false,
  "mfa_enabled": false,
  "bot": false,
  "avatar_url": "https://cdn.discordapp.com/avatars/221905671296253953/a_752a15d01e68fb5f6f6ec83400461a6a.gif",
  "created_at": "2016-09-04T08:38:26.976834845Z",
  "bot_owner": true
}

Get Guild List

GET /api/guilds

Returns a list of guilds you and shinpuru are sharing.

Example Response

{
  "n": 2,
  "data": [
    {
      "id": "362162947738566657",
      "name": "zekro's Privatbutze",
      "icon": "2bdf517d77a79b1d6ba60457bd00128e",
      "icon_url": "https://cdn.discordapp.com/icons/362162947738566657/2bdf517d77a79b1d6ba60457bd00128e.png",
      "region": "europe",
      "owner_id": "221905671296253953",
      "joined_at": "2019-01-21T18:59:09.405000+00:00",
      "member_count": 41
    },
    {
      "id": "526196711962705925",
      "name": "5w4gg3rn4ut_5t4t10n",
      "icon": "5ec6d60236376005794d684c6e9a209a",
      "icon_url": "https://cdn.discordapp.com/icons/526196711962705925/5ec6d60236376005794d684c6e9a209a.png",
      "region": "eu-central",
      "owner_id": "221905671296253953",
      "joined_at": "2019-07-15T13:53:34.795000+00:00",
      "member_count": 7
    }
  ]
}

Get Guild

GET /api/guilds/:guildid

Returns details of a guild.

Example Response

{
  "id": "362162947738566657",
  "name": "zekro's Privatbutze",
  "icon": "2bdf517d77a79b1d6ba60457bd00128e",
  "region": "europe",
  "afk_channel_id": "384315833104597005",
  "owner_id": "221905671296253953",
  "joined_at": "2019-01-21T18:59:09.405000+00:00",
  "splash": "",
  "member_count": 41,
  "verification_level": 4,
  "embed_enabled": false,
  "large": false,
  "unavailable": false,
  "mfa_level": 0,
  "description": "",
  "banner": "",
  "premium_tier": 1,
  "premium_subscription_count": 3,
  "roles": [
    {
      "id": "362162947738566657",
      "name": "@everyone",
      "managed": false,
      "mentionable": false,
      "hoist": false,
      "color": 0,
      "position": 0,
      "permissions": 37084224
    },
    {
      "id": "362166557721362433",
      "name": "先生 (Sensei)",
      "managed": false,
      "mentionable": true,
      "hoist": true,
      "color": 16758016,
      "position": 15,
      "permissions": 512
    },
    {
      "id": "362166741373288448",
      "name": "先輩 (Senpai)",
      "managed": false,
      "mentionable": true,
      "hoist": true,
      "color": 3447003,
      "position": 10,
      "permissions": 2146958931
    }
  ],
  "channels": [
    {
      "id": "381119295632965655",
      "guild_id": "362162947738566657",
      "name": "general",
      "topic": "\n",
      "type": 0,
      "last_message_id": "720959238976962651",
      "last_pin_timestamp": "2019-06-20T04:05:01.229000+00:00",
      "nsfw": false,
      "icon": "",
      "position": 1,
      "bitrate": 0,
      "recipients": null,
      "permission_overwrites": [
        {
          "id": "362162947738566657",
          "type": "role",
          "deny": 1024,
          "allow": 0
        },
        {
          "id": "362169804146081802",
          "type": "role",
          "deny": 0,
          "allow": 1024
        }
      ],
      "user_limit": 0,
      "parent_id": "362162947738566658",
      "rate_limit_per_user": 0
    }
  ],
  "self_member": {
    "guild_id": "",
    "joined_at": "2020-04-09T20:53:47.658000+00:00",
    "nick": "",
    "deaf": false,
    "mute": false,
    "user": {
      "id": "221905671296253953",
      "email": "",
      "username": "zekro",
      "avatar": "a_752a15d01e68fb5f6f6ec83400461a6a",
      "locale": "",
      "discriminator": "0001",
      "token": "",
      "verified": false,
      "mfa_enabled": false,
      "bot": false
    },
    "roles": [
      "362166557721362433",
      "362169804146081802",
      "406891236407115777",
      "583411624514289675",
      "639385098021765131"
    ],
    "premium_since": "2020-04-15T09:24:24.174000+00:00",
    "avatar_url": "https://cdn.discordapp.com/avatars/221905671296253953/a_752a15d01e68fb5f6f6ec83400461a6a.gif",
    "created_at": "2016-09-04T08:38:26.976834845Z",
    "dominance": 1
  },
  "icon_url": "https://cdn.discordapp.com/icons/362162947738566657/2bdf517d77a79b1d6ba60457bd00128e.png"
}

Get Guild Members List

GET /api/guilds/:guildid/members

Returns a list of members of a guild. The upper limit of requestable items is 100, so this request must be paginated.

Query Parameters

Field Type Description
limit? int Maximum ammount of items per request (max = default = 100).
after? string Show items after the specified snowflake ID.

Example Response

{
  "n": 1,
  "data": [
    {
      "guild_id": "",
      "joined_at": "2020-04-09T20:53:47.658000+00:00",
      "nick": "",
      "deaf": false,
      "mute": false,
      "user": {
        "id": "221905671296253953",
        "email": "",
        "username": "zekro",
        "avatar": "a_752a15d01e68fb5f6f6ec83400461a6a",
        "locale": "",
        "discriminator": "0001",
        "token": "",
        "verified": false,
        "mfa_enabled": false,
        "bot": false
      },
      "roles": [
        "362166557721362433",
        "362169804146081802",
        "406891236407115777",
        "583411624514289675",
        "639385098021765131"
      ],
      "premium_since": "2020-04-15T09:24:24.174000+00:00",
      "avatar_url": "https://cdn.discordapp.com/avatars/221905671296253953/a_752a15d01e68fb5f6f6ec83400461a6a.gif",
      "created_at": "2016-09-04T08:38:26.976834845Z",
      "dominance": 0
    }
  ]
}

Get Guild Member

GET /api/guilds/:guildid/:memberid

Shows information about a specific memebr on the specified guild.

Example Response

{
  "guild_id": "362162947738566657",
  "joined_at": "2020-04-09T20:53:47.658000+00:00",
  "nick": "",
  "deaf": false,
  "mute": false,
  "user": {
    "id": "221905671296253953",
    "email": "",
    "username": "zekro",
    "avatar": "a_752a15d01e68fb5f6f6ec83400461a6a",
    "locale": "",
    "discriminator": "0001",
    "token": "",
    "verified": false,
    "mfa_enabled": false,
    "bot": false
  },
  "roles": [
    "362166557721362433",
    "362169804146081802",
    "406891236407115777",
    "583411624514289675",
    "639385098021765131"
  ],
  "premium_since": "2020-04-15T09:24:24.174000+00:00",
  "avatar_url": "https://cdn.discordapp.com/avatars/221905671296253953/a_752a15d01e68fb5f6f6ec83400461a6a.gif",
  "created_at": "2016-09-04T08:38:26.976834845Z",
  "dominance": 1
}

Get Guild Member Permissions

GET /api/guilds/:guildid/:memberid/permissions

Returns the calculated permissions rules array of the specified user on the specified guild.

Example Response

{
  "permissions": [
    "+sp.guild.config.*",
    "+sp.*",
    "+sp.guild.*",
    "+sp.etc.*",
    "+sp.chat.*"
  ]
}

Get Guild Member Permissions Allowed

GET /api/guilds/:guildid/:memberid/permissions/allowed

Returns a full list of all rule domains which are allowed for the specified user on the specified guild.

Example Response

{
  "n": 33,
  "data": [
    "sp.etc.help",
    "sp.guild.config.prefix",
    "sp.guild.config.perms",
    "sp.guild.mod.clear",
    "sp.guild.mod.mvall",
    "sp.etc.info",
    "sp.chat.say",
    "sp.chat.quote",
    "sp.game",
    "sp.guild.config.autorole",
    "sp.guild.mod.report",
    "sp.guild.config.modlog",
    "sp.guild.mod.kick",
    "sp.guild.mod.ban",
    "sp.chat.vote",
    "sp.chat.profile",
    "sp.etc.id",
    "sp.guild.mod.mute",
    "sp.guild.mod.ment",
    "sp.chat.notify",
    "sp.guild.config.voicelog",
    "sp.etc.bug",
    "sp.etc.stats",
    "sp.chat.twitch",
    "sp.guild.mod.ghostping",
    "sp.chat.exec",
    "sp.guild.admin.backup",
    "sp.guild.mod.inviteblock",
    "sp.chat.tag",
    "sp.guild.config.joinmsg",
    "sp.guild.config.leavemsg",
    "sp.etc.snowflake",
    "sp.chat.chanstats"
  ]
}

Get Guild Reports

GET /api/guilds/:guildid/reports

Displays a list of reports on the specified guild. This request can also be paginated.

Query Parameters

Field Type Description
limit? int Maximum ammount of items per request.
offset? int Ammount of items to be skipped.

Example Response

{
  "n": 1,
  "data": [
    {
      "id": "6678266303259619328",
      "type": 3,
      "guild_id": "547762913876639754",
      "executor_id": "221905671296253953",
      "victim_id": "455819141245304832",
      "message": "Bad language",
      "attachment_url": "https://sp-canary.zekro.de/imagestore/6678266279931420672.png",
      "type_name": "WARN",
      "created": "2020-07-03T09:29:57Z"
    }
  ]
}

Get Guild Reports Count

GET /api/guilds/:guildid/reports/counts

Returns the accumulated ammount of reports on this guild.

Example Response

{
  "count": 1
}

Get Guild Member Reports

GET /api/guilds/:guildid/:memberid/reports

Displays a list of reports for the specified member on the specified guild. This request can also be paginated.

Query Parameters

Field Type Description
limit? int Maximum ammount of items per request.
offset? int Ammount of items to be skipped.

Example Response

{
  "n": 1,
  "data": [
    {
      "id": "6678266303259619328",
      "type": 3,
      "guild_id": "547762913876639754",
      "executor_id": "221905671296253953",
      "victim_id": "455819141245304832",
      "message": "Bad language",
      "attachment_url": "https://sp-canary.zekro.de/imagestore/6678266279931420672.png",
      "type_name": "WARN",
      "created": "2020-07-03T09:29:57Z"
    }
  ]
}

Get Guild Reports Count

GET /api/guilds/:guildid/:memberid/reports/counts

Returns the accumulated ammount of reports on this guild for the specified member.

Example Response

{
  "count": 1
}

Get Guild Settings

GET /api/guilds/:guildid/settings

Returns the settings and preferences for the specified guild.

Example Response

{
  "prefix": "!",
  "perms": {
    "608577686528458762": [
      "+sp.guild.config.*"
    ],
    "608584907014537246": [
      "+sp.guild.mod.*"
    ]
  },
  "autorole": "547772764921004043",
  "modlogchannel": "547773902357790730",
  "voicelogchannel": "547774364968288296",
  "joinmessagechannel": "Welcome [ment]! :heart:",
  "joinmessagetext": "547762913876639757",
  "leavemessagechannel": "",
  "leavemessagetext": ""
}

Set Guild Settings

POST /api/guilds/:guildid/settings

Returns the settings and preferences for the specified guild.

Requires Permissions

  • sp.guild.config.autorole
  • sp.guild.config.modlog
  • sp.guild.config.prefix
  • sp.guild.config.voicelog
  • sp.guild.config.joinmsg
  • sp.guild.config.leavemsg

Body Parameters

Only set parameters will be updated. If you want to actively reset a value, you need to set the value to __RESET__.

Field Type Description
prefix string The guild specific prefix.
autorole string The snowflake ID of the set autorole.
modlogchannel string The snowflake ID of the set modlog channel.
voicelogchannel string The snowflake ID of the set voicelog channel.
joinmessagechannel string The snowflake ID of the channel where join messages are sent to.
joinmessagetext string The text which is sent into the join message channel when a user joins the guild.
leavemessagechannel string The snowflake ID of the channel where leave messages are sent to.
leavemessagetext string The text which is sent into the leave message channel when a user leaves the guild.

Example Response

{
  "code": 200,
  "message": "ok"
}

Get Guild Permissions

GET /api/guilds/:guildid/permissions

Returns the defined rule sets for roles on the guild.

Example Response

{
  "608577686528458762": [
    "+sp.guild.config.*"
  ],
  "608584907014537246": [
    "+sp.guild.mod.*"
  ]
}

Set Guild Permissions

POST /api/guilds/:guildid/permissions

Defines a new rule for specified role IDs.

Requires Permissions

  • sp.guild.config.perms

Body Parameters

Field Type Description
perm string The permission rule, for example:
+sp.guild.mod.*
roles string[] The list of roles IDs to set the rule for.

Example Response

{
  "code": 200,
  "message": "ok"
}

Create Member Report

POST /api/guilds/:guildid/:memberid/reports

Records a report for a member on the specified guild.

Required Permissions

  • sp.guild.mod.report

Body Parameters

Field Type Description
type int Type of the report. Only these two are available for manual spec:
3 - WARN
4 - AD
reason string The issue reason.
attachment? string An image URL as report attachment.

Example Response

{
  "id": "6678266303259619328",
  "type": 3,
  "guild_id": "547762913876639754",
  "executor_id": "221905671296253953",
  "victim_id": "455819141245304832",
  "message": "Bad language",
  "attachment_url": "https://sp-canary.zekro.de/imagestore/6678266279931420672.png",
  "type_name": "WARN",
  "created": "2020-07-03T09:29:57Z"
}

Create Member Kick Issue

POST /api/guilds/:guildid/:memberid/kick

Issues a member kick which is recorded with a kick report.

Required Permissions

  • sp.guild.mod.kick

Body Parameters

Field Type Description
reason string The issue reason.
attachment? string An image URL as report attachment.

Example Response

{
  "id": "6678266303259619328",
  "type": 0,
  "guild_id": "547762913876639754",
  "executor_id": "221905671296253953",
  "victim_id": "455819141245304832",
  "message": "Bad language",
  "attachment_url": "https://sp-canary.zekro.de/imagestore/6678266279931420672.png",
  "type_name": "KICK",
  "created": "2020-07-03T09:29:57Z"
}

Create Member Ban Issue

POST /api/guilds/:guildid/:memberid/ban

Issues a member ban which is recorded with a ban report.

Required Permissions

  • sp.guild.mod.ban

Body Parameters

Field Type Description
reason string The issue reason.
attachment? string An image URL as report attachment.

Example Response

{
  "id": "6678266303259619328",
  "type": 1,
  "guild_id": "547762913876639754",
  "executor_id": "221905671296253953",
  "victim_id": "455819141245304832",
  "message": "Bad language",
  "attachment_url": "https://sp-canary.zekro.de/imagestore/6678266279931420672.png",
  "type_name": "BAN",
  "created": "2020-07-03T09:29:57Z"
}

Get Guild Backups

GET /api/guilds/:guildid/backups

Returns a list of backups created on this guild.

Example Response

{
  "n": 2,
  "data": [
    {
      "guild_id": "526196711962705925",
      "timestamp": "2020-07-20T17:59:59+02:00",
      "file_id": "6684525051657994240"
    },
    {
      "guild_id": "526196711962705925",
      "timestamp": "2020-07-21T10:12:15+02:00",
      "file_id": "6684769728223133696"
    }
  ]
}

Download Guild Backups

GET /api/guilds/:guildid/backups/:backupid/download

Returns the gzip compressed guild backup JSON file in the response body.

Example Response

HTTP/1.1 200 OK
Server: shinpuru v.1.1.0
Date: Tue, 21 Jul 2020 08:21:58 GMT
Content-Type: application/gzip
Content-Length: 1567
X-Content-Type-Options: nosniff
Cache-Control: public, max-age=86400‬, immutable
{ gzip compressed body data }

Toggle Guild Backup Enabled

POST /api/guilds/:guildid/backups/toggle

Toggle guild backup generation.

Required Permissions

  • sp.guild.admin.backup

Body Parameters

Field Type Description
enabled boolean Whether or not to enable guild backup generation.

Example Response

{
  "code": 200,
  "message": "ok"
}

Toggle Guild Invite Block Enabled

POST /api/guilds/:guildid/inviteblock

Toggle guild invite block enable.

Required Permissions

  • sp.guild.mod.inviteblock

Body Parameters

Field Type Description
enabled boolean Whether or not to enable invite blocking or not.

Example Response

{
  "code": 200,
  "message": "ok"
}

Get Guild Karma Scoreboard

GET /api/guilds/:guildid/scoreboard

Returns a list of members sorted decremented by their karma value on the specified guild.

Field Type Description
limit number The maximum ammount of scoreboard entries to return. 
{
  "n": 1,
  "data": [
    {
      "member": {
        "guild_id": "526196711962705925",
        "joined_at": "2020-07-22T10:52:36.424682+00:00",
        "nick": "",
        "deaf": false,
        "mute": false,
        "user": {
          "id": "661175627105173514",
          "email": "",
          "username": "0x7a656b726f",
          "avatar": "36c7f473d55f7cf8ff39675bed5c8ebb",
          "locale": "",
          "discriminator": "7375",
          "token": "",
          "verified": false,
          "mfa_enabled": false,
          "bot": false
        },
        "roles": [],
        "premium_since": "",
        "avatar_url": "https://cdn.discordapp.com/avatars/661175627105173514/36c7f473d55f7cf8ff39675bed5c8ebb.png",
        "created_at": "2019-12-30T13:22:10.706953551+01:00",
        "dominance": 0,
        "karma": 0,
        "karma_total": 0
      },
      "value": 126
    }
  ]
}

Get Report

GET /api/reports/:caseid

Returns information about a report by case ID.

Example Response

{
  "id": "6678266303259619328",
  "type": 1,
  "guild_id": "547762913876639754",
  "executor_id": "221905671296253953",
  "victim_id": "455819141245304832",
  "message": "Bad language",
  "attachment_url": "https://sp-canary.zekro.de/imagestore/6678266279931420672.png",
  "type_name": "BAN",
  "created": "2020-07-03T09:29:57Z"
}

Revoke Report

POST /api/reports/:caseid/revoke

Revoke a report.

Required Permissions

  • sp.guild.mod.report

Body Parameters

Field Type Description
reason string The report revokation reason.

Example Response

{
  "code": 200,
  "message": "ok"
}

Get Bot Presence

GET /api/settings/presence

Displays the bot instance set presence.

Example Response

{
  "game": "sp-canary.zekro.de",
  "status": "online"
}

Set Bot Presence

POST /api/settings/presence

Required Permissions

  • sp.game

Set the bot instance presence.

Body Parameters

Field Type Description
game string The presence game.
status string The online status:
- online
- away
- dnd
- invisible

Example Response

{
  "game": "sp-canary.zekro.de",
  "status": "online"
}

Get No Guild Invite Setting

GET /api/settings/noguildinvite

Displays the guild invite set which is displayed when soneone hits the web interface who does not share any guild with the bot instance account.

Example Response

{
    "invite_url": "https://discord.gg/sxUnqAn",
  "message": "Join the shinpuru Canary test guild to test the latest dev build!",
  "guild": {
    "id": "547762913876639754",
    "name": "shinpuru Canary Testing",
    "icon": "48684c3ad6e9b42793675fda9b09d64c",
    "region": "eu-central",
    "afk_channel_id": "",
    "owner_id": "221905671296253953",
    "joined_at": "",
    "splash": "",
    "member_count": 0,
    "verification_level": 0,
    "embed_enabled": false,
    "large": false,
    "unavailable": false,
    "mfa_level": 0,
    "description": "",
    "banner": "",
    "premium_tier": 0,
    "premium_subscription_count": 0,
    "roles": [
      {
        "id": "547762913876639754",
        "name": "@everyone",
        "managed": false,
        "mentionable": false,
        "hoist": false,
        "color": 0,
        "position": 0,
        "permissions": 104193601
      }
    ],
    "channels": null,
    "self_member": null,
    "icon_url": "https://cdn.discordapp.com/icons/547762913876639754/48684c3ad6e9b42793675fda9b09d64c.png"
  }
}

Set No Guild Invite Setting

POST /api/settings/noguildinvite

Set the guild invite set which is displayed when soneone hits the web interface who does not share any guild with the bot instance account.

Required Permissions

  • sp.noguildinvite

Body Parameters

Field Type Description
guild_id string The snowflake ID of the guild to be invited to.
message string The message displayed on the web interface page.
invite_code? string Set an already defined invite code. Otherwise, a new invite will be generated by shinpuru.

Example Response

{
  "code": 200,
  "message": "ok"
}

Get System and Instance Information

POST /api/sysinfo

Returns detailed information about the shinpuru instance and the system it is running on.

Example Response

{
  "version": "0.17.0-100-g8faeb1a",
  "commit_hash": "8faeb1a5ab0aa574e896ba0f67372e096984b4e6",
  "build_date": "2020-07-03T11:04:01Z",
  "go_version": "go1.14.4",
  "uptime": 44384,
  "uptime_str": "44384",
  "os": "linux",
  "arch": "amd64",
  "cpus": 6,
  "go_routines": 20,
  "stack_use": 884736,
  "stack_use_str": "884736",
  "heap_use": 5136384,
  "heap_use_str": "5136384",
  "bot_user_id": "536916384026722314",
  "bot_invite": "https://discordapp.com/api/oauth2/authorize?client_id=536916384026722314&scope=bot&permissions=2080894065",
  "guilds": 9
}

Get API Token

GET /api/token

Returns information about a generated API token for the authenticated user. This does not contain the API token itself!

Example Response

{
  "created": "2020-07-03T10:59:52.18640661Z",
  "expires": "2021-07-03T10:59:52.18640661Z",
  "last_access": "2020-07-05T09:43:40.923373646Z",
  "hits": 34
}

Post API Token

POST /api/token

Create a new API token for the authenticated user which is returned in the response. If a token was generated before, the old token will be rendered invalid.

Example Response

{
  "created": "2020-07-03T10:59:06.100282743Z",
  "expires": "2021-07-03T10:59:06.100282743Z",
  "last_access": "0001-01-01T00:00:00Z",
  "hits": 0,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MjUzMDk5NDYsImlhdCI6MTU5Mzc3Mzk0NiwiaXNzIjoic2hpbnB1cnUgdi4wLjE3LjAtOTktZzhjMWNlNmIiLCJuYmYiOjE1OTM3NzM5NDYsInN1YiI6IjIyMTkwNTY3MTI5NjI1Mzk1MyIsInNwX3NhbHQiOiJNd2RhUUxpcUJDNWZhNXFkaHdjdVpnPT0ifQ.2kifiXUHJTS-CNw-n8dUMSWD44Dwzb73EsvDtJjS8aE"
}

Unset API Token

DELETE /api/token

Deletes the generated API token for the authenticated user and makes it invalid.

Example Response

{
  "code": 200,
  "message": "ok"
}

Imagestore

shinpuru exposes an endpoint exposing images saved in the imagestore. These image resources are publicly available without authentication to embed the images in Discord message embeds.

This is the endpoint to access images from the imagestore:

GET /imagestore/:imgid

imgid is the snowflake ID of the image.

Utility API

shinpuru also exposes a utility API which is also accessable without authentication. These endpoints are general purpose utilities.

Color Image Generator

Generates a PNG image with the passed hexcode HEX RGBA color.

GET /api/util/color/:hexcode

Query Parameters

Field Type Description
size? int/string Image size. This value can either be one or two dimensional:
- ?size=64 → 64x64 px
- ?size=128x64 → 128x64 px

Example Response

HTTP/1.1 200 OK
Date: Wed, 12 Aug 2020 09:08:48 GMT
Content-Type: image/png
Content-Length: 161
Connection: keep-alive
X-Content-Type-Options: nosniff
Cache-Control: public, max-age=31536000, immutable
Etag: "cb75bd95eeb110119df52872d583e827d349607f"

{ img data }

Getting Started

Documentation

Self-Hosting

Clone this wiki locally