API Endpoints - Monkeytype

Users

Get User Data

Retrieve complete user profile and settings.

curl https://api.monkeytype.com/users \
  -H "Authorization: Bearer YOUR_TOKEN"

data

object

Show User object

uid

string

required

User’s unique identifier

name

string

required

Username

string

required

User’s email address

addedAt

number

required

Account creation timestamp

personalBests

object

required

Personal best records by mode

completedTests

number

Total number of completed tests

startedTests

number

Total number of started tests

timeTyping

number

Total seconds spent typing

number

Total XP earned

streak

object

Current and max streak information

isPremium

boolean

Premium subscription status

inboxUnreadSize

number

required

Count of unread inbox messages

Create User

curl -X POST https://api.monkeytype.com/users/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "username",
    "email": "[email protected]",
    "captcha": "CAPTCHA_TOKEN"
  }'

name

string

required

Desired username (1-16 characters, alphanumeric, underscores, hyphens, dots)

string

User’s email address

captcha

string

required

Google reCAPTCHA token

Get User Profile

Retrieve public profile of any user.

curl "https://api.monkeytype.com/users/{uidOrName}/profile?isUid=false"

uidOrName

string

required

Username or user ID

isUid

boolean

default:"false"

Whether the path parameter is a UID (true) or username (false)

Update Username

Change username (once per 30 days).

curl -X PATCH https://api.monkeytype.com/users/name \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "newusername"}'

Requires fresh token (issued within last 60 seconds). Limited to once per 30 days.

Results

Submit Test Result

Submit a completed typing test result.

curl -X POST https://api.monkeytype.com/results \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "result": {
      "wpm": 85.5,
      "acc": 96.8,
      "mode": "time",
      "mode2": "60",
      "language": "english",
      "timestamp": 1234567890,
      "testDuration": 60,
      "consistency": 78.5,
      "rawWpm": 90.2,
      "hash": "RESULT_HASH"
    }
  }'

result

object

required

Show CompletedEvent object

wpm

number

required

Words per minute

rawWpm

number

required

Raw WPM (includes errors)

acc

number

required

Accuracy percentage (0-100)

mode

string

required

Test mode: “time”, “words”, “quote”, “zen”, “custom”

mode2

string

required

Mode variant (e.g., “60” for 60-second test)

language

string

required

Language code (e.g., “english”)

timestamp

number

required

Test completion timestamp

testDuration

number

required

Test duration in seconds

consistency

number

required

Consistency percentage

hash

string

required

Object hash for verification

data

object

Show PostResultResponse

isPb

boolean

Whether this result is a personal best

insertedId

string

Database ID of inserted result

number

XP gained from this result

xpBreakdown

object

Detailed XP calculation breakdown

dailyXpBonus

boolean

Whether daily XP bonus was applied

streak

number

Current streak length

dailyLeaderboardRank

number

Rank on daily leaderboard (if applicable)

Results undergo anticheat validation. Invalid results (hash mismatch, suspicious timing, bot detection) will be rejected.

Get Results

Retrieve paginated test results.

curl "https://api.monkeytype.com/results?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN"

limit

number

default:"50"

Number of results to return (max 1000)

offset

number

default:"0"

Offset for pagination

onOrAfterTimestamp

number

Filter results on or after this timestamp

Premium users can retrieve more results than regular users. Limits are configurable per deployment.

Get Result by ID

Retrieve a specific result by its ID.

curl https://api.monkeytype.com/results/id/{resultId} \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete All Results

Permanently delete all test results.

curl -X DELETE https://api.monkeytype.com/results \
  -H "Authorization: Bearer YOUR_TOKEN"

Requires fresh token. This action is irreversible.

Leaderboards

Get All-Time Leaderboard

Retrieve global leaderboard entries.

curl "https://api.monkeytype.com/leaderboards?language=english&mode=time&mode2=60&page=0&pageSize=50"

language

string

required

Language code (e.g., “english”)

mode

string

required

Test mode: “time” or “words”

mode2

string

required

Mode variant: “15”, “60” for time; “10”, “25”, “50”, “100” for words

page

number

default:"0"

Page number (0-indexed)

pageSize

number

default:"50"

Results per page (10-200)

friendsOnly

boolean

default:"false"

Show only friends (requires authentication)

data

object

Show Leaderboard response

entries

array

Array of leaderboard entries

count

number

Total number of entries

pageSize

number

Entries per page

Get Leaderboard Rank

