261 lines
6.2 KiB
Markdown
261 lines
6.2 KiB
Markdown
|
---
|
||
|
|
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.
|
||
|
|
|
||
|
|
::: note
|
||
|
|
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`
|
||
|
|
|
||
|
|
::: warn
|
||
|
|
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`
|
||
|
|
|
||
|
|
::: warn
|
||
|
|
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.
|
||
|
|
|
||
|
|
::: note
|
||
|
|
You must already have updated per-guild settings for a 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`
|
||
|
|
|
||
|
|
::: warn
|
||
|
|
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`
|
||
|
|
|
||
|
|
::: warn
|
||
|
|
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.
|