# Endpoints
The base URL for the PluralKit API is https://api.pluralkit.me/v2. Endpoint URLs should be added to the base URL to get a full URL to query.
All query string parameters are optional, but if present they require a non-null value.
# Systems
systemRef can be a system's short (5-character) ID, a system's UUID, the ID of a Discord account linked to the system, or the string @me to refer to the currently authenticated system.
# Get System
GET /systems/{systemRef}
Returns a system object.
# Update System
PATCH /systems/{systemRef}
Takes a partial system object.
Returns a system object.
# Get System Settings
GET /systems/{systemRef}/settings
Returns a system settings object.
# Update System Settings
PATCH /systems/{systemRef}/settings
Takes a partial system settings object.
Returns a system settings object.
# Get System Guild Settings
GET /systems/@me/guilds/{guild_id}
Returns a system guild settings object.
TIP
You must already have updated per-guild settings for your system in the target guild before being able to get or update them from the API.
# Update System Guild Settings
PATCH /systems/@me/guilds/{guild_id}
Takes a partial system guild settings object.
Returns a system guild settings object on success.
# Get System Autoproxy Settings
GET /systems/@me/autoproxy
Query String Parameters
| name | type |
|---|---|
| guild_id? | snowflake |
| channel_id? | snowflake |
Returns an autoproxy settings object on success.
WARNING
Currently, only autoproxy with guild_id is supported. The API will return an error message if you specify channel_id, or do not specify a guild_id.
# Update System Autoproxy Settings
PATCH /systems/@me/autoproxy
Query String Parameters
| name | type |
|---|---|
| guild_id? | snowflake |
| channel_id? | snowflake |
Takes a partial autoproxy settings object.
Returns an autoproxy settings object on success.
WARNING
Currently, only autoproxy with guild_id is supported. The API will return an error message if you specify channel_id, or do not specify a guild_id.
# Members
memberRef can be a member's short (5-character ID) or a member's UUID.
# Get System Members
GET /systems/{systemRef}/members
Returns a list of member objects.
# Create Member
POST /members
Takes a partial member object as input. Key name is required.
Returns a member object on success.
# Get Member
GET /members/{memberRef}
Returns a member object.
# Update Member
PATCH /members/{memberRef}
Takes a partial member object as input.
Returns a member object on success.
# Delete Member
DELETE /members/{memberRef}
Returns 204 No Content on success.
# Get Member Groups
GET /members/{memberRef}/groups
# Add Member To Groups
POST /members/{memberRef}/groups/add
Takes a list of group references as input. Returns 204 No Content on success.
# Remove Member From Groups
POST /members/{memberRef}/groups/remove
TIP
If you want to remove all groups from a member, consider using the Overwrite Member Groups endpoint instead.
Takes a list of group references as input. Returns 204 No Content on success.
# Overwrite Member Groups
POST /members/{memberRef}/groups/overwrite
Takes a list of group references as input. (An empty list is accepted.) Returns 204 No Content on success.
# Get Member Guild Settings
GET /members/{memberRef}/guilds/{guild_id}
Returns a member guild settings object.
TIP
You must already have updated per-guild settings for the target member in the target guild before being able to get or update them from the API.
# Update Member Guild Settings
PATCH /members/{memberRef}/guilds/{guild_id}
Takes a partial member guild settings object.
Returns a member guild settings object on success.
# Groups
groupRef can be a group's short (5-character ID) or a group's UUID.
# Get System Groups
GET /systems/{systemRef}/groups
Query String Parameters
| name | type | description |
|---|---|---|
| with_members | boolean | includes members key with array of member UUIDs in each group object |
Returns a list of group objects.
# Create Group
POST /groups
Takes a partial group object as input. Key name is required.
Returns a group object on success, or an error object on failure.
# Get Group
GET /groups/{groupRef}
Returns a group object.
# Update Group
PATCH /groups/{groupRef}
Takes a partial group object as input.
Returns a group object on success, or an error object on failure.
# Delete Group
DELETE /groups/{groupRef}
Returns 204 No Content on success.
# Get Group Members
GET /groups/{groupRef}/members
Returns an array of member objects.
# Add Members To Group
POST /groups/{groupRef}/members/add
Takes an array of member references as input. Returns 204 No Content on success.
# Remove Member From Group
POST /groups/{groupRef}/members/remove
TIP
If you want to remove all members from a group, consider using the Overwrite Group Members endpoint instead.
Takes an array of member references as input. Returns 204 No Content on success.
# Overwrite Group Members
POST /groups/{groupRef}/members/overwrite
Takes an array of member references as input. (An empty list is accepted.) Returns 204 No Content on success.
# Switches
switchRef must be a switch's UUID. systemRef can be a system's short (5-character) ID, a system's UUID, the ID of a Discord account linked to the system, or the string @me to refer to the currently authenticated system.
# Get System Switches
GET /systems/{systemRef}/switches
Query String Parameters
| key | type | description |
|---|---|---|
| before | timestamp | date to get latest switch from |
| limit | int | number of switches to get (defaults to 100) |
WARNING
This endpoint returns at most 100 switches. To get more switches, make multiple requests using the before parameter for pagination.
Returns a switch object containing a list of IDs.
# Get Current System Fronters
GET /systems/{systemRef}/fronters
Returns a switch object containing a list of member objects.
# Create Switch
POST /systems/{systemRef}/switches
JSON Body Parameters
| key | type | description |
|---|---|---|
| ?timestamp | datetime* | when the switch started |
| members | list of strings** | members present in the switch (or empty list for switch-out) |
* Defaults to "now" when missing.
** Can be short IDs or UUIDs.
# Get Switch
GET /systems/{systemRef}/switches/{switchRef}
Returns a switch object containing a list of member objects.
# Update Switch
PATCH /systems/{systemRef}/switches/{switchRef}
JSON Body Parameters
| key | type | description |
|---|---|---|
| timestamp | datetime | when the switch started |
Returns a switch object containing a list of member objects on success.
# Update Switch Members
PATCH /systems/{systemRef}/switches/{switchRef}/members
Takes a list of member short IDs or UUIDs as input.
Returns a switch object containing a list of member objects on success.
# Delete Switch
DELETE /systems/{systemRef}/switches/{switchRef}
Returns 204 No Content on success.
# Misc
# Get Proxied Message Information
GET /messages/{message}
Message can be the ID of a proxied message, or the ID of the message that sent the proxy.
Returns a message object.