--- 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. --- ## 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). ### Get System Guild Settings GET `/systems/@me/guilds/{guild_id}` Returns a [system guild settings](/api/models#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](/api/models#system-guild-settings) object. Returns a [system guild settings](/api/models#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](/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 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](#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](#remove-member-from-group) endpoint instead. ::: ### Get Member Guild Settings GET `/members/{memberRef}/guilds/{guild_id}` Returns a [member guild settings](/api/models#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](/api/models#member-guild-settings) object. Returns a [member guild settings](/api/models#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](/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` ### 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](#add-group-member) 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](#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](/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)| * Defaults to "now" when missing. ** 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}` Returns 204 No Content on success.