Get current user’s rank on leaderboard.

curl "https://api.monkeytype.com/leaderboards/rank?language=english&mode=time&mode2=60" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Daily Leaderboard

Retrieve today’s daily leaderboard.

curl "https://api.monkeytype.com/leaderboards/daily?language=english&mode=time&mode2=60"

daysBefore

number

default:"0"

Get leaderboard from N days ago (0 = today, 1 = yesterday)

Get Weekly XP Leaderboard

Retrieve weekly XP leaderboard.

curl "https://api.monkeytype.com/leaderboards/xp/weekly?page=0&pageSize=50"

Configs

Get User Configuration

Retrieve user’s configuration settings.

curl https://api.monkeytype.com/configs \
  -H "Authorization: Bearer YOUR_TOKEN"

data

object

User’s configuration object including theme, test settings, behavior preferences, etc.

Update Configuration

Update user configuration (partial update).

curl -X PATCH https://api.monkeytype.com/configs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "theme": "serika_dark",
    "difficulty": "expert",
    "showAverage": "wpm"
  }'

Only provided fields are updated. Missing fields remain unchanged.

Quotes

Get Quote Submissions

Retrieve pending quote submissions (moderators only).

curl https://api.monkeytype.com/quotes \
  -H "Authorization: Bearer YOUR_TOKEN"

Requires quoteMod permission.

Submit Quote

Submit a new quote for approval.

curl -X POST https://api.monkeytype.com/quotes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Quote text that is at least 60 characters long to meet requirements",
    "source": "Author Name",
    "language": "english",
    "captcha": "CAPTCHA_TOKEN"
  }'

text

string

required

Quote text (minimum 60 characters)

source

string

required

Quote author or source

language

string

required

Language code

captcha

string

required

reCAPTCHA token

Report Quote

Report a problematic quote.

curl -X POST https://api.monkeytype.com/quotes/report \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "123",
    "quoteLanguage": "english",
    "reason": "inappropriate",
    "comment": "Optional comment",
    "captcha": "CAPTCHA_TOKEN"
  }'

Presets

Get Presets

Retrieve user’s test presets.

curl https://api.monkeytype.com/presets \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Preset

Create a new test preset.

curl -X POST https://api.monkeytype.com/presets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Preset",
    "config": {
      "mode": "time",
      "time": 60,
      "language": "english",
      "difficulty": "normal"
    }
  }'

Update Preset

Update an existing preset.

curl -X PATCH https://api.monkeytype.com/presets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "_id": "507f1f77bcf86cd799439011",
    "name": "Updated Name",
    "config": {}
  }'

Delete Preset

Delete a preset by ID.

curl -X DELETE https://api.monkeytype.com/presets/{presetId} \
  -H "Authorization: Bearer YOUR_TOKEN"

ApeKeys

List ApeKeys

Retrieve all API keys for the current user.

curl https://api.monkeytype.com/ape-keys \
  -H "Authorization: Bearer YOUR_TOKEN"

Generate ApeKey

Create a new API key.

curl -X POST https://api.monkeytype.com/ape-keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "enabled": true
  }'

Update ApeKey

Modify an existing API key.

curl -X PATCH https://api.monkeytype.com/ape-keys/{apeKeyId} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "enabled": false}'

Delete ApeKey

Delete an API key.

curl -X DELETE https://api.monkeytype.com/ape-keys/{apeKeyId} \
  -H "Authorization: Bearer YOUR_TOKEN"

Custom Themes

Get Custom Themes

Retrieve all custom themes for the current user.

curl https://api.monkeytype.com/users/customThemes \
  -H "Authorization: Bearer YOUR_TOKEN"

data

array

Array of custom theme objects with colors

Create Custom Theme

Create a new custom theme.

curl -X POST https://api.monkeytype.com/users/customThemes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Theme",
    "colors": {
      "bg": "#323437",
      "main": "#e2b714",
      "caret": "#e2b714",
      "sub": "#646669",
      "text": "#d1d0c5",
      "error": "#ca4754",
      "errorExtra": "#7e2a33",
      "colorfulError": "#ca4754",
      "colorfulErrorExtra": "#7e2a33"
    }
  }'

name

string

required

Theme name (1-16 characters)

colors

object

required

Show Theme colors

string

required

Background color (hex)

main

string

required

Main color (hex)

caret

string

required

Caret color (hex)

sub

string

required

Sub color (hex)

text

string

required

Text color (hex)

