API Endpoints
Authentication/Registering Users
When you want a user to launch into a TryHackMe room, you will send a POST request to the URL below. The apiKey parameter is the API key required to authenticate the request. The userId parameter is a unique string used to represent your user and the roomCode is the code of the room that the user is trying to access. A successful request will return a 200 status code with a URL:
- If the user has not authenticated to TryHackMe through this API endpoint, the URL will point to a unique sign up page that redirects a user to a room after successful registration
- If that user has authenticated to TryHackMe through this API endpoint, the URL will automatically enter a user into a room
The request body parameters are
The headers & data encoding are
The expected successful response is
Retrieve User Progress
This endpoint returns users progress in the specified room. The {ROOM-CODE} parameter is the room code you would like to receive data from.
The API key needs to be provided inside the THM-API-KEY header as follows
The expected successful response is
Data will only show for users that are in the room, and that have been created through the /api/external/authenticate
endpoint. If you've generated a user through this endpoint, they'll also need to sign up and join the room.
Retrieving Users
This endpoint is used to retrieve all the users that have signed up using the API.
The API key needs to be provided inside the THM-API-KEY header as follows
The expected successful response is as follows
Remove Users From Room
This endpoint is used to remove a user from a room.
The request body parameters are
The headers & data encoding are
The expected successful response is as follows
Retrieve Rooms
This endpoint is used to retrieve details of public and the user's private rooms on the platform. The users field is only returned for a room that owned/managed by the API user.
The API key needs to be provided inside the THM-API-KEY header as follows
The expected successful response is as follows
Check If Room Exists
This endpoint is used to check if a room exists on the platform using the {ROOM-CODE} as a URL parameter..
The API key needs to be provided inside the THM-API-KEY header as follows
The expected successful response is as follows
Room Questions
This endpoint is used to retrieve questions associated with a {ROOM-CODE}. This endpoint retrieves questions associated with public rooms and private rooms owned by the API user.
The API key needs to be provided inside the THM-API-KEY header as follows
The expected successful response is as follows
Status Codes & Error Handling
A successful request to any of these endpoints 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 response as follows