API Endpoints - Monkeytype

Users

Get User Data

Retrieve complete user profile and settings.

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

const response = await fetch('https://api.monkeytype.com/users', {
  headers: { 'Authorization': `Bearer ${token}` }
});
const { data } = await response.json();

object

Show User object

string

required

User’s unique identifier

string

required

Username

string

required

User’s email address

number

required

Account creation timestamp

object

required

Personal best records by mode

number

Total number of completed tests

number

Total number of started tests

number

Total seconds spent typing

number

Total XP earned

object

Current and max streak information

boolean

Premium subscription status

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": "user@example.com",
    "captcha": "CAPTCHA_TOKEN"
  }'

string

required

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

string

User’s email address

string

required

Google reCAPTCHA token

Get User Profile

Retrieve public profile of any user.

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

string

required

Username or user ID

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"
    }
  }'

object

required

Show CompletedEvent object

number

required

Words per minute

number

required

Raw WPM (includes errors)

number

required

Accuracy percentage (0-100)

string

required

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

string

required

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

string

required

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

number

required

Test completion timestamp

number

required

Test duration in seconds

number

required

Consistency percentage

string

required

Object hash for verification

object

Show PostResultResponse

boolean

Whether this result is a personal best

string

Database ID of inserted result

number

XP gained from this result

object

Detailed XP calculation breakdown

boolean

Whether daily XP bonus was applied

number

Current streak length

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"

number

default:"50"

Number of results to return (max 1000)

number

default:"0"

Offset for pagination

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"

string

required

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

string

required

Test mode: “time” or “words”

string

required

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

number

default:"0"

Page number (0-indexed)

number

default:"50"

Results per page (10-200)

boolean

default:"false"

Show only friends (requires authentication)

object

Show Leaderboard response

array

Array of leaderboard entries

number

Total number of entries

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"

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"

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"
  }'

string

required

Quote text (minimum 60 characters)

string

required

Quote author or source

string

required

Language code

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"

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"
    }
  }'

string

required

Theme name (1-16 characters)

object

required

Show Theme colors

string

required

Background color (hex)

string

required

Main color (hex)

string

required

Caret color (hex)

string

required

Sub color (hex)

string

required

Text color (hex)

string

required

Error color (hex)

string

required

Error extra color (hex)

string

required

Colorful error color (hex)

string

required

Colorful error extra color (hex)

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": {...}
    }
  }'

string

required

Theme ID to update

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"}'

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"

object

Show Inbox data

array

Array of mail objects

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"]
  }'

array

Array of message UUIDs to mark as read

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"

object

Show Streak data

number

Current streak length in days

number

Maximum streak length achieved

number

Timestamp of last result

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}'

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"

string

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

string

Filter by type: “incoming”, “outgoing”

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"}'

string

required

Username of the user to connect with

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

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"

object

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"
  }'

string

required

Token type from Discord OAuth

string

required

Access token from Discord OAuth

string

required

State parameter from OAuth (20 characters)

object

string

Linked Discord user ID

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.

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
  }'

string

User biography

string

Keyboard information

number

ID of badge to display on profile

Social media profile usernames

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"

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"
  }'

string

required

Language code

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"
  }'

string

required

Language code

string

required

Quote ID to remove from favorites

Error Responses

All endpoints may return these common error responses:

{
  "message": "Invalid request parameters"
}

{
  "message": "Unauthorized"
}

{
  "message": "Invalid request data schema",
  "validationErrors": [
    "wpm must be a positive number",
    "mode is required"
  ]
}

{
  "message": "Request limit reached, please try again later."
}

{
  "message": "Test is too short"
}

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.

​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

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