PluralKit/docs/content/api/reference.md

title	permalink
Reference	/api

API Reference

PluralKit has a basic HTTP REST API for querying and modifying your system. The root endpoint of the API is https://api.pluralkit.me/v2/.

Endpoints will always return all fields, using null when a value is missing. On PATCH endpoints, missing fields from the JSON request will be ignored and preserved as is, but on POST endpoints will be set to null or cleared.

For models that have them, the keys id, uuid and created are not user-settable.

Endpoints taking JSON bodies (eg. most PATCH and PUT endpoints) require the Content-Type: application/json header set.

User agent

The API requires the User-Agent header to be set to a non-empty string. Not doing so will return a 400 Bad Request with a JSON body.

If you are developing an application exposed to the public, we would appreciate if your User-Agent uniquely identifies your application, and (if possible) provides some contact information for the developers - so that we are able to contact you if we notice your application doing something it shouldn't.

Authentication

Authentication is done with an API key provided in the Authorization HTTP header - see the API key section of the documentation for details.

Some endpoints show information that a given system may have set to private. For unauthenticated requests, and for requests authenticated with an API key that does not have permission to read private data, the following rules apply:

• For fields with specific privacy settings (e.g. descriptions), the field will simply contain null rather than the true value
• For entire endpoints which show private data (e.g. member/group lists), a 403 Forbidden response will be returned

Rate Limiting

To protect against abuse and manage server resources, PluralKit's API limits the amount of queries available. Currently, the following limits are applied:

• 10/second for any GET requests other than the messages endpoint (generic_get scope)
• 10/second for requests to the Get Proxied Message Information endpoint (message scope)
• 3/second for any POST, PATCH, or DELETE requests (generic_update scope)

We may raise the limits for individual API clients on a case-by-case basis; please ask in the support server if you need a higher limit.

::: tip If you are looking to query a specific resource in your system repeatedly (polling), please consider using Dispatch Webhooks instead. :::

The following rate limit headers are present on HTTP responses:

name	description
X-RateLimit-Limit	The amount of total requests you have available per second.
X-RateLimit-Remaining	The amount of requests you have remaining until the next reset time.
X-RateLimit-Reset	The UNIX time (in milliseconds) when the ratelimit info will reset.
X-RateLimit-Scope	The type of rate limit the current request falls under.

If you make more requests than you have available, the server will respond with a 429 status code and a JSON error body.

{
  "message": "429: too many requests",
  "retry_after": 19, // the amount of milliseconds remaining until you can make more requests
  "code": 0
}

Community API Libraries

The following API libraries have been created by members of our community. Please contact the developer of each library if you need support.

• Python: PluralKit.py (PyPI | Docs | Source code)
• JavaScript: pkapi.js (npmjs | Docs | Source code)
• Golang: pkgo (install: go get github.com/starshine-sys/pkgo/v2 | Docs (godoc) | Docs (pkg.go.dev) | Source code)
• Kotlin: Plural.kt (Maven Repository | Source code)

Do let us know in the support server if you made a new library and would like to see it listed here!