The API itself is stable, but this document (the OpenAPI description) is still subject to change, and may be updated, corrected or restructured in the future (as long as it's still coherent with the real API).
A unique identifier for a system or a member, as a randomly generated string of five lowercase letters.
These IDs are guaranteed to be globally unique for the given model type (a system can have the same ID as a member, but two systems or two members can never share an ID).
The IDs can on rare occasions change - eg. if a profane word is generated and later regenerated, or as a potential future Patreon perk. However, it's still reasonable to assume that the IDs are constant, and that tey won't change without the user's knowledge, so it's safe to store in things like settings menus and config files.
System:
properties:
id:
$ref:"#/components/schemas/ID"
name:
type:string
nullable:true
maxLength:100
description:The user-provided name of the system.
example:"Boxes of Foxes"
description:
type:string
nullable:true
maxLength:1000
description:|
The user-provided system description.
May contain rich text in Markdown, including standard Markdown-formatted links, or Discord-formatted emoji/user/channel references.
example:|-
This system is very cool.
It has cool people.
tag:
type:string
maxLength:78
description:|
The system tag, which is appended to the names (or display names, if set) of members when proxying through the bot.
A space will automatically be inserted between the name and the tag, so no need to include one at the start.
The character limit here is 78, as Discord's name length limit for webhooks is 80 characters. A 78-character system tag is thus the longest tag that can still accomodate a single-letter member name and the separating space.
nullable:true
example:"| BoF"
avatar_url:
type:string
format:url
nullable:true
maxLength:256
example:"https://i.imgur.com/Abcdefg.png"
description:|
A link to the avatar/icon of the system.
If used for proxying, the image must be at most 1000 pixels in width *and* height, and at most 1 MiB in size. This restriction is on Discord's end and is not verified through the API (it's simply stored as a string).
tz:
type:string
format:timezone
nullable:true
default:UTC
example:America/New_York
description:|
The system's registered time zone as an Olson time zone ID.
This is used in the bot to convert various time stamps in commands on behalf of this system.
created:
type:string
format:date-time
readOnly:true
description:The creation timestamp of the system.
description_privacy:
allOf:
- $ref:"#/components/schemas/PrivacySetting"
- description:|
The system's description privacy setting, either "public" or "private".
If this is set to "private", the field `description` will be returned as `null` on all requests not authorized with this system's token.
In addition, this field will be returned as `null` if the request is not authorized with this system's token.
Because of this, there is no way for an unauthorized user to tell the difference between a private description and a `null` description - this is intentional.
description:The member's "display name", which will override the member's normal name when proxying.
nullable:true
example:Myriad 'Big Boss' Kit
description:
type:string
maxLength:1000
description:|
The user-provided description of the member.
May contain rich text in Markdown, including standard Markdown-formatted links, or Discord-formatted emoji/user/channel references.
If this member is private, and the request is not authorized with the member's system token, this field will always be returned as `null`.
example:Myriad is very cool and rad, and they love snuggling.
color:
type:string
format:color
minLength:6
maxLength:6
nullable:true
pattern:"^[0-9A-Fa-f]{6}$"
description:|
The member's "color", displayed on member cards, as a 6-character hexadecimal color code (no leading#).
If this member is private, and the request is not authorized with the member's system token, this field will always be returned as `null`.
example:"FF0000"
birthday:
type:string
format:date
example:"2018-07-11"
nullable:true
description:|
The user-provided birthdate of the member.
"Year-less"birthdays are supported. In this case, the year should be set to `0004`, and that specific year should be special-cased and hidden from the user. Previous versions used the year `0001` for the same purpose, and this value may still be both read and written with the API and should be treated the same as `0004`.
The year `0004` was chosen because it is a leap year in the Gregorian calendar, and thus the date `0004-02-29` can be properly represented.
If this member is private, and the request is not authorized with the member's system token, this field will always be returned as `null`.
pronouns:
type:string
maxLength:100
example:"they/them or xe/xem"
nullable:true
description:|
The user-provided pronouns of the member.
There is no specific schema, just a freeform text field.
If this member is private, and the request is not authorized with the member's system token, this field will always be returned as `null`.
avatar_url:
type:string
format:url
nullable:true
maxLength:256
example:"https://i.imgur.com/Abcdefg.png"
description:|
A link to the avatar/icon of the member.
If used for proxying, the image must be at most 1000 pixels in width *and* height, and at most 1 MiB in size. This restriction is on Discord's end and is not verified through the API (it's simply stored as a string).
At the moment, it's still included in member objects, with a value that mirrors the `visibility` field. Writing to this field will set *every* privacy setting to the written value.
example:public
deprecated:true
visibility:
allOf:
- $ref:"#/components/schemas/PrivacySetting"
- description:|
The member's current visibility, either "public" or "private".
If this is set to "private", the member will not appear in public member lists. It can still be looked up using its 5-character member ID, but will return limited information.
In addition, this field will be returned as `null` if the request is not authorized with this system's token.
example:public
name_privacy:
allOf:
- $ref:"#/components/schemas/PrivacySetting"
- description:|
The member's current name privacy setting, either "public" or "private".
If this is set to "private", the member's returned `name` will be replaced by their `display_name` when applicable.
In addition, this field will be returned as `null` if the request is not authorized with this system's token.
Because of this, there is no way for an unauthorized user to tell the difference between a private name being replaced by the display name, and an empty display name with the name set - this is intentional.
example:public
description_privacy:
allOf:
- $ref:"#/components/schemas/PrivacySetting"
- description:|
The member's current description privacy setting, either "public" or "private".
If this is set to "private", the field `description` will be returned as `null` on all requests not authorized with this system's token.
In addition, this field will be returned as `null` if the request is not authorized with this system's token.
Because of this, there is no way for an unauthorized user to tell the difference between a private description and a `null` description - this is intentional.
example:public
pronouns_privacy:
allOf:
- $ref:"#/components/schemas/PrivacySetting"
- description:|
The member's current pronouns privacy setting, either "public" or "private".
If this is set to "private", the field `pronouns` will be returned as `null` on all requests not authorized with this system's token.
In addition, this field will be returned as `null` if the request is not authorized with this system's token.
Because of this, there is no way for an unauthorized user to tell the difference between private pronouns and `null` pronouns - this is intentional.
example:public
birthday_privacy:
allOf:
- $ref:"#/components/schemas/PrivacySetting"
- description:|
The member's current birthday privacy setting, either "public" or "private".
If this is set to "private", the field `birthday` will be returned as `null` on all requests not authorized with this system's token.
In addition, this field will be returned as `null` if the request is not authorized with this system's token.
Because of this, there is no way for an unauthorized user to tell the difference between a private birthday and a `null` birthday - this is intentional.
example:public
metadata_privacy:
allOf:
- $ref:"#/components/schemas/PrivacySetting"
- description:|
The member's current metadata privacy setting, either "public" or "private".
If this is set to "private", the field `created` on all requests not authorized with this system's token.
description:The creation timestamp of the member. May be returned as `null` depending on the value of `metadata_privacy` and the request authorization.
description:A privacy setting for systems or members, either public or private. May occasionally be `null` in cases where you are not authorized to view the privacy setting's state.
An object containing information about a proxied message, including message, user and channel IDs, as well as the system and member it's related to.
For privacy and performance reasons, this endpoint does not return the *contents* of the original message. This data isn't stored in the database either way - but given the channel and message ID, it can be fetched from Discord's own API.
properties:
timestamp:
type:string
format:date-time
readOnly:true
description:The time the message was proxied.
id:
allOf:
- $ref:"#/components/schemas/Snowflake"
- description:"The ID of the proxied webhook message posted by PluralKit."
