hackerrank¶
Installation¶
$ pip install hackerrank
This is tested on Python 3.13+.
Usage¶
Generate an API token from the HackerRank for Work tokens page and pass it to hackerrank.client.HackerRank:
"""Example usage."""
import sys
from hackerrank.client import HackerRank
client = HackerRank(api_key="your-api-key")
for test in client.tests.list().data:
_ = sys.stdout.write(test.name)
interview = client.interviews.create(title="My Interview")
_ = sys.stdout.write(interview.url)
Project directory uploads¶
Use client.questions.upload_project_directory(question_id=..., directory=Path(...)) to upload a prepared directory for a fullstack question.
The client includes every file, including hidden files, with its relative path and original bytes.
It builds a ZIP in memory and delegates to upload_project_zip, preserving the API response and retry behavior.
No temporary archive is created.
After a read timeout, both upload methods check the stored archive before retrying.
Matching file names and contents prove success even if HackerRank repackaged the ZIP.
Unverified uploads retain the original timeout and configured retry policy.
Archive downloads omit the API authorization header.
Built-in transports accept project_upload_timeout to tune uploads independently of ordinary requests and verification reads.
Omitting it preserves the normal transport timeout.
The asynchronous method performs file operations and compression in a worker thread.
Missing directories and regular files raise NotADirectoryError.
Symbolic links within the directory raise ValueError.
An empty directory produces an empty ZIP.
Filtering and transformations belong in the caller.
Use shutil.copytree() with an ignore callback and tempfile.TemporaryDirectory to prepare and clean up a staging directory.
Already-prepared directories can be uploaded directly without copying.
"""Filter a directory, then upload the staged files."""
from pathlib import Path
from shutil import copytree, ignore_patterns
from tempfile import TemporaryDirectory
from hackerrank.client import HackerRank
with TemporaryDirectory() as temporary:
source = Path(temporary) / "source"
source.mkdir()
_ = (source / "main.py").write_text(
data="print('Hello')\n", encoding="utf-8"
)
directory = Path(
copytree(
src=source,
dst=Path(temporary) / "upload",
ignore=ignore_patterns("node_modules", "__pycache__", "*.pyc"),
)
)
with HackerRank(api_key="your-api-key") as client:
_response = client.questions.upload_project_directory(
question_id="q1", directory=directory
)
HTTPX2 transports¶
HTTPX remains the default client family.
To opt in to HTTPX2, construct the HTTPX2 transport explicitly and pass it to the client.
The standard hackerrank installation includes both client families.
"""Configure HackerRank to use HTTPX2."""
import httpx2
from hackerrank.client import HackerRank
from hackerrank.transports import HTTPX2Transport
transport = HTTPX2Transport(timeout=httpx2.Timeout(timeout=10))
with HackerRank(api_key="your-api-key", transport=transport) as client:
tests = client.tests.list()
Use AsyncHTTPX2Transport with AsyncHackerRank for asynchronous calls.
The timeout argument accepts an HTTPX2 timeout object or a number of seconds.
Existing HTTPX users can keep their current configuration, but HTTPX2 transports require timeout objects from HTTPX2 when passing them across the package boundary.
Migrating to HTTPX2 only requires selecting the new transport.
HackerRank client methods and returned models are unchanged.
See the API Reference for full usage details.
Reference¶
- API Reference
InterviewsNamespaceExplicitSharingRolesNamespaceInterviewTemplatesNamespaceInterviewTemplatesNamespace.iter_all()InterviewTemplatesNamespace.list()InterviewTemplatesNamespace.create()InterviewTemplatesNamespace.get()InterviewTemplatesNamespace.update()InterviewTemplatesNamespace.delete()InterviewTemplatesNamespace.add_questions()InterviewTemplatesNamespace.remove_question()
EnvironmentsNamespaceQuestionsNamespaceQuestionsNamespace.iter_all()QuestionsNamespace.list()QuestionsNamespace.create()QuestionsNamespace.get()QuestionsNamespace.update()QuestionsNamespace.update_internal_notes()QuestionsNamespace.update_metadata()QuestionsNamespace.upload_project_directory()QuestionsNamespace.upload_project_zip()QuestionsNamespace.update_codestubs()QuestionsNamespace.generate_codestubs()QuestionsNamespace.add_testcase()QuestionsNamespace.update_testcase()QuestionsNamespace.delete_testcase()QuestionsNamespace.delete_all_testcases()
TestCandidatesNamespaceTestsNamespaceTemplatesNamespaceCandidatesNamespaceUsersNamespaceTeamMembershipsNamespaceTeamsNamespaceAuditLogsNamespaceATSCodePairNamespaceATSCodeScreenNamespaceATSNamespaceSCIMUsersNamespaceSCIMGroupsNamespaceSCIMNamespaceAPINamespaceHackerRankHackerRank.base_urlHackerRank.scim_base_urlHackerRank.apiHackerRank.interviewsHackerRank.interview_templatesHackerRank.environmentsHackerRank.questionsHackerRank.testsHackerRank.templatesHackerRank.candidatesHackerRank.usersHackerRank.teamsHackerRank.audit_logsHackerRank.atsHackerRank.scimHackerRank.close()
AsyncInterviewsNamespaceAsyncInterviewsNamespace.list()AsyncInterviewsNamespace.create()AsyncInterviewsNamespace.get()AsyncInterviewsNamespace.update()AsyncInterviewsNamespace.delete()AsyncInterviewsNamespace.get_transcript()AsyncInterviewsNamespace.get_artifacts()AsyncInterviewsNamespace.get_notes()AsyncInterviewsNamespace.update_note()
AsyncExplicitSharingRolesNamespaceAsyncInterviewTemplatesNamespaceAsyncInterviewTemplatesNamespace.iter_all()AsyncInterviewTemplatesNamespace.list()AsyncInterviewTemplatesNamespace.create()AsyncInterviewTemplatesNamespace.get()AsyncInterviewTemplatesNamespace.update()AsyncInterviewTemplatesNamespace.delete()AsyncInterviewTemplatesNamespace.add_questions()AsyncInterviewTemplatesNamespace.remove_question()
AsyncEnvironmentsNamespaceAsyncQuestionsNamespaceAsyncQuestionsNamespace.iter_all()AsyncQuestionsNamespace.list()AsyncQuestionsNamespace.get()AsyncQuestionsNamespace.create()AsyncQuestionsNamespace.update()AsyncQuestionsNamespace.update_internal_notes()AsyncQuestionsNamespace.update_metadata()AsyncQuestionsNamespace.upload_project_directory()AsyncQuestionsNamespace.upload_project_zip()AsyncQuestionsNamespace.update_codestubs()AsyncQuestionsNamespace.generate_codestubs()AsyncQuestionsNamespace.add_testcase()AsyncQuestionsNamespace.update_testcase()AsyncQuestionsNamespace.delete_testcase()AsyncQuestionsNamespace.delete_all_testcases()
AsyncTestCandidatesNamespaceAsyncTestCandidatesNamespace.list()AsyncTestCandidatesNamespace.search()AsyncTestCandidatesNamespace.invite()AsyncTestCandidatesNamespace.get()AsyncTestCandidatesNamespace.update()AsyncTestCandidatesNamespace.cancel_invite()AsyncTestCandidatesNamespace.delete_report()AsyncTestCandidatesNamespace.get_report_pdf()
AsyncTestsNamespaceAsyncTemplatesNamespaceAsyncCandidatesNamespaceAsyncUsersNamespaceAsyncTeamMembershipsNamespaceAsyncTeamsNamespaceAsyncAuditLogsNamespaceAsyncATSCodePairNamespaceAsyncATSCodeScreenNamespaceAsyncATSNamespaceAsyncSCIMUsersNamespaceAsyncSCIMGroupsNamespaceAsyncSCIMNamespaceAsyncAPINamespaceAsyncHackerRankAsyncHackerRank.base_urlAsyncHackerRank.scim_base_urlAsyncHackerRank.apiAsyncHackerRank.interviewsAsyncHackerRank.interview_templatesAsyncHackerRank.environmentsAsyncHackerRank.questionsAsyncHackerRank.testsAsyncHackerRank.templatesAsyncHackerRank.candidatesAsyncHackerRank.usersAsyncHackerRank.teamsAsyncHackerRank.audit_logsAsyncHackerRank.atsAsyncHackerRank.scimAsyncHackerRank.aclose()
DEFAULT_TIMEOUT_SECONDSHTTPStatusErrorTransportResponseTransportHTTPXTransportHTTPX2TransportAsyncTransportAsyncHTTPXTransportAsyncHTTPX2TransportQuestionTypeQuestionAnswerJSONValuePageSCIMPageCandidateDetailCandidateSearchAttemptResultCandidateSearchAttemptResult.attempt_idCandidateSearchAttemptResult.test_idCandidateSearchAttemptResult.report_urlCandidateSearchAttemptResult.scoreCandidateSearchAttemptResult.percentage_scoreCandidateSearchAttemptResult.attempt_starttimeCandidateSearchAttemptResult.attempt_endtimeCandidateSearchAttemptResult.from_dict()
CandidateSearchResultInterviewerInterviewInterview.idInterview.statusInterview.urlInterview.titleInterview.feedbackInterview.thumbs_upInterview.notesInterview.resume_urlInterview.interviewersInterview.result_urlInterview.candidateInterview.metadataInterview.report_urlInterview.ended_atInterview.interview_template_idInterview.created_atInterview.updated_atInterview.userInterview.send_emailInterview.from_Interview.toInterview.started_atInterview.ai_assistant_availableInterview.from_dict()
InterviewTranscriptMessageInterviewTranscriptInterviewTemplateInterviewTemplate.idInterviewTemplate.nameInterviewTemplate.created_atInterviewTemplate.statusInterviewTemplate.userInterviewTemplate.rolesInterviewTemplate.team_shareInterviewTemplate.questionsInterviewTemplate.scorecardInterviewTemplate.import_templateInterviewTemplate.editor_accessInterviewTemplate.from_dict()
EnvironmentRuntimeEnvironmentQuestionQuestion.idQuestion.typeQuestion.nameQuestion.unique_idQuestion.ownerQuestion.created_atQuestion.statusQuestion.internal_notesQuestion.languagesQuestion.problem_statementQuestion.recommended_durationQuestion.tagsQuestion.max_scoreQuestion.optionsQuestion.answerQuestion.test_case_countQuestion.role_typeQuestion.environment_idQuestion.file_urlQuestion.file_pathQuestion.has_valid_stacksQuestion.fullstack_project_detailsQuestion.custom_system_promptQuestion.supports_custom_system_promptQuestion.from_dict()
QuestionChangesQuestionChanges.nameQuestionChanges.internal_notesQuestionChanges.languagesQuestionChanges.problem_statementQuestionChanges.recommended_durationQuestionChanges.tagsQuestionChanges.optionsQuestionChanges.answerQuestionChanges.scoreQuestionChanges.environment_idQuestionChanges.role_typeQuestionChanges.scoring_commandQuestionChanges.scoring_filesQuestionChanges.readonly_pathsQuestionChanges.default_filesQuestionChanges.configurationQuestionChanges.testcasesQuestionChanges.custom_system_promptQuestionChanges.to_dict()
TestCandidateDetailFieldTestTest.idTest.nameTest.unique_idTest.starttimeTest.endtimeTest.durationTest.ownerTest.instructionsTest.starredTest.created_atTest.stateTest.lockedTest.draftTest.languagesTest.candidate_detailsTest.custom_acknowledge_textTest.cutoff_scoreTest.master_passwordTest.hide_compile_testTest.tagsTest.role_idsTest.experienceTest.questionsTest.sectionsTest.mcq_incorrect_scoreTest.mcq_correct_scoreTest.locked_byTest.short_login_urlTest.public_login_urlTest.shuffle_questionsTest.test_adminsTest.hide_templateTest.enable_acknowledgementTest.enable_proctoringTest.enable_advanced_proctoringTest.enable_secure_assessment_modeTest.enable_ml_plagiarism_analysisTest.enable_photo_identificationTest.ide_configTest.from_dict()
TestCandidateTestCandidate.idTestCandidate.emailTestCandidate.full_nameTestCandidate.scoreTestCandidate.testTestCandidate.userTestCandidate.attempt_starttimeTestCandidate.attempt_endtimeTestCandidate.attempt_eventsTestCandidate.statusTestCandidate.ats_stateTestCandidate.integrity_statusTestCandidate.integrity_summaryTestCandidate.invite_email_doneTestCandidate.invite_validTestCandidate.invited_onTestCandidate.invite_valid_fromTestCandidate.invite_valid_toTestCandidate.invite_linkTestCandidate.invite_metadataTestCandidate.evaluator_emailTestCandidate.test_finish_urlTestCandidate.test_result_urlTestCandidate.accept_result_updatesTestCandidate.tagsTestCandidate.report_urlTestCandidate.authenticated_report_urlTestCandidate.pdf_urlTestCandidate.scores_tags_splitTestCandidate.scores_skills_splitTestCandidate.added_timeTestCandidate.unclaimed_added_timeTestCandidate.commentsTestCandidate.performance_summaryTestCandidate.ip_addressTestCandidate.questionsTestCandidate.plagiarismTestCandidate.plagiarism_statusTestCandidate.max_code_similarityTestCandidate.feedbackTestCandidate.percentage_scoreTestCandidate.candidate_detailsTestCandidate.out_of_window_eventsTestCandidate.out_of_window_durationTestCandidate.editor_paste_countTestCandidate.proctor_imagesTestCandidate.from_dict()
InviterInviter.idInviter.emailInviter.firstnameInviter.lastnameInviter.roleInviter.statusInviter.phoneInviter.timezoneInviter.questions_permissionInviter.tests_permissionInviter.interviews_permissionInviter.candidates_permissionInviter.teamsInviter.candidates_invitedInviter.activatedInviter.from_dict()
UserUser.idUser.emailUser.firstnameUser.lastnameUser.countryUser.roleUser.statusUser.phoneUser.timezoneUser.questions_permissionUser.tests_permissionUser.interviews_permissionUser.candidates_permissionUser.shared_questions_permissionUser.shared_tests_permissionUser.shared_interviews_permissionUser.shared_candidates_permissionUser.company_adminUser.team_adminUser.teamsUser.activatedUser.last_activity_timeUser.from_dict()
TeamUserTeamMembershipTemplateAuditLogCandidateInviteATSCodePairATSCodeScreenSCIMUserSCIMTeamUserUpdateUserUpdate.firstnameUserUpdate.lastnameUserUpdate.countryUserUpdate.roleUserUpdate.phoneUserUpdate.questions_permissionUserUpdate.tests_permissionUserUpdate.interviews_permissionUserUpdate.candidates_permissionUserUpdate.shared_questions_permissionUserUpdate.shared_tests_permissionUserUpdate.shared_interviews_permissionUserUpdate.shared_candidates_permissionUserUpdate.company_adminUserUpdate.team_adminUserUpdate.to_dict()
TestsUpdateTestsUpdate.nameTestsUpdate.starttimeTestsUpdate.endtimeTestsUpdate.durationTestsUpdate.instructionsTestsUpdate.lockedTestsUpdate.draftTestsUpdate.languagesTestsUpdate.candidate_detailsTestsUpdate.custom_acknowledge_textTestsUpdate.cutoff_scoreTestsUpdate.master_passwordTestsUpdate.hide_compile_testTestsUpdate.tagsTestsUpdate.role_idsTestsUpdate.experienceTestsUpdate.questionsTestsUpdate.mcq_incorrect_scoreTestsUpdate.mcq_correct_scoreTestsUpdate.shuffle_questionsTestsUpdate.test_adminsTestsUpdate.hide_templateTestsUpdate.enable_acknowledgementTestsUpdate.enable_proctoringTestsUpdate.enable_advanced_proctoringTestsUpdate.enable_secure_assessment_modeTestsUpdate.enable_ml_plagiarism_analysisTestsUpdate.enable_photo_identificationTestsUpdate.ide_configTestsUpdate.to_dict()
SCIMMessageAuditLogCursorPagePaginationErrorHackerRankErrorRedirectErrorBadRequestErrorAuthenticationErrorForbiddenErrorNotFoundErrorConflictErrorUnprocessableEntityErrorRateLimitErrorServerErrorInterviewArtifactDescriptorInterviewArtifactQuestionInterviewArtifactNoteInterviewArtifactsInterviewArtifactsPendingInterviewNoteAPIOperationAPIResponseapi_catalogue()api_operations()prepare_operation()parse_api_object()
- OpenAPI Spec
- Contributing to hackerrank
- Release Process
- Unreleased changes
- [UNRELEASED DRAFT] (2026-11-12)
- Changelog
- 2026.11.10.4 (2026-11-10)
- 2026.11.10.3 (2026-11-10)
- 2026.11.10.2 (2026-11-10)
- 2026.11.10.1 (2026-11-10)
- 2026.11.10 (2026-11-10)
- 2026.11.07 (2026-11-07)
- 2026.11.03.1 (2026-11-03)
- 2026.11.03 (2026-11-03)
- 2026.11.02 (2026-11-02)
- 2026.10.30.1 (2026-10-30)
- 2026.10.30 (2026-10-30)
- 2026.10.09 (2026-10-09)
- 2026.09.16
- 2026.09.07
- 2026.08.28
- 2026.08.27
- 2026.08.22
- 2026.08.16
- 2026.07.30
- 2026.07.19
- 2026.07.08
- 2026.05.12.2
- 2026.05.12.1
- 2026.05.12
Question answer representations¶
Question.answer preserves the API’s answer representation: a string, an integer, a list of integers, or None for an absent or null answer.
QuestionAnswer describes the three non-null forms accepted by typed question creation and updates.
Strings are neither parsed as numbers nor split into characters.
An omitted or None answer on creation remains omitted from the request.
Inventory pagination¶
client.questions.iter_all(), client.interview_templates.iter_all(), and client.teams.iter_all() read all reachable inventory records.
Use the existing listing filters, such as status="active" for questions or filter="owned" for templates.
The positive page_size argument defaults to 100.
Async clients return asynchronous iterators for async for.
Requests are lazy and use the client’s normal retry policy. Filter lists are copied when the iterator is created. Each request advances by the number of records actually returned, so short pages do not discard later results. Missing totals are handled by continuing until an empty page. Next-page URLs from responses are not followed.
A repeated page or an exhausted server offset window raises hackerrank.exceptions.PaginationError rather than presenting partial inventory as complete.
Narrow the listing filters when the API offset window prevents reaching every result.
Selected question metadata updates¶
Use questions.update_metadata(question_id=..., changes=QuestionChanges(...)) to replace selected fields without rebuilding the required update payload.
QuestionChanges is available from hackerrank.types on both clients.
The helper reads the current question, preserves its identifier and type, and sends required metadata with the selected changes.
Other optional fields are omitted so project settings and existing assistant prompts remain untouched.
None preserves a field; empty strings, empty lists, and zero are explicit changes.
If the resulting metadata lacks a problem statement or recommended duration, the helper raises ValueError before writing.
Custom system prompts use the same type and length validation as ordinary question updates.
Every call sends the merged metadata, even if unchanged.
The read and write are separate API requests.
Concurrent edits are not locked.
The existing update_internal_notes helper now calls update_metadata.