HTTP API: Executing Webtasks

Execute custom Node.js code with authenticated HTTP call

For customized documentation and ready to run samples, please log in.

The HTTP API is deprecated for public usage and access will be removed soon.

The webtask request endpoint is used to execute code in the webtask cluster:

HTTPS {verb} /api/run/{webtask_container}          

The {webtask_container} URL segment identifies the name of the webtask container to execute the request in. The request must be authenticated by specifying the webtask token as the key URL query parameter or with the Authorization HTTP request header. The {verb} must be POST, PATCH, PUT, GET, or DELETE.

There are two ways of supplying the webtask code to execute: directly in the body of the HTTPS request, or by providing the URL to the code using the webtask_url URL query paramater. If you are using the GET or DELETE verbs, you can only provide code to execute by specifying its URL.

There are several representations of code you can submit for execution, explained in the programming model topic.

You can issue a webtask request that specifies the code to execute directly in the body of the request with curl as follows:

curl{webtask_container} -H "Authorization: Bearer {webtask_token}" --data-binary 'module.exports = function (cb) { cb(null, "Hello, world!"); }'      

If you choose to specify the webtask code by providing the webtask_url URL query parameter, you must make sure an HTTP GET request to that URL will properly return the code. For example, let's use the webtask code stored at

module.exports = function (cb) {
  cb(null, "Hello, world!");

You can then issue a webtask request that specifies the webtask_url URL query parameter and does not provide any HTTP request body:

curl{webtask_container}?webtask_url= -H "Authorization: Bearer {webtask_token}" -X POST 

Regardless of the mechanim used to supply the webtask code, the HTTP response has contains either the result of code execution or an error, depending on the status code of the response as follows:


Code executed correctly and response contains the result of the computation.


There was a problem with the data submitted by the caller, the response body contains details.


The webtask token is not submitted with the request or does not grant sufficient permissions.


Requests to the {webtask_container} are throttled. The caller is expected to wait at least the amount of time specified in the Retry-After HTTP response header before re-attempting the request.


Fatal execution error of the webtask request, the response contains details.