--- layout: default title: API documentation permalink: /api --- # API documentation PluralKit has a basic HTTP REST API for querying and modifying your system. The root endpoint of the API is `https://api.pluralkit.me/v1/`. Endpoints will always return all fields, using `null` when a value is missing. On `PATCH` endpoints, you *must* include all fields, too. Missing fields will be interpreted as `null`, and `null` fields will have their value removed. To preserve a value, pass the existing value again. ## Authentication Authentication is done with a simple "system token". You can get your system token by running `pk;token` using the Discord bot, either in a channel with the bot or in DMs. Then, pass this token in the `Authorization` HTTP header on requests that require it. Failure to do so on endpoints that require authentication will return a `401 Unauthorized`. ## Models The following three models (usually represented in JSON format) represent the various objects in PluralKit's API. A `?` after the column type indicates an optional (nullable) parameter. ### System model |Key|Type|Patchable?|Notes| |---|---|---|---| |id|string|No|| |name|string?|Yes|100-character limit.| |description|string?|Yes|1000-character limit.| |tag|string?|Yes|| |avatar_url|url?|Yes|Not validated server-side.| |tz|string?|Yes|Tzdb identifier. Patching with `null` will store `"UTC"`.| |created|datetime|No|| ### Member model |Key|Type|Patchable?|Notes| |---|---|---|---| |id|string|No|| |name|string?|Yes|50-character limit.| |description|string?|Yes|1000-character limit.| |color|color?|Yes|6-char hex (eg. `ff7000`), sans `#`.| |avatar_url|url?|Yes|Not validated server-side.| |birthday|date?|Yes|ISO-8601 (`YYYY-MM-DD`) format, year of `0001` means hidden year.| |prefix|string?|Yes|| |suffix|string?|Yes|| |created|datetime|No|| ### Switch model |Key|Type|Notes| |---|---|---| |timestamp|datetime|| |members|list of id/Member|Is sometimes in plain ID list form (eg. `GET /s//switches`), sometimes includes the full Member model (eg. `GET /s//fronters`).| ## Endpoints ### GET /s **Requires authentication.** Returns information about your own system. #### Example request GET https://api.pluralkit.me/v1/s #### Example response ```json { "id": "abcde", "name": "My System", "description": "This is my system description. Yay.", "tag": "[MySys]", "avatar_url": "https://path/to/avatar/image.png", "tz": "Europe/Copenhagen", "created": "2019-01-01T14:30:00.987654Z" } ``` ### GET /s/ Queries a system by its 5-character ID, and returns information about it. If the system doesn't exist, returns `404 Not Found`. #### Example request GET https://api.pluralkit.me/v1/s/abcde #### Example response ```json { "id": "abcde", "name": "My System", "description": "This is my system description. Yay.", "tag": "[MySys]", "avatar_url": "https://path/to/avatar/image.png", "tz": "Europe/Copenhagen", "created": "2019-01-01T14:30:00.987654Z" } ``` ### GET /s//members Queries a system's member list by its 5-character ID. If the system doesn't exist, returns `404 Not Found`. #### Example request GET https://api.pluralkit.me/v1/s/abcde/members #### Example response ```json [ { "id": "qwert", "name": "Craig Johnson", "color": "ff7000", "avatar_url": "https://path/to/avatar/image.png", "birthday": "1997-07-14", "pronouns": "he/him or they/them", "description": "I am Craig, example user extraordinaire.", "prefix": "[", "suffix": "]", "created": "2019-01-01T15:00:00.654321Z" } ] ``` ### GET /s//switches[?before=] Returns a system's switch history in newest-first chronological order, with a maximum of 100 switches. If the system doesn't exist, returns `404 Not Found`. Optionally takes a `?before=` query parameter with an ISO-8601-formatted timestamp, and will only return switches that happen before that timestamp. #### Example request GET https://api.pluralkit.me/v1/s/abcde/switches?before=2019-03-01T14:00:00Z #### Example response ```json [ { "timestamp": "2019-02-23T14:20:59.123456Z", "members": ["qwert", "yuiop"] }, { "timestamp": "2019-02-22T12:00:00Z", "members": ["yuiop"] }, { "timestamp": "2019-02-20T09:30:00Z", "members": [] } ] ``` ### GET /s//fronters Returns a system's current fronter(s), with fully hydrated member objects. If the system doesn't exist, *or* the system has no registered switches, returns `404 Not Found`. #### Example request GET https://api.pluralkit.me/v1/s/abcde/fronters #### Example response ```json { "timestamp": "2019-07-09T17:22:46.47441Z", "members": [ { "id": "qwert", "name": "Craig Johnson", "color": "ff7000", "avatar_url": "https://path/to/avatar/image.png", "birthday": "1997-07-14", "pronouns": "he/him or they/them", "description": "I am Craig, example user extraordinaire.", "prefix": "[", "suffix": "]", "created": "2019-01-01T15:00:00.654321Z" } ] } ``` ### PATCH /s **Requires authentication.** Edits your own system's information. Missing fields will be set to `null`. Will return the new system object. #### Example request PATCH https://api.pluralkit.me/v1/s ```json { "name": "New System Name", "tag": "{Sys}", "avatar_url": "https://path/to/new/avatar.png" "tz": "America/New_York" } ``` (note the absence of a `description` field, which is set to null in the response) #### Example response ```json { "id": "abcde", "name": "New System Name", "description": null, "tag": "{Sys}", "avatar_url": "https://path/to/new/avatar.png", "tz": "America/New_York", "created": "2019-01-01T14:30:00.987654Z" } ``` ### POST /s/switches **Requires authentication.** Registers a new switch to your own system given a list of member IDs. #### Example request POST https://api.pluralkit.me/v1/s/switches ```json { "members": ["qwert", "yuiop"] } ``` #### Example response (`204 No Content`) ### GET /m/ Queries a member's information by its 5-character member ID. If the member does not exist, will return `404 Not Found`. #### Example request GET https://api.pluralkit.me/v1/m/qwert #### Example response ```json { "id": "qwert", "name": "Craig Johnson", "color": "ff7000", "avatar_url": "https://path/to/avatar/image.png", "birthday": "1997-07-14", "pronouns": "he/him or they/them", "description": "I am Craig, example user extraordinaire.", "prefix": "[", "suffix": "]", "created": "2019-01-01T15:00:00.654321Z" } ``` ### PATCH /m/ **Requires authentication.** Edits a member's information. Missing fields will be set to `null`. Will return the new member object. Member must (obviously) belong to your own system. #### Example request PATCH https://api.pluralkit.me/v1/m/qwert ```json { "name": "Craig Peterson", "color": null, "avatar_url": "https://path/to/new/image.png", "birthday": "1997-07-14", "pronouns": "they/them", "description": "I am Craig, cooler example user extraordinaire.", "prefix": "[" } ``` (note the absence of a `suffix` field, which is set to null in the response) #### Example response ```json { "id": "qwert", "name": "Craig Peterson", "color": null, "avatar_url": "https://path/to/new/image.png", "birthday": "1997-07-14", "pronouns": "they/them", "description": "I am Craig, cooler example user extraordinaire.", "prefix": "[", "suffix": null, "created": "2019-01-01T15:00:00.654321Z" } ``` ## Version history * 2019-07-10 **(v1)** * First specified version * (prehistory) * Initial release