Monkeytype API (2.0.0)

Download OpenAPI specification:

Support: [email protected] License: GPL-3.0 Terms of Service

Documentation for the endpoints provided by the Monkeytype API server.

Note that authentication is performed with the Authorization HTTP header in the format Authorization: ApeKey YOUR_APE_KEY

There is a rate limit of 30 requests per minute across all endpoints with some endpoints being more strict. Rate limit rates are shared across all ape keys.

Users

User account data.

check name

Checks to see if a username is available.

Rate limit: This operation can be called up to 60 times per minute for regular users.

path Parameters

name

required

string [ 1 .. 16 ] characters ^[\da-zA-Z_-]+$

Responses

Response samples

Content type

application/json

{"message": "string"
}

get personal bests

Get user's personal bests.

Rate limit: This operation can be called up to 60 times per hour for regular users.

Authorizations:

BearerAuthApeKey

query Parameters

mode required	string Enum: "time" "words" "quote" "custom" "zen"
	(string or number) or string or string

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
}

get tags

Get the users tags.

Rate limit: This operation can be called up to 60 times per hour for regular users.

Authorizations:

BearerAuthApeKey

Responses

Response samples

Content type

application/json

{"message": "string",
"data": [{"_id": "string",
"name": "string",
"personalBests": {"time": {"property1": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
],
"property2": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
]
},
"words": {"property1": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
],
"property2": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
]
},
"quote": {"property1": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
],
"property2": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
]
},
"custom": {"property1": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
],
"property2": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
]
},
"zen": {"property1": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
],
"property2": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
]
}
}
}
]
}

get stats

Gets a user's typing stats data.

Rate limit: This operation can be called up to 60 times per hour for regular users.

Authorizations:

BearerAuthApeKey

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"completedTests": 0,
"startedTests": 0,
"timeTyping": 0
}
}

get profile

Gets a user's profile.

Rate limit: This operation can be called up to 100 times per hour for regular users.

Required configuration: This operation can only be called if the configuration for users.profiles.enabled is true.

path Parameters

uidOrName

required

string

query Parameters

string or boolean

Default: false

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"uid": "string",
"name": "string",
"banned": true,
"addedAt": 0,
"discordId": "string",
"discordAvatar": "string",
"xp": 0,
"lbOptOut": true,
"isPremium": true,
"inventory": {"badges": [{"id": 0,
"selected": true
}
]
},
"allTimeLbs": {"time": {"property1": {"property1": {"rank": 0,
"count": 0
},
"property2": {"rank": 0,
"count": 0
}
},
"property2": {"property1": {"rank": 0,
"count": 0
},
"property2": {"rank": 0,
"count": 0
}
}
}
},
"typingStats": {"completedTests": 0,
"startedTests": 0,
"timeTyping": 0
},
"personalBests": {"time": {"property1": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
],
"property2": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
]
},
"words": {"property1": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
],
"property2": [{"acc": 100,
"consistency": 100,
"difficulty": "normal",
"lazyMode": true,
"language": "string",
"punctuation": true,
"numbers": true,
"raw": 0,
"wpm": 0,
"timestamp": 0
}
]
}
},
"streak": 0,
"maxStreak": 0,
"details": {"bio": "string",
"keyboard": "string",
"socialProfiles": {"twitter": "string",
"github": "string",
"website": "http://example.com"
}
}
}
}

send forgot password email

Send a forgot password email.

Rate limit: This operation can be called up to 1 times per minute for regular users.

Request Body schema: application/json

Body

captcha required	string
email required	string <email>

Responses

Request samples

Payload

Content type

application/json

{"captcha": "string",
"email": "[email protected]"
}

Response samples

Content type

application/json

{"message": "string"
}

get current test activity

Get test activity for the last up to 372 days for the current user .

Rate limit: This operation can be called up to 60 times per hour for regular users.

Authorizations:

BearerAuthApeKey

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"testsByDays": [0
],
"lastDay": 0
}
}

get streak

Get user's streak data.

Rate limit: This operation can be called up to 60 times per hour for regular users.

Authorizations:

BearerAuthApeKey

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"lastResultTimestamp": 0,
"length": 0,
"maxLength": 0,
"hourOffset": -11
}
}

Test results

User test results

get results

Gets up to 1000 results.

Rate limit: This operation can be called up to 60 times per hour for regular users and up to 30 times per day with ApeKeys.

Authorizations:

BearerAuthApeKey

query Parameters

onOrAfterTimestamp	integer >= 1589428800000 Timestamp of the earliest result to fetch. If omitted the most recent results are fetched.
offset	integer >= 0 Offset of the item at which to begin the response.
limit	integer [ 0 .. 1000 ] Limit results to the given amount.

Responses

Response samples

Content type

application/json

