This is the HackerEarth API V4 resource documentation. If you face any issues or have any requests, please contact support.

The API provides endpoints for compiling and running code in several languages. It can be accessed via an API key-based authorization process. You must register your web application in order to receive a client-specific client-secret that must be provided while communicating with the API.

Currently, there is a cap on the following:

1. Number of clients a user can register
2. Number of free requests a user can make.

Register your own client here. Register here for an API key.

How HackerEarth API v4 is different from API v3?

V4 will only support asynchronous code evaluation requests, unlike v3 which supported both synchronous and asynchronous. It also fixes issues in the async version of the v3 endpoints. In the asynchronous flow, a temporary response is returned immediately after the code execution request has been received. Internally, the request will be queued for further processing. In the meanwhile, you can use the getStatus API to retrieve the execution status of the code that you just submitted. We also have a callback feature, wherein if you pass a callback URL in the request, we send the response of compilation and execution to this URL. This way the client program doesn't wait on a response from hackerearth. More details are shared in the rest of the document.

In v3 you needed to make 2 API calls to 2 different endpoints to evaluate a piece of code against the given input. In v4 you only need to make 1 API call to the new endpoint, which will take care of compilation as well as the execution of the code.

Instead of sending the authentication details (client-secret) in the payload, you can now send it in the header, which is the preferred method. We have also added 1 reconciliation endpoint, which can be called to get the status of any previous code- evaluation request. The response body will contain the compile and execution results of the code-evaluation request in question.

ENDPOINTS

POST request for code evaluation(compile and execute)

https://api.hackerearth.com/v4/partner/code-evaluation/submissions/

Authentication

The client authentication is done using your unique client-secret. You need to register your web application in order to get a unique client-secret, which must be provided while communicating with the API. You need to pass this client secret in the header with the key as client-secret and value as the client secret you receive after registration.

Making requests

Content type

1. application/json

Request Headers You have to pass 2 mandatory headers:

1. content-type: This represents the MIME type of the request. The value has to be application/json.
2. client-secret: This is the client secret you receive after registration.

{
  "lang": "PYTHON",
  "source": "print 'Hello World'",
  "input": "",
  "memory_limit": 243232,
  "time_limit": 5,
  "context": “{‘id’: 213121}”,
  "callback": "https://client.com/callback/"
}

1. lang
   • Datatype: String
   • Required: True
   • This represents the programming language in which the source is written. You can find a list of all the supported languages below.
2. source
   • Datatype: String
   • Required: True
   • This is the actual code that needs to be compiled and executed.
3. input
   • Datatype: String
   • Required: False
   • This is the data that is passed to your program as input during execution.
4. memory_limit
   • Datatype: Integer
   • Required: False
   • This is the maximum memory (in KB) that can be used by the program. The maximum value of the memory limit can be 262144 (256 MB). Any value greater than 262144 in the API request is set to 262144. Exceeding the memory limit returns the status as MLE as the response.
5. time_limit
   • Datatype: Integer
   • Required: False
   • This is the maximum time (in seconds) for which the program is allowed to run. The maximum value of the time limit can be 5 seconds. Any value greater than 5 seconds in the API request is set to 5 seconds. Exceeding the time limit returns the status as TLE as the response.
6. context
   • Datatype: String
   • Required: False
   • Max length: 1024 chars
   • This attribute is provided for the client to pass any string data which is related to this request . If this is passed in the code evaluation request, then it is sent along with the compilation and execution results sent in the callback URL or the response for the get status API call, as it is. It can be used to pass any identifier which is relevant to client’s request or any contextual information that the client needs.
7. callback
   • Datatype: String
   • Required: False
   • This is the URL where the client can receive a POST request that contains the status of the current request for code evaluation. For each request made by the client, if a callback URL is present in the request, it is called twice—once after compilation is over and the other after the execution. If you use a callback URL, you don’t need to poll the get status URL to get the compilation and execution result. Please note that we retry a maximum of 3 times in case of failure and a maximum of 5 redirects are supported.

• POST request body after compilation is over:

  {
    "request_status": {
      "message": "Compilation step is over",
      "code": "CODE_COMPILED"
    },
    "errors": {},
    "he_id": "1466ca3e-a263-437a-a996-a816af0db499",
    "status_update_url": "https://api.hackerearth.com/v4/partner/code-evaluation/submissions/1466ca3e-a263-437a-a996-a816af0db499",
    "context": "{id: 213121}",
    "result": {
      "run_status": {},
      "compile_status": "OK"
    }
  }
  

• POST request body after execution is over:

  {
    "request_status": {
      "message": "Your request has been completed successfully",
      "code": "REQUEST_COMPLETED"
    },
    "errors": {},
    "he_id": "1466ca3e-a263-437a-a996-a816af0db499",
    "status_update_url": "https://api.hackerearth.com/v4/partner/code-evaluation/submissions/1466ca3e-a263-437a-a996-a816af0db499",
    "context": "{‘id’: 213121}",
    "result": {
      "run_status": {
        "memory_used": "3392",
        "status": "AC",
        "time_used": "0.033403",
        "signal": "OTHER",
        "exit_code": "0",
        "status_detail": "NA",
        "stderr": "",
        "output": "https://he-s3.s3.amazonaws.com/media/userdata/AnonymousUser/code/ee2123423155",
        "request_NOT_OK_reason": "",
        "request_OK": "True"
      },
      "compile_status": "OK"
    }
  }
  

