API

The API Instance

You can get started by importing the library and creating a new instance:

import PKAPI from 'pkapi.js';
const api = new PKAPI();

Options

key	description	optional?	default
base_url	The URL for accessing the API, eg. localhost:8080 for local testing	yes	https://api.pluralkit.me
version	The version of the API to use	yes	2
token	A system token to use for authorizing requests	yes	undefined
user_agent	A string to use for the User-Agent header when sending requests	yes	PKAPI.js/<version>

Note: A token being given here will always override tokens used in options/arguments. Only set the token if you're only planning to affect one system with this instance!

System Methods

getSystem(data)

Fetches a system

Options

key	description	optional?
system	An account or system ID	no - unless using token
token	A token to auth the request	yes - unless not using ID
fetch	An array of keys to also fetch	yes

Fetch keys

key	description
members	Fetches system members, placing them into a Map by their IDs
fronters	Fetches the system's current fronters, using the Switch format
groups	Fetch the system's groups, Maping by their IDS
switches	Fetches an array of Switch objects for the system
settings	Fetches the settings object for the system (appears in the .config property)

Returns
A new System object

Errors
Throws for the following reasons:

• ID and token not supplied
• System not found (ID or token invalid)

getAccount(data)

Shortcut for getting a system with their account ID; works the same as above

patchSystem(data)

Patches a system

Options

key	description	optional?
token	A token to auth the request	no
[system data]	The data to patch the system with. See Systems for keys	yes*

Note: All keys should be top level on the object, eg: {token: "", name: "Test"}
* = Keys are all optional

Returns
Returns a new System object

Errors
Throws for the following:

