# 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.

# 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.

← Reference Models →