PluralKit/docs/content/api/endpoints.md

name	permalink
Endpoints	/api/endpoints

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.

---

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

PUT /members/{memberRef}/groups

::: warning Not all HTTP implementations support PUT requests with a body. If yours does not, consider using the Add Member To Group endpoint instead. :::

Remove Member From Groups

DELETE /members/{memberRef}/groups

::: warning Not all HTTP implementations support DELETE requests with a body. If yours does not, consider using the Remove Member From Group endpoint instead. :::

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

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

Add Member To Group

PUT /groups/{groupRef}/members/{memberRef}

Add Members To Group

PUT /groups/{groupRef}/members

::: warning Not all HTTP implementations support PUT requests with a body. If yours does not, consider using the Add Member To Group endpoint instead. :::

Remove Member From Group

DELETE /groups/{groupRef}/members/{memberRef}

Remove Members From Group

DELETE /groups/{groupRef}/members

::: warning Not all HTTP implementations support DELETE requests with a body. If yours does not, consider using the Remove Member From Group endpoint instead. :::

---

Switches

switchRef must be a switch's UUID. On POST/PATCH/DELETE endpoints, systemRef must be @me.

Get System Switches

GET /systems/{systemRef}/switches

Query String Parameters

key	type	description
before	timestamp	date to get latest switch from (inclusive)
limit	int	number of switches to get

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.