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
To get access to the teaching program, please send an email to [email protected] or [email protected].
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": null }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." }