Skip to main content
Enterprise API
Blackout avatar
Written by Blackout
Updated over a week ago

Instructors that are part of the TryHackMe Business or Classroom plans get access to a set of API features that they can use to perform various functions such as:

  • register/authenticate users

  • retrieve users' room data

  • retrieve public rooms

Registering API-Users to Platform

Create TryHackMe account for company/client api-user, if the user successfully registers their email gets updated on company api-user.

This link will show a custom message, company logo, and company name when you get to the signup page.

Request Endpoint:

GET <https://tryhackme.com/external/api/register?token={api-user-token}>

Response:

Success redirects to ‘/signup’, Fail redirects to ‘/404

Authenticate API-Users

Add new api-user to company and return registration link **and has the following scenarios:

  • If api-user does not exist, add them to the company api-users and give link to register

  • If api-user exists but not registered, returns link to register to the platform.

  • If api-user exists and is registered, returns link to join the room.

Request Endpoint:

POST <https://tryhackme.com/external/api/authenticate>

Headers:

THM-API-KEY: {api-key}

Body:

{ "extUserId": String, // unique external user id for adding to api-users "roomCode": String // TryHackMe room code }

Response:

{ "url": string }

Add/Remove user from Seat

This endpoint can be used to add (PUT) or remove (DELETE) a user from a seat in your management dashboard.

Request Endpoint:

PUT <https://tryhackme.com/api/v2/external/seats/users> (to add a user to a seat)

DELETE <https://tryhackme.com/api/v2/external/seats/users> (to remove a user from a seat)

Headers:

THM-API-KEY: {api-key}

Body:

{ "email": String }

Response:

{ "status": "success", "data": { "username": String } }

Error handling:

403 FORBIDDEN - Invalid or Missing API key:

{ "status": "error", "message": "API Key is invalid or has expired.", "stack": "Error: API Key is invalid or has expired. ..." }

400 BAD REQUEST - email missing from request body:

{ "status": "error", "message": "email is required.", "stack": "Error: email is required. ..." }

The below errors are returned by the PUT endpoint

400 BAD REQUEST - email not found (no user exists with this email):

{ "status": "error", "message": "email not found.", "stack": "Error: email not found. ..." }

400 BAD REQUEST - No available seats in dashboard.

{ "status": "error", "message": "no available seats in dashboard.", "stack": "Error: no available seats in dashboard. ..." }

400 BAD REQUEST - User already assigned to seat.

{ "status": "error", "message": "User already assigned to seat.", "stack": "Error: User already assigned to seat. ..." }

The below errors are returned by the DELETE endpoint

400 BAD REQUEST - User is not currently in a company seat.

{ "status": "error", "message": "User is not currently in a company seat.", "stack": "Error: User is not currently in a company seat. ..." }

Room Scoreboard

This endpoint returns the score and attempts your users have made in a particular room. Use the room-code as a URL parameter. Reminder: the room code is the final string in the room’s URL, i.e. https://tryhackme.com/room/{room-code}

Request Endpoint:

GET <https://tryhackme.com/api/v2/external/scoreboard?roomCode={room-code}>

Headers:

THM-API-KEY: {api-key}

Response:

{ "status": "success", "data": Array<{ "score": Number, "tasks": Record< String, Array<{ "correct": Boolean, "score": Number, "attempts": Number, "_id": String, "questionNo": Number, "timeCorrect": ISODateString, }> >; "level": Number, "avatar": String, "username": String, "rank": Number, }>; }

Error Handling:

403 FORBIDDEN - Invalid or Missing API key:

{ "status": "error", "message": "API Key is invalid or has expired.", "stack": "Error: API Key is invalid or has expired. ..." }

400 BAD REQUEST - roomCode query parameter is mandatory:

{ "status": "error", "message": "roomCode query parameter is mandatory", "stack": "Error: roomCode query parameter is mandatory. ..." }

404 NOT FOUND - Room not found:

{ "status": "error", "message": "Room not found.", "stack": "Error: Room not found. ..." }

Retrieving Users

This endpoint retrieves users on seats of company and api-users if they have registered to platform

Request Endpoint:

GET <https://tryhackme.com/external/api/users>

Headers:

THM-API-KEY: {api-key}

Response:

{ "status": true, "users": [ { "username": String, "email": String, "avatar": String, "totalPoint": Number, "monthlyPoints": Number, "dateSignedUp": ISO8601 UTC Datetime, "extUserId": String // only for api-users }, ] }

Remove Users From Room

This endpoint is used to remove a user (mark as left) from a room.

Request Endpoint:

POST <https://tryhackme.com/external/api/leaveRoom>

Headers:

THM-API-KEY: {api-key}

Body:

{ "extUserId": String, "roomCode": String }

Response:

{ }

Retrieve Rooms

This endpoint retrieves details of public and the user's private rooms on the platform.

Request Endpoint:

GET <https://tryhackme.com/external/api/rooms>

Headers:

THM-API-KEY: {api-key}

Response:

{ "roomInfo":[ { "code": String, "title": String, "description": String, "public": Boolean, } ] }

Check If Room Exists

This endpoint checks if a public room and the user's private rooms exists on the platform using the room-code as a URL parameter.

Request Endpoint:

GET <https://tryhackme.com/external/api/roomExists?roomCode={room-code}>

Headers:

THM-API-KEY: {api-key}

Response:

{ "roomExists": Boolean }

Room Questions

This endpoint is used to retrieve questions associated with a room-code, retrieves inquiries related to public rooms and private rooms owned by the client/company

Request Endpoint:

GET <https://tryhackme.com/external/api/questions?roomCode={room-code}>

Headers:

THM-API-KEY: {api-key}

Response:

{ "questions": [ { "taskNo": Integer, "infoList":[ { "questionNo": Integer, "question": String, "answer": String, "hint": String, "extraPoints": Integer } ] } ] }

Status Codes & Error Handling

A successful request to any endpoint will always return a 200 OK response.

A request to an endpoint that does not return a 200 OK response will contain a message parameter attached to the reaction as follows.

{ "message": "API Key is invalid or has expired." }

Contact

  • Existing B2B or EDU customer and have questions? Please contact your Customer Success Manager or Technical Support.

  • Please contact [email protected] if you'd like to explore whether TryHackMe could be a good fit for your organization. Alternatively, book a meeting directly with the Sales team: For Education, For Business

Did this answer your question?