PronounDB
Login Create account
About PronounDB

API v2 Documentation

When querying the PronounDB API, please ensure to use a descriptive User-Agent. This is used to identify your traffic and ensure it is not rejected by anti-abuse policies.

A descriptive User-Agent should include at least: the name of the application, the version of the application (if applicable), and optionally a link to a website. Ideally, all this information should be enough to clearly identify your application and finding without too much effort a way to reach out.

Don't be overly descriptive, and make sure the information is usable. Non-monotonic version identifiers are difficult to handle as they don't allow to distinguish ranges. Information that's too specific may be a privacy issue for your users as well.

If you are unable to configure the User-Agent header, you may use the X-PronounDB-Source header if the default User-Agent is not descriptive enough. Be careful, in some environments this will cause extra CORS preflight requests to occur!

If you are unsure about your implementation, or have a general question about the API feel free to reach out.

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,246652610747039745

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/01765c9b-e000-736c-aa79-b32c8e80d5b6

Example response

HTTP/2 200 OK
Content-Type: application/json

{
	"id": "01765c9b-e000-736c-aa79-b32c8e80d5b6",
	"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/01765c9b-e000-736c-aa79-b32c8e80d5b6.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