{
    "request_status": {
        "message": "Your request has been queued in the evaluation pipeline",
        "code": "REQUEST_QUEUED"
    },
    "he_id": "6438b9a6-d5c0-4960-9049-b21a35f0bdb0",
    "result": {
        "run_status": {
            "status": "NA"
        },
        "compile_status": "Compiling..."
    },
    "context": "{‘id’: 213121}",
    "status_update_url": "https://api.hackerearth.com/v4/partner/code-evaluation/submissions/6438b9a6-d5c0-4960-9049-b21a3zz5f0bdb0/"
}

1. request_status: It represents the current status of the request. Possible values for request_status[“code”] are:
   • REQUEST_INITIATED: The request has been recorded and processing has been initiated.
   • REQUEST_QUEUED: The request has been queued in the evaluation pipeline.
   • CODE_COMPILED: Compilation is complete.
   • REQUEST_COMPLETED: Execution is complete.
   • REQUEST_FAILED: The request processing failed due to an internal issue.
2. he_id: It is a UUID4 string which uniquely identifies each request made by the client. It is used in the get status API call to get the status of the code evaluation request identified by this value.
3. result: It contains the compilation and execution results of the code evaluation request.
   • The result json contains run_result and compile_result attributes which in turn contains 2 status related attributes i.e. status and status_detail, which represents the execution and compilation result in terms of whether it executed successfully, or there was runtime error or a compilation error, etc. Below is a list of expected values of status and status_detail attributes:

     Status	Status detail	Explanation
     AC	NA	Accepted. The code executed successfully.
     MLE	NA	Memory Limit Exceeded. Execution of the compiled code used more memory that the memory limit
     TLE	NA	Time Limit Exceeded. Execution of the compiled code took more time than the passed time limit
     RE	SIGXFSZ SIGSEGV SIGFPE SIGBUS SIGABRT NZEC OTHER	SIGXFSZ: The output file size exceeded beyond allowed system value SIGSEGV: Invalid memory reference or segmentation fault SIGFPE: Division by 0 SIGBUS: Accessed memory location that has not been physically mapped. The address is valid but we failed to read/write. SIGABRT: Aborting due to a fatal error. NZEC or OTHER: If the user code execution stopped because of any reasons other than the above.

   • The output attribute in run_result is an S3 filepath from where the actual output can be downloaded.
4. context: It’s the context sent by the client while making the code evaluation request.
5. status_update_url: You can make a GET request to this URL to get the current status of your code evaluation request.

Error Response In case of an error with the above request, the response contains the details of the error.

1. If a required attribute is missing:

   {
       "message": "ArgumentMissingError: source is needed!",
       "errors": {}
   }
   

2. If your consumption exceeds API services quota. You can contact support in case you want to increase your API services quota.

   {
     "message": "QuotaExceededError: API usage quota exceeded",
     "errors": {
       "quota": 73000000,
       "current_count": 120189
     }
   }
   

3. If the client-secret header value is wrong

   {
       "message": "UnregisteredClientError: Client does not exist",
       "errors": { }
   }
   

Get request for getting status of a code evaluation request

https://api.hackerearth.com/v4/partner/code-evaluation/submissions/id/

The id parameter is the value of the he_id attribute you receive in the response while submitting the POST request for code evaluation. This he_id attribute uniquely identifies each request made by the client. Like the POST request above, this requires you to pass client-secret in the header for the purpose of authentication. The response format is the same as above.

Examples

Post request for code evaluation(compile and execute)

Python

import json
import requests

CODE_EVALUATION_URL = u'https://api.hackerearth.com/v4/partner/code-evaluation/submissions/'
CLIENT_SECRET = 'bc40b60349b9ddd98cf2fda31c9d1s7112chdsd85hs231'

def execute(source_file_name, language):
    source = open(source_file_name, "r")
    input_file = open("input.txt", "r")
    callback = "https://client.com/callback/"

    data = {    
        'source': source.read(),
        'lang': language,
        'time_limit': 5,
        'memory_limit': 246323,
        'input': input_file.read(),
        'callback' : callback,
        'id': "client-001"
    }
    headers = {"client-secret": CLIENT_SECRET}
    input_file.close()
    source.close()
    resp = requests.post(CODE_EVALUATION_URL, json=data, headers=headers)
    """
    This will also work:
    resp = requests.post(CODE_EVALUATION_URL, data=data, headers=headers)
    """
    dict = json.loads(resp.text)
    return dict

run("py_source.py", "PYTHON")

curl -X POST \
  https://api.hackerearth.com/v4/partner/code-evaluation/submissions/ \
  -H 'cache-control: no-cache' \
  -H 'client-secret: bc40b60349b9ddd9s8cf2fda31c9d17112cfsdsd54d81' \
  -H 'content-type: application/json' \
  -d '{"lang": "PYTHON", "memory_limit": 2463232, "callback": "https://client.com/execute/result/", "time_limit": 5, 
"source": "print '\''Hello World'\''", "input": "", "id": 21312112}'

Get request for getting status of a code evaluation request

Python

import json
import requests

GET_STATUS_URL = u'https://api.hackerearth.com/v4/partner/code-evaluation/submissions/6438b9a6-d5c0-4960-9049-b21a35f0bsdb0/'
CLIENT_SECRET = 'bc40b60349b9ddd98cf2fda31c9d1ds7112chd8s5hs231'

def get_status():
    headers = {"client-secret": CLIENT_SECRET}
    resp = requests.get(GET_STATUS_URL, headers=headers)
    dict = json.loads(resp.text)
    return dict

get_status()

curl -X GET \
  https://api.hackerearth.com/v4/partner/code-evaluation/submissions/202fsdsf443-6308-4707-ab35-5c93f5ab8ea6/ \
  -H 'client-secret: bc40b60349b9ddd98cf2fda31c9d17112csdsf54d81' 

Supported Programming Languages