API v2 Documentation
Endpoint routes
Looks up the data saved in PronounDB for one or more (up to 50) account for a given platform.
The response is a map of IDs to the corresponding data. If an ID is not in our database, it will not be present in the response.
It is strongly recommended to fetch IDs in bulk when possible and applicable, to help prevent hitting and potential rate limits.
type RequestParams = {
// See below for a list of supported platforms
platform: string
// Items are separated by ",". Example: 13,27,31
ids: string[]
}
type ResponseBody = {
[userId: string]: {
// See below for a list of supported sets
sets: {
// See below for a list of supported locales
[locale: string]: string[]
}
}
}
Example request
GET /api/v2/lookup?platform=discord&ids=94762492923748352,246652610747039744
Example response
HTTP/2 200 OK
Content-Type: application/json
{
"94762492923748352": {
"sets": {
"en": [
"she",
"it"
]
}
}
}
Looks up the data saved for a given PronounDB user. Will return a 404 Not Found error if the user does not exist.
type RequestParams = {
id: string
}
type ResponseBody = {
id: string
sets: {
[locale: string]: string[]
}
}
Example request
GET /api/v2/users/5fd62c00985db32c8e80d5b6
Example response
HTTP/2 200 OK
Content-Type: application/json
{
"id": "5fd62c00985db32c8e80d5b6",
"sets": {
"en": [
"she",
"it"
]
}
}
Returns a shields.io-compatible JSON object to be used as part of shields.io endpoint feature.
Learn more on shields.io's documentation.
type RequestParams = {
pronoundbId: string
capitalize?: boolean
locale?: string
}
Example request
GET /shields/5fd62c00985db32c8e80d5b6.json
Example response
HTTP/2 200 OK
Content-Type: application/json
{
"schemaVersion": 1,
"label": "pronouns",
"message": "she/it"
}
Supported sets
Each locale has a list of pronouns set available to it.
Only the "en" locale is supported at this time.
en
locale- Nominative
he
: he/himit
: it/itsshe
: she/herthey
: they/them- Meta sets
any
: Any pronounsask
: Ask me my pronounsavoid
: Avoid pronouns, use my nameother
: Other pronouns
Supported platforms
-
discord
-
github
-
minecraft
(UUIDs must be formatted with dashes) -
twitch
-
twitter
Legacy API v1
If you need it, the documentation for API v1 is still available. Beware, API v1 is deprecated and scheduled for removal on June 1st, 2024