{"message": "string",
"data": [{"wpm": 420,
"rawWpm": 420,
"charStats": null,
"acc": 50,
"mode": "time",
"mode2": "string",
"quoteLength": 3,
"timestamp": 0,
"testDuration": 1,
"consistency": 100,
"keyConsistency": 100,
"uid": "string",
"restartCount": 0,
"incompleteTestSeconds": 0,
"afkDuration": 0,
"tags": ["string"
],
"bailedOut": true,
"blindMode": true,
"lazyMode": true,
"funbox": ["58008"
],
"language": "string",
"difficulty": "normal",
"numbers": true,
"punctuation": true,
"_id": "string",
"isPb": true
}
]
}

get result by id

Get result by id.

Rate limit: This operation can be called up to 300 times per hour for regular users and up to 60 times per hour with ApeKeys.

Authorizations:

BearerAuthApeKey

path Parameters

resultId

required

string^[a-zA-Z0-9_]+$

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"wpm": 420,
"rawWpm": 420,
"charStats": null,
"acc": 50,
"mode": "time",
"mode2": "string",
"quoteLength": 3,
"timestamp": 0,
"testDuration": 1,
"consistency": 100,
"keyConsistency": 100,
"chartData": {"wpm": [0
],
"raw": [0
],
"err": [0
]
},
"uid": "string",
"restartCount": 0,
"incompleteTestSeconds": 0,
"afkDuration": 0,
"tags": ["string"
],
"bailedOut": true,
"blindMode": true,
"lazyMode": true,
"funbox": ["58008"
],
"language": "string",
"difficulty": "normal",
"numbers": true,
"punctuation": true,
"_id": "string",
"keySpacingStats": {"average": 0,
"sd": 0
},
"keyDurationStats": {"average": 0,
"sd": 0
},
"name": "string",
"isPb": true
}
}

get last result

Gets a user's last saved result.

Rate limit: This operation can be called up to 60 times per hour for regular users.

Authorizations:

BearerAuthApeKey

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"wpm": 420,
"rawWpm": 420,
"charStats": null,
"acc": 50,
"mode": "time",
"mode2": "string",
"quoteLength": 3,
"timestamp": 0,
"testDuration": 1,
"consistency": 100,
"keyConsistency": 100,
"chartData": {"wpm": [0
],
"raw": [0
],
"err": [0
]
},
"uid": "string",
"restartCount": 0,
"incompleteTestSeconds": 0,
"afkDuration": 0,
"tags": ["string"
],
"bailedOut": true,
"blindMode": true,
"lazyMode": true,
"funbox": ["58008"
],
"language": "string",
"difficulty": "normal",
"numbers": true,
"punctuation": true,
"_id": "string",
"keySpacingStats": {"average": 0,
"sd": 0
},
"keyDurationStats": {"average": 0,
"sd": 0
},
"name": "string",
"isPb": true
}
}

Public

Public endpoints such as typing stats.

get speed histogram

get number of users personal bests grouped by wpm level (multiples of ten).

Rate limit: This operation can be called up to 60 times per minute for regular users.

query Parameters

language required	string <= 50 characters ^[a-zA-Z0-9_+]+$
mode required	string Enum: "time" "words" "quote" "custom" "zen"
required	(string or number) or string or string

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"property1": 0,
"property2": 0
}
}

get typing stats

get number of tests and time users spend typing.

Rate limit: This operation can be called up to 60 times per minute for regular users.

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"timeTyping": 0,
"testsCompleted": 0,
"testsStarted": 0
}
}

Leaderboards

All-time and daily leaderboards of the fastest typers.

get leaderboard

Get all-time leaderboard.

Rate limit: This operation can be called up to 500 times per hour for regular users.

query Parameters

language required	string <= 50 characters ^[a-zA-Z0-9_+]+$
mode required	string Enum: "time" "words" "quote" "custom" "zen"
required	(string or number) or string or string
page	integer [ 0 .. 9007199254740991 ] Default: 0
pageSize	integer ( 0 .. 200 ] Default: 50

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"count": 0,
"pageSize": 0,
"entries": [{"wpm": 0,
"acc": 100,
"timestamp": 0,
"raw": 0,
"consistency": 0,
"uid": "string",
"name": "string",
"discordId": "string",
"discordAvatar": "string",
"rank": 0,
"badgeId": 0,
"isPremium": true
}
]
}
}

get leaderboard rank

Get the rank of the current user on the all-time leaderboard.

Rate limit: This operation can be called up to 500 times per hour for regular users.

Authorizations:

BearerAuthApeKey

query Parameters

language required	string <= 50 characters ^[a-zA-Z0-9_+]+$
mode required	string Enum: "time" "words" "quote" "custom" "zen"
required	(string or number) or string or string

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"wpm": 0,
"acc": 100,
"timestamp": 0,
"raw": 0,
"consistency": 0,
"uid": "string",
"name": "string",
"discordId": "string",
"discordAvatar": "string",
"rank": 0,
"badgeId": 0,
"isPremium": true
}
}

