2021-10-22 15:20:26 +00:00
---
name: Endpoints
permalink: /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.
2021-11-17 15:00:57 +00:00
All query string parameters are optional, but if present they require a non-null value.
2021-10-22 15:20:26 +00:00
---
## 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 ](/api/models#system-model ).
### Update System
PATCH `/systems/{systemRef}`
Takes a partial [system object ](/api/models#system-model ).
Returns a [system object ](/api/models#system-model ).
2021-11-30 02:35:21 +00:00
### Get System Settings
GET `/systems/{systemRef}/settings`
Returns a [system settings object ](/api/models#system-settings-model ).
### Update System Settings
PATCH `/systems/{systemRef}/settings`
Takes a partial [system settings object ](/api/models#system-settings-model ).
Returns a [system settings object ](/api/models#system-settings-model ).
2021-10-22 15:20:26 +00:00
### Get System Guild Settings
GET `/systems/@me/guilds/{guild_id}`
2021-11-08 16:15:48 +00:00
Returns a [system guild settings ](/api/models#system-guild-settings-model ) object.
2021-10-22 15:20:26 +00:00
2021-10-22 21:54:47 +00:00
::: tip
2021-10-22 15:20:26 +00:00
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}`
2021-11-08 16:15:48 +00:00
Takes a partial [system guild settings ](/api/models#system-guild-settings-model ) object.
2021-10-22 15:20:26 +00:00
2021-11-08 16:15:48 +00:00
Returns a [system guild settings ](/api/models#system-guild-settings-model ) object on success.
2021-10-22 15:20:26 +00:00
2022-06-02 17:32:31 +00:00
### Get System Autoproxy Settings
GET `/systems/@me/autoproxy`
Query String Parameters
|name|type|
|---|---|
|guild_id?|snowflake|
|channel_id?|snowflake|
Returns an [autoproxy settings ](/api/models/#autoproxy-settings-model ) 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 ](/api/models/#autoproxy-settings-model ) object.
Returns an [autoproxy settings ](/api/models/#autoproxy-settings-model ) 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` .
:::
2021-10-22 15:20:26 +00:00
---
## 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 ](/api/models#member-model ).
### Create Member
POST `/members`
Takes a partial [member object ](/api/models#member-model ) as input. Key `name` is required.
Returns a [member object ](/api/models#member-model ) on success.
### Get Member
GET `/members/{memberRef}`
Returns a [member object ](/api/models#member-model ).
### Update Member
PATCH `/members/{memberRef}`
Takes a partial [member object ](/api/models#member-model ) as input.
Returns a [member object ](/api/models#member-model ) on success.
### Delete Member
DELETE `/members/{memberRef}`
Returns 204 No Content on success.
### Get Member Groups
GET `/members/{memberRef}/groups`
### Add Member To Groups
2021-10-30 22:16:18 +00:00
POST `/members/{memberRef}/groups/add`
2021-10-22 15:20:26 +00:00
2021-10-30 22:16:18 +00:00
Takes a list of group references as input. Returns 204 No Content on success.
2021-10-22 15:20:26 +00:00
### Remove Member From Groups
2021-10-30 22:16:18 +00:00
POST `/members/{memberRef}/groups/remove`
2021-10-22 15:20:26 +00:00
2021-10-30 22:16:18 +00:00
::: tip
If you want to remove *all* groups from a member, consider using the [Overwrite Member Groups ](#overwrite-member-groups ) endpoint instead.
2021-10-22 15:20:26 +00:00
:::
2021-10-30 22:16:18 +00:00
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.
2021-10-22 15:20:26 +00:00
### Get Member Guild Settings
GET `/members/{memberRef}/guilds/{guild_id}`
2021-11-08 16:15:48 +00:00
Returns a [member guild settings ](/api/models#member-guild-settings-model ) object.
2021-10-22 15:20:26 +00:00
2021-10-22 21:54:47 +00:00
::: 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.
2021-10-22 15:20:26 +00:00
:::
### Update Member Guild Settings
PATCH `/members/{memberRef}/guilds/{guild_id}`
2021-11-08 16:15:48 +00:00
Takes a partial [member guild settings ](/api/models#member-guild-settings-model ) object.
2021-10-22 15:20:26 +00:00
2021-11-08 16:15:48 +00:00
Returns a [member guild settings ](/api/models#member-guild-settings-model ) object on success.
2021-10-22 15:20:26 +00:00
---
## Groups
*`groupRef` can be a group's short (5-character ID) or a group's UUID.*
### Get System Groups
GET `/systems/{systemRef}/groups`
2021-11-01 04:12:11 +00:00
Query String Parameters
|name|type|description
|---|---|---|
|with_members|boolean|includes `members` key with array of member UUIDs in each group object|
2021-10-22 15:20:26 +00:00
Returns a list of [group objects ](/api/models/#group-model ).
### Create Group
POST `/groups`
Takes a partial [group object ](/api/models#group-model ) as input. Key `name` is required.
Returns a [group object ](/api/models#group-model ) on success, or an error object on failure.
### Get Group
GET `/groups/{groupRef}`
Returns a [group object ](/api/models/#group-model ).
### Update Group
PATCH `/groups/{groupRef}`
Takes a partial [group object ](/api/models#group-model ) as input.
Returns a [group object ](/api/models#group-model ) 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`
2021-10-30 22:16:18 +00:00
Returns an array of [member objects ](/api/models#member-model ).
2021-10-22 15:20:26 +00:00
### Add Members To Group
2021-10-30 22:16:18 +00:00
POST `/groups/{groupRef}/members/add`
2021-10-22 15:20:26 +00:00
2021-10-30 22:16:18 +00:00
Takes an array of member references as input. Returns 204 No Content on success.
2021-10-22 15:20:26 +00:00
### Remove Member From Group
2021-10-30 22:16:18 +00:00
POST `/groups/{groupRef}/members/remove`
::: tip
If you want to remove *all* members from a group, consider using the [Overwrite Group Members ](#overwrite-group-members ) endpoint instead.
:::
2021-10-22 15:20:26 +00:00
2021-10-30 22:16:18 +00:00
Takes an array of member references as input. Returns 204 No Content on success.
2021-10-22 15:20:26 +00:00
2021-10-30 22:16:18 +00:00
### Overwrite Group Members
2021-10-22 15:20:26 +00:00
2021-10-30 22:16:18 +00:00
POST `/groups/{groupRef}/members/overwrite`
2021-10-22 15:20:26 +00:00
2021-10-30 22:16:18 +00:00
Takes an array of member references as input. (An empty list is accepted.) Returns 204 No Content on success.
2021-10-22 15:20:26 +00:00
---
## Switches
2021-11-28 23:33:41 +00:00
*`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.*
2021-10-22 15:20:26 +00:00
### Get System Switches
GET `/systems/{systemRef}/switches`
Query String Parameters
|key|type|description|
|---|---|---|
2021-11-17 14:52:58 +00:00
|before|timestamp|date to get latest switch from|
2021-11-17 14:53:17 +00:00
|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.
:::
2021-10-22 15:20:26 +00:00
Returns a [switch object ](/api/models#switch-model ) containing a list of IDs.
### Get Current System Fronters
GET `/systems/{systemRef}/fronters`
Returns a [switch object ](/api/models#switch-model ) 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)|
2021-11-13 16:48:20 +00:00
\* Defaults to "now" when missing.
2021-10-22 15:20:26 +00:00
** Can be short IDs or UUIDs.
### Get Switch
GET `/systems/{systemRef}/switches/{switchRef}`
Returns a [switch object ](/api/models#switch-model ) 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 ](/api/models#switch-model ) 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 ](/api/models#switch-model ) containing a list of member objects on success.
### Delete Switch
DELETE `/systems/{systemRef}/switches/{switchRef}`
2021-10-30 23:51:50 +00:00
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.
2022-11-24 06:32:55 +00:00
::: warning
Looking up messages by the original message ID only works **up to 30 minutes** after the message was sent.
:::
2021-10-30 23:51:50 +00:00
Returns a [message object ](/api/models#message-object ).
