PronounDB
Login Create account
About PronounDB

API v2 Documentation

Endpoint routes

GET /api/v2/lookup?platform=[platform]&ids=[ids]

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.

Request types
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"
			]
		}
	}
}
GET /api/v2/users/[id]

Looks up the data saved for a given PronounDB user. Will return a 404 Not Found error if the user does not exist.

Request types
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"
		]
	}
}
GET /shields/[pronoundbId].json?capitalize=[capitalize]&locale=[locale]

Returns a shields.io-compatible JSON object to be used as part of shields.io endpoint feature.

Learn more on shields.io's documentation.

Request types
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.

Supported platforms

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