error

string

required

Error color (hex)

errorExtra

string

required

Error extra color (hex)

colorfulError

string

required

Colorful error color (hex)

colorfulErrorExtra

string

required

Colorful error extra color (hex)

data

object

Created theme with _id and name

Update Custom Theme

Update an existing custom theme.

curl -X PATCH https://api.monkeytype.com/users/customThemes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "themeId": "507f1f77bcf86cd799439011",
    "theme": {
      "name": "Updated Theme",
      "colors": {...}
    }
  }'

themeId

string

required

Theme ID to update

theme

object

required

Theme object with name and colors

Delete Custom Theme

Delete a custom theme.

curl -X DELETE https://api.monkeytype.com/users/customThemes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"themeId": "507f1f77bcf86cd799439011"}'

themeId

string

required

Theme ID to delete

Inbox

Get Inbox

Retrieve user’s inbox messages.

curl https://api.monkeytype.com/users/inbox \
  -H "Authorization: Bearer YOUR_TOKEN"

data

object

Show Inbox data

inbox

array

Array of mail objects

maxMail

number

Maximum number of messages allowed

Update Inbox

Mark messages as read or delete them.

curl -X PATCH https://api.monkeytype.com/users/inbox \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mailIdsToMarkRead": ["uuid1", "uuid2"],
    "mailIdsToDelete": ["uuid3"]
  }'

mailIdsToMarkRead

array

Array of message UUIDs to mark as read

mailIdsToDelete

array

Array of message UUIDs to delete

Streak

Get Streak

Retrieve user’s streak data.

curl https://api.monkeytype.com/users/streak \
  -H "Authorization: Bearer YOUR_TOKEN"

data

object

Show Streak data

length

number

Current streak length in days

maxLength

number

Maximum streak length achieved

lastResultTimestamp

number

Timestamp of last result

hourOffset

number

Hour offset for streak calculation

Set Streak Hour Offset

Set the hour offset for streak calculation (can only be set once).

curl -X PATCH https://api.monkeytype.com/users/streak/hourOffset \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hourOffset": -5}'

hourOffset

number

required

Hour offset (-11 to 12)

This can only be set once and cannot be changed.

Connections

Get Connections

Retrieve user’s connections (friends).

curl "https://api.monkeytype.com/connections?status=accepted&type=outgoing" \
  -H "Authorization: Bearer YOUR_TOKEN"

status

string

Filter by status: “pending”, “accepted”, “rejected”, “blocked”

type

string

Filter by type: “incoming”, “outgoing”

data

array

Array of connection objects

Create Connection

Send a friend request to another user.

curl -X POST https://api.monkeytype.com/connections \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"receiverName": "username"}'

receiverName

string

required

Username of the user to connect with

data

object

Created connection object with status “pending”

Update Connection

Accept, reject, or block a connection request.

curl -X PATCH https://api.monkeytype.com/connections/{id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "accepted"}'

string

required

Connection ID

status

string

required

New status: “accepted”, “rejected”, or “blocked”

Delete Connection

Remove a connection.

curl -X DELETE https://api.monkeytype.com/connections/{id} \
  -H "Authorization: Bearer YOUR_TOKEN"

string

required

Connection ID to delete

Discord Integration

Get Discord OAuth Link

Get the OAuth link to start Discord integration.

curl https://api.monkeytype.com/users/discord/oauth \
  -H "Authorization: Bearer YOUR_TOKEN"

data

object

url

string

Discord OAuth URL to redirect user to

Link Discord Account

Link a Discord account after OAuth callback.

curl -X POST https://api.monkeytype.com/users/discord/link \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenType": "Bearer",
    "accessToken": "DISCORD_ACCESS_TOKEN",
    "state": "STATE_FROM_OAUTH"
  }'

tokenType

string

required

Token type from Discord OAuth

accessToken

string

required

Access token from Discord OAuth

state

string

required

State parameter from OAuth (20 characters)

data

object

discordId

string

Linked Discord user ID

discordAvatar

string

Discord avatar URL

Unlink Discord Account

Unlink the connected Discord account.

curl -X POST https://api.monkeytype.com/users/discord/unlink \
  -H "Authorization: Bearer YOUR_TOKEN"

Additional User Endpoints

Get Test Activity

Retrieve complete test activity data (premium feature).

curl https://api.monkeytype.com/users/testActivity \
  -H "Authorization: Bearer YOUR_TOKEN"