• Token not supplied
• Token incorrect (failed to auth)
• Invalid system data (bad request or failed lib's tests)

getSystemSettings(data) [v2 only]

Fetches config settings for a system

Options

key	description	optional?
token	A token to auth the request	yes

Returns Returns a new SystemSettings object

Errors Throws for the following:

• Token not supplied
• Token incorrect (failed to auth)

getSystemGuildSettings(data) [v2 only]

Fetches settings for a specific guild

Options

key	description	optional?
guild	A guild ID to get data from	no
token	A token to auth the request	no

Returns
A new SystemGuildSettings object

Errors
Throws for the following:

• Token not supplied
• Guild ID not supplied
• Token incorrect (failed to auth)
• Settings don't exist for given guild

patchSystemGuildSettings(data) [v2 only]

Patches settings for a specific guild

Options

key	description	optional?
guild	The guild ID to patch	no
token	A token to auth the request	no
[system guild settings data]	The data to patch the settings with. See System Guild Settings for keys	yes*

Returns
New SystemGuildSettings object

Errors
Throws for the following:

• Token not supplied
• Token incorrect (failed to auth)
• Invalid guild (no settings exist)
• Invalid settings data (bad request or failed lib's tests)

getSystemAutoproxySettings(data) [v2 only]

Fetches autoproxy settings for a specific guild

Options

key	description	optional?
guild	A guild ID to get data from	no
token	A token to auth the request	no

Returns
A new SystemAutoproxySettings object

Errors
Throws for the following:

• Token not supplied
• Guild ID not supplied
• Token incorrect (failed to auth)
• Settings don't exist for given guild

patchSystemAutoproxySettings(data) [v2 only]

Patches autoproxy settings for a specific guild

Options

key	description	optional?
guild	The guild ID to patch	no
token	A token to auth the request	no
[system autoproxy settings data]	The data to patch the settings with. See System Autoproxy Settings for keys	yes*

Returns
New SystemAutoproxySettings object

Errors
Throws for the following:

• Token not supplied
• Token incorrect (failed to auth)
• Invalid guild (no settings exist)
• Invalid settings data (bad request or failed lib's tests)

---

Member Methods

createMember(data)

Creates a new member

Options

key	description	optional?
token	A token to auth the request	no
[member data]	The data to create the member with. See Members for keys	no*

* = All keys exceot name are optional

Returns
Returns new Member object

Errors
Throws for the following:

• Token not supplied
• Token incorrect (failed to auth)
• Invalid member data (bad request or failed lib's tests)

getMember(data)

Fetches a member

Options

key	description	optional?
member	The ID of the member to get	no
token	A token to auth the request	yes

Returns
Returns a new Member object

Errors
Throws for the following:

• ID not supplied
• Invalid ID (member not found)
• Member not visible (member privated, auth failed)

getMembers(data)

Fetches a system's members

Options

key	description	optional?
member	The system's ID	no
token	A token to auth the request	yes

Returns
A Map of all the members, keyed by their ID

Errors
Throws for the following:

• ID not supplied
• Member list not visible (auth failed)

patchMember(data)

Patches a member

Options

key	description	optional?
member	ID of the member to patch	no
token	A token to auth the request	no
[member data]	The data to patch the member with. See Members for keys	yes*

Note: This method works the same as creating a member and patching a system
* = Keys are all optional

Returns
Returns new Member object

Errors
Throws for the following:

• ID not supplied
• Token not supplied
• Token incorrect (failed to auth)
• Invalid system data (bad request or failed lib's tests)

deleteMember(data)

Deletes a member

Options

key	description	optional?
member	ID of the member to delete	no
token	A token to auth the request	no

Returns Nothing

Errors
Throws for the following:

• ID not supplied
• Token not supplied
• Token invalid (auth failed)

getMemberGroups(data) [v2 only]

Fetches the groups a member is part of

Options

key	description	optional?
member	The member ID to fetch groups for	no
token	A token to auth the request	yes

Returns
A Map of Group objects, keyed by their ID

Errors
Throws for the following:

• Invalid member ID (not found or failed to auth)
• Groups are private (failed to auth)

addMemberGroups(data) [v2 only]

Adds groups to a member

Options

key	description	optional?
member	The member ID to add groups to	no
groups	An array of group IDs	no
token	A token to auth the request	no

Returns
Nothing (refetch for new group list)

Errors
Throws for the following:

• Anything required not supplied
• Token invalid (failed to auth)
• Member ID invalid (not found)
• Group ID(s) invalid (at least one group not found)

removeMemberGroups(data) [v2 only]

Removes groups from a member

Options

key	description	optional?
member	The member ID to remove groups from	no
groups	An array of group IDs	no
token	A token to auth the request	no

Returns
Nothing (refetch for new group list)

Errors
Throws for the following:

• Anything required not supplied
• Token invalid (failed to auth)
• Member ID invalid (not found)
• Group ID(s) invalid (at least one group not found)

setMemberGroups(data) [v2 only]

Sets groups for a member, overwriting all current groups

Options

key	description	optional?
member	The member ID to set groups for	no
groups	An array of group IDs	no
token	A token to auth the request	no

Returns
Nothing (refetch for new group list)

Errors
Throws for the following:

• Anything required not supplied
• Token invalid (failed to auth)
• Member ID invalid (not found)
• Group ID(s) invalid (at least one group not found)

getMemberGuildSettings(data) [v2 only]

Fetches a member's guild settings

Options

key	description	optional?
member	The member to fetch settings for	no
guild	The guild to fetch settings for	no
token	A token to auth the request	no

Returns
New MemberGuildSettings object

Errors
Throws for the following:

• Anything required not supplied
• Token invalid (failed to auth)
• Member ID invalid (not found)
• No settings for that guild

patchSystemGuildSettings(data) [v2 only]

Patches settings for a specific guild

Options

key	description	optional?
member	The member ID to patch settings for	no
guild	The guild ID to patch	no
token	A token to auth the request	no
[system guild settings data]	The data to patch the settings with. See Member Guild Settings for keys	yes*

* = Keys are all optional

Returns
New MemberGuildSettings object

Errors
Throws for the following:

• Anything required not supplied
• Token incorrect (failed to auth)
• Invalid member (not found)
• Invalid guild (no settings exist)
• Invalid settings data (bad request or failed lib's tests)

---

Group Methods

createGroup(data) [v2 only]

Creates a new Group

Options

key	description	optional?
token	A token to auth the request	no
[group data]	The data to create the group with. See Groups for keys	no*

* = All keys except name not required

Returns
A new Group object

Errors
Throws for the following:

• Token not supplied
• Invalid token (auth failed)
• Invalid group data (bad request or failed lib's tests)

getGroups(data) [v2 only]

Fetches a system's groups

Options

key	description	optional?
system	ID of the system to get groups for	no - unless using token
token	A token to auth the request	no - unless using ID

Returns
A Map of Group objects, keyed by their IDs

Errors
Throws for the following:

• Anything required not supplied
• Groups are private (auth failed)

getGroup(data) [v2 only]

Fetches a specific group

Options

key	description	optional?
group	ID of the group to get	no
token	A token to auth the request	yes
fetch_members	A boolean (`true	false`) to determine if members should be fetched

Returns
A new Group object, complete with members (if fetch_members = true)

Errors
Throws for the following:

• Group ID not supplied
• Token invalid (failed to auth)

patchGroup(data) [v2 only]

Patches a group's info

Options

key	description	optional?
group	The ID of the group to patch	no
token	A token to auth the request	no
[group data]	Data to patch the group with. See Groups for keys	yes*

* = All keys optional

Returns
A new Group object

Errors
Throws for the following:

• Anything required not supplied
• Group ID invalid (not found)
• Token invalid (failed to auth)

deleteGroup(data) [v2 only]

Deletes a group

Options

key	description	optional?
group	ID of the group to delete	no
token	A token to auth the request	no

Returns
Nothing

Errors
Throws for the following:

• Anything required not supplied
• Group ID invalid (not found)
• Token invalid (failed to auth)

getGroupMembers(data) [v2 only]

Fetches a group's members

Options

key	description	optional?
group	ID of the group to get members of	no
token	A token to auth the request	yes

Returns
A Map of Member objects, keyed by their ID

Errors
Throws for the following:

• Anything rqeuired not supplied
• Group ID invalid (not found)
• Group private (auth failed)

addGroupMembers(data) [v2 only]

Adds members to a group

Options

key	description	optional?
group	ID of the group to affect	no
token	A token to auth the request	no
members	Array of member IDs to add	no

Returns
Nothing

Errors
Throws for the following:

• Anything required not supplied
• Group ID invalid (not found)
• Member ID(s) invalid (not found)
• Token invalid (failed to auth)

removeGroupMembers(data) [v2 only]

Removes members from a group

Options

key	description	optional?
group	ID of the group to affect	no
token	A token to auth the request	no
members	Array of member IDs to remove	no

Returns
Nothing

Errors
Throws for the following:

• Anything required not supplied
• Group ID invalid (not found)
• Member ID(s) invalid (not found)
• Token invalid (failed to auth)

setGroupMembers(data) [v2 only]

Sets a group's members, overwriting existing ones

Options

key	description	optional?
group	ID of the group to affect	no
token	A token to auth the request	no
members	Array of member IDs to set	no

Returns
Nothing

Errors
Throws for the following:

• Anything required not supplied
• Group ID invalid (not found)
• Member ID(s) invalid (not found)
• Token invalid (failed to auth)

---

Switch Methods

createSwitch(data)

Creates a new switch

Options

key	description	optional?
token	A token to auth the request	no
timestamp	A valid Date for the switch	yes
members	An array of Member IDs or objects to switch in	yes*

* = Uses empty array (no members) if not supplied

Returns
Nothing

Errors Throws for the following:

• Token not supplied
• Token invalid (auth failed)

getSwitches(data)

Fetches a system's switches

Options

key	description	optional?
system	ID of the system to get switches for	no
token	A token to auth the request	yes
raw	Whether members should be resolved or not; true means no member objects

Returns

v1

An array of Switch objects, including a Map of full member objects (if raw = false)

v2

A Map of Switch objects, keyed by ID. Each contains full member objects (if raw = false)

Errors

• ID not supplied
• No switches logged
• Switches not visible (auth failed)
• Member list not visible (auth failed; only if raw = false)

getSwitch(data) [v2 only]

Fetches a specific switch

Options

key	description	optional?
system	The system ID the switch belongs to	no - unless using token
switch	The switch ID	no
token	A token to auth the request	no - unless using ID

Returns
A new Switch object, with a Map of members

Errors
Throws for the following:

• Anything required not supplied
• Token invalid (failed to auth)
• System ID invalid (not found)
• Switch ID invalid (not found)

getFronters(data)

Fetches a system's fronters

Options

key	description	optional?
systen	ID of the system to fetch fronters for	no
token	A token to auth the request	yes

Returns New Switch object with a Map of full member objects

Errors
Throws for the following:

• ID not supplied
• No switches logged
• Fronters not visible (auth failed)

patchSwitchTimestamp(data) [v2 only]

Patches a switch's timestamp

Options

key	description	optional?
switch	ID of the switch to patch	no
token	A token to auth the request	no
timestamp	A new timestamp for the switch	no

Returns
New Switch object with a Map of full member objects

Errors
Throws for the following:

• Anything required not supplied
• Invalid timestamp (bad request or failed lib's tests)
• Invalid switch (not found)

patchSwitchMembers(data) [v2 only]

Patches a switch's member list

Options

key	description	optional?
switch	ID of the switch to patch	no
token	A token to auth the request	no
members	An array of member IDs for the switch	yes

Returns
New Switch object with a Map of full member objects (if applicable)

Errors
Throws for the following:

• Anything required not supplied
• Invalid members (bad request or not found)
• Invalid switch (not found)

deleteSwitch(data) [v2 only]

Deletes an existing switch

Options

key	description	optional?
switch	The switch ID to delete	no
token	A token to auth the request	no

Returns
Nothing

Errors
Throws for the following:

• Anything required not supplied
• Invalid switch ID (not found)
• Invalid token (failed to auth)

---

Misc Methods

getMessage(data)

Fetches a proxied message

Options

key	description	optional?
message	ID of the message to fetch	no
token	A token to auth the request	yes

Returns
A new Message object, with full System and Member objects

Errors
Throws for the following:

• ID not supplied