6.7 KiB
| 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
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. 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.
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.