Requires premium subscription.

data

object

Test activity data organized by year and day

Update Profile

Update user’s public profile information.

curl -X PATCH https://api.monkeytype.com/users/profile \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bio": "Typing enthusiast",
    "keyboard": "Custom 60%",
    "selectedBadgeId": 1,
    "socialProfiles": {
      "twitter": "username",
      "github": "username"
    },
    "showActivityOnPublicProfile": true
  }'

bio

string

User biography

keyboard

string

Keyboard information

selectedBadgeId

number

ID of badge to display on profile

Social media profile usernames

showActivityOnPublicProfile

boolean

Whether to show test activity on public profile

Get Favorite Quotes

Retrieve user’s favorite quotes.

curl https://api.monkeytype.com/users/favoriteQuotes \
  -H "Authorization: Bearer YOUR_TOKEN"

data

object

Favorite quotes organized by language

Add Favorite Quote

Add a quote to favorites.

curl -X POST https://api.monkeytype.com/users/favoriteQuotes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "english",
    "quoteId": "123"
  }'

language

string

required

Language code

quoteId

string

required

Quote ID to add to favorites

Remove Favorite Quote

Remove a quote from favorites.

curl -X DELETE https://api.monkeytype.com/users/favoriteQuotes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "english",
    "quoteId": "123"
  }'

language

string

required

Language code

quoteId

string

required

Quote ID to remove from favorites

Error Responses

All endpoints may return these common error responses:

{
  "message": "Invalid request parameters"
}

Rate Limits

Endpoints have varying rate limits. Common limits:

User endpoints: 30-60 requests per minute
Result submission: 500 per day
Leaderboards: 60 per minute
Config updates: 120 per hour

See Authentication for rate limit details.

Contributing

Architecture

API Reference

​Users

​Get User Data

​Create User

​Get User Profile

​Update Username

​Results

​Submit Test Result

​Get Results

​Get Result by ID

​Delete All Results

​Leaderboards

​Get All-Time Leaderboard

​Get Leaderboard Rank

​Get Daily Leaderboard

​Get Weekly XP Leaderboard

​Configs

​Get User Configuration

​Update Configuration

​Quotes

​Get Quote Submissions

​Submit Quote

​Report Quote

​Presets

​Get Presets

​Create Preset

​Update Preset

​Delete Preset

​ApeKeys

​List ApeKeys

​Generate ApeKey

​Update ApeKey

​Delete ApeKey

​Tags

​Get Tags

​Create Tag

​Update Tag

​Delete Tag

​Delete Tag Personal Best

​Custom Themes

​Get Custom Themes

​Create Custom Theme

​Update Custom Theme

​Delete Custom Theme

​Inbox

​Get Inbox

​Update Inbox

​Streak

​Get Streak

​Set Streak Hour Offset

​Connections

​Get Connections

​Create Connection

​Update Connection

​Delete Connection

​Discord Integration

​Get Discord OAuth Link

​Link Discord Account

​Unlink Discord Account

​Additional User Endpoints

​Get Test Activity

​Update Profile

​Get Favorite Quotes

​Add Favorite Quote

​Remove Favorite Quote

​Error Responses

​Rate Limits

Build docs developers (and LLMs) love

Users

Get User Data

Create User

Get User Profile

Update Username

Results

Submit Test Result

Get Results

Get Result by ID

Delete All Results

Leaderboards

Get All-Time Leaderboard

Get Leaderboard Rank

Get Daily Leaderboard

Get Weekly XP Leaderboard

Configs

Get User Configuration

Update Configuration

Quotes

Get Quote Submissions

Submit Quote

Report Quote

Presets

Get Presets

Create Preset

Update Preset

Delete Preset

ApeKeys

List ApeKeys

Generate ApeKey

Update ApeKey

Delete ApeKey

Tags

Get Tags

Create Tag

Update Tag

Delete Tag

Delete Tag Personal Best

Custom Themes

Get Custom Themes

Create Custom Theme

Update Custom Theme

Delete Custom Theme

Inbox

Get Inbox

Update Inbox

Streak

Get Streak

Set Streak Hour Offset

Connections

Get Connections

Create Connection

Update Connection

Delete Connection

Discord Integration

Get Discord OAuth Link

Link Discord Account

Unlink Discord Account

Additional User Endpoints

Get Test Activity

Update Profile

Get Favorite Quotes

Add Favorite Quote

Remove Favorite Quote

Error Responses

Rate Limits