get daily leaderboard

Get daily leaderboard.

Rate limit: This operation can be called up to 500 times per hour for regular users.

Required configuration: This operation can only be called if the configuration for dailyLeaderboards.enabled is true.

query Parameters

language required	string <= 50 characters ^[a-zA-Z0-9_+]+$
mode required	string Enum: "time" "words" "quote" "custom" "zen"
required	(string or number) or string or string
daysBefore	number Value: 1
page	integer [ 0 .. 9007199254740991 ] Default: 0
pageSize	integer ( 0 .. 200 ] Default: 50

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"count": 0,
"pageSize": 0,
"entries": [{"wpm": 0,
"acc": 100,
"timestamp": 0,
"raw": 0,
"consistency": 0,
"uid": "string",
"name": "string",
"discordId": "string",
"discordAvatar": "string",
"rank": 0,
"badgeId": 0,
"isPremium": true
}
],
"minWpm": 0
}
}

get weekly xp leaderboard

Get weekly xp leaderboard.

Rate limit: This operation can be called up to 500 times per hour for regular users.

Required configuration: This operation can only be called if the configuration for leaderboards.weeklyXp.enabled is true.

query Parameters

weeksBefore	number Value: 1
page	integer [ 0 .. 9007199254740991 ] Default: 0
pageSize	integer ( 0 .. 200 ] Default: 50

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"count": 0,
"pageSize": 0,
"entries": [{"uid": "string",
"name": "string",
"lastActivityTimestamp": 0,
"timeTypedSeconds": 0,
"discordId": "string",
"discordAvatar": "string",
"badgeId": 0,
"isPremium": true,
"totalXp": 0,
"rank": 0
}
]
}
}

PSAs

Public service announcements.

get psas

Get list of public service announcements.

Rate limit: This operation can be called up to 60 times per minute for regular users.

Responses

Response samples

Content type

application/json

{"message": "string",
"data": [{"_id": "string",
"message": "string",
"date": 0,
"level": 0,
"sticky": true
}
]
}

Quotes

Quote ratings and new quote submissions

is submission enabled

Check if submissions are enabled.

Rate limit: This operation can be called up to 60 times per minute for regular users.

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"isEnabled": true
}
}

Server configuration

get configuration

Get server configuration.

Responses

Response samples

Content type

application/json

{"message": "string",
"data": {"maintenance": true,
"dev": {"responseSlowdownMs": 0
},
"quotes": {"reporting": {"enabled": true,
"maxReports": 0,
"contentReportLimit": 0
},
"submissionsEnabled": true,
"maxFavorites": 0
},
"results": {"savingEnabled": true,
"objectHashCheckEnabled": true,
"filterPresets": {"enabled": true,
"maxPresetsPerUser": 0
},
"limits": {"regularUser": 0,
"premiumUser": 0
},
"maxBatchSize": 0
},
"users": {"signUp": true,
"lastHashesCheck": {"enabled": true,
"maxHashes": 0
},
"autoBan": {"enabled": true,
"maxCount": 0,
"maxHours": 0
},
"profiles": {"enabled": true
},
"discordIntegration": {"enabled": true
},
"xp": {"enabled": true,
"funboxBonus": 0,
"gainMultiplier": 0,
"maxDailyBonus": 0,
"minDailyBonus": 0,
"streak": {"enabled": true,
"maxStreakDays": 0,
"maxStreakMultiplier": 0
}
},
"inbox": {"enabled": true,
"maxMail": 0
},
"premium": {"enabled": true
}
},
"admin": {"endpointsEnabled": true
},
"apeKeys": {"endpointsEnabled": true,
"acceptKeys": true,
"maxKeysPerUser": 0,
"apeKeyBytes": 0,
"apeKeySaltRounds": 0
},
"rateLimiting": {"badAuthentication": {"enabled": true,
"penalty": 0,
"flaggedStatusCodes": [0
]
}
},
"dailyLeaderboards": {"enabled": true,
"leaderboardExpirationTimeInDays": 0,
"maxResults": 0,
"validModeRules": [{"language": "string",
"mode": "string",
"mode2": "string"
}
],
"scheduleRewardsModeRules": [{"language": "string",
"mode": "string",
"mode2": "string"
}
],
"topResultsToAnnounce": 0,
"xpRewardBrackets": [{"minRank": 0,
"maxRank": 0,
"minReward": 0,
"maxReward": 0
}
]
},
"leaderboards": {"minTimeTyping": 0,
"weeklyXp": {"enabled": true,
"expirationTimeInDays": 0,
"xpRewardBrackets": [{"minRank": 0,
"maxRank": 0,
"minReward": 0,
"maxReward": 0
}
]
}
}
}
}

Webhooks

Endpoints for incoming webhooks.