class XMLHttpRequest

XMLHttpRequest provides HTTP client functionality for making network requests from JavaScript in Max.

XMLHttpRequest implements a subset of the web standard XMLHttpRequest API. It is available in both JavaScript engines, but the backing implementation and capabilities differ:

In the legacy [js] / [jsui] (SpiderMonkey) objects it is backed by the Max maxurl object. Only text responses are supported, and the Max-specific XMLHttpRequest._setRequestKey() / XMLHttpRequest._getResponseKey() extensions are available. - In the [v8] / [v8.codebox] / [v8ui] objects (Max 9.2 and later) it is backed by the native Boost/Beast HTTP client path (the same transport as fetch()), not maxurl. It additionally supports arraybuffer, blob, and json response types, the XMLHttpRequest.response and XMLHttpRequest.responseURL properties, upload progress via XMLHttpRequest.upload, automatic redirect following, transparent gzip/deflate decoding, and the full progress event set.

Both engines are asynchronous only. In the v8 engine open(..., false) throws immediately; the legacy engine ignores the async argument. URLs must be absolute http:// or https:// URLs. responseXML, responseType = "document", synchronous requests, and the browser CORS/page-integration model are not implemented.

The readyState property indicates the current state of the request: - 0 (UNSENT): open() has not been called yet - 1 (OPENED): send() has not been called yet - 2 (HEADERS_RECEIVED): send() has been called, and headers and status are available - 3 (LOADING): Downloading; responseText holds partial data - 4 (DONE): The operation is complete

Example

var req = new XMLHttpRequest();
req.open("GET", "https://api.example.com/data");
req.onreadystatechange = function () {
  if (this.readyState == 4) {
    post("Response: " + this.responseText + "\n");
  }
};
req.send();

Index

Properties

DONE
HEADERS_RECEIVED
LOADING
onabort
onerror
onload
onloadend
onloadstart
onprogress
onreadystatechange
ontimeout
OPENED
readyState
response
responseText
responseType
responseURL
status
statusText
timeout
UNSENT
upload
withCredentials

Methods

_getResponseKey(key)
_setRequestKey(key, value)
abort()
addEventListener(type, listener)
getAllResponseHeaders()
getResponseHeader(name)
open(method, url, async, username, password)
overrideMimeType(mimeType)
removeEventListener(type, listener)
send(body)
setRequestHeader(name, value)

_getResponseKey(key)

Supported only in the SpiderMonkey engine.

Gets a Max-specific response key from the underlying maxurl object.

This is a Max-specific extension of the legacy [js] / [jsui] (maxurl-backed) implementation. It is not available in the v8 runtime, which does not use maxurl. Common keys include: content_type, total_time, size_download, filename_out.

_getResponseKey(key: string): string;

Name	Type	Description
key	string	The key name
Return Value	string	The value associated with the key, or an empty string if not found

Example

req.onreadystatechange = function () {
  if (this.readyState == 4) {
    post("Content-Type: " + this._getResponseKey("content_type") + "\n");
    post("Total Time: " + this._getResponseKey("total_time") + "\n");
  }
};

_setRequestKey(key, value)

Supported only in the SpiderMonkey engine.

Sets a Max-specific request key for the underlying maxurl object.

This is a Max-specific extension of the legacy [js] / [jsui] (maxurl-backed) implementation. It is not available in the v8 runtime, which does not use maxurl. For example, you can use this to set the filename_out key to save the response directly to a file.

_setRequestKey(key: string, value: string): void;

Name	Type	Description
key	string	The key name
value	string	The value to set

Example

req.open("GET", "https://cycling74.com");
req._setRequestKey("filename_out", "~/Desktop/download.html");
req.send();

abort()

Aborts the request if it is still in progress.

After calling abort(), the readyState will be set to UNSENT (0), and the onabort handler will be called if one is set.

abort(): void;

Example

req.abort();

addEventListener(type, listener)

Supported only in the v8 engine. Introduced in Max v9.2.0.

Registers an event listener.

addEventListener(type: string, listener: (...args: any[]) => void): void;

Name	Type	Description
type	string	The event name (`readystatechange`, `loadstart`, `progress`, `abort`, `error`, `timeout`, `load`, `loadend`)
listener	(...args: any[]) => void	The callback to invoke

DONE number read-only

State constant: the operation is complete (4).

getAllResponseHeaders()

Gets all response headers as a single string.

In the v8 runtime (Max 9.2 and later) this omits set-cookie (matching browser XHR behavior) and preserves repeated non-cookie header lines.

getAllResponseHeaders(): string;

Name	Type	Description
Return Value	string	A string containing all response headers, separated by newlines, or an empty string if no headers are available

Example

var headers = req.getAllResponseHeaders();
post("Headers:\n" + headers + "\n");

getResponseHeader(name)

Gets the value of a specific response header.

getResponseHeader(name: string): string;

Name	Type	Description
name	string	The name of the header to retrieve
Return Value	string	The header value, or an empty string if not found

Example

var contentType = req.getResponseHeader("Content-Type");
post("Content-Type: " + contentType + "\n");

HEADERS_RECEIVED number read-only

State constant: headers and status are available (2).

LOADING number read-only

State constant: response body is downloading (3).

onabort ((this: XMLHttpRequest) => void) | null

Supported only in the v8 engine.

Event handler called when the request is aborted.

onerror ((this: XMLHttpRequest, event: ProgressEvent) => void) | null

Supported only in the v8 engine.

Event handler called when the request encounters a network error.

This fires for network errors (e.g., network down, invalid URL), but not for HTTP error status codes like 404 or 500. For HTTP errors, check the XMLHttpRequest.status property in the XMLHttpRequest.onload handler.

Example

req.onerror = function (event) {
  post("Network error occurred\n");
};

onload ((this: XMLHttpRequest) => void) | null

Supported only in the v8 engine.

Event handler called when the request successfully completes.

This fires when the request completes, even if the HTTP status code indicates an error (e.g., 404 or 500). Always check the XMLHttpRequest.status property to determine if the request was truly successful.

Example

req.onload = function () {
  if (this.status == 200) {
    post("Success: " + this.responseText + "\n");
  } else {
    post("Error: " + this.status + "\n");
  }
};

onloadend ((this: XMLHttpRequest) => void) | null

Supported only in the v8 engine.

Event handler called when the request finishes, regardless of success or failure.

This always fires after the request completes, whether it succeeded, failed with an error, or was aborted.

onloadstart ((this: XMLHttpRequest) => void) | null

Supported only in the v8 engine.

Event handler called when the request starts loading data.

onprogress ((this: XMLHttpRequest, event: ProgressEvent) => void) | null

Supported only in the v8 engine.

Event handler called periodically as data is received.

The event handler receives a ProgressEvent object containing information about the download progress.

Example

req.onprogress = function (event) {
  post("Progress: " + event.loaded + " / " + event.total + "\n");
};

onreadystatechange ((this: XMLHttpRequest) => void) | null

Event handler called whenever the readyState property changes.

Example

req.onreadystatechange = function () {
  post("readyState: " + this.readyState + "\n");
};

ontimeout ((this: XMLHttpRequest) => void) | null

Supported only in the v8 engine.

Event handler called when the request times out.

Currently not fully implemented. Timeout detection may not work as expected.

open(method, url, async, username, password)

Initializes a request.

open(
  method: string,
  url: string,
  async?: boolean,
  username?: string,
  password?: string,
): void;

Name	Type	Description
method	string	The HTTP method (e.g., "GET", "POST", "PUT", "DELETE")
url	string	The absolute `http://` or `https://` URL to request
optional async	boolean	Whether the request should be asynchronous. The legacy `[js]` engine ignores this argument (always async); the v8 engine throws if it is `false`.
optional username	string	Optional username for HTTP authentication
optional password	string	Optional password for HTTP authentication

Example

req.open("GET", "https://api.example.com/data");
req.open("POST", "https://api.example.com/submit", true);
req.open("GET", "https://api.example.com/data", true, "user", "pass");

OPENED number read-only

State constant: open() has been called (1).

overrideMimeType(mimeType)

Overrides the MIME type of the response.

Must be called before XMLHttpRequest.send(). In the v8 runtime this affects text decoding and blob type metadata only; it does not change the network transport.

overrideMimeType(mimeType: string): void;

Name	Type	Description
mimeType	string	The MIME type to use

Example

req.open("GET", "https://api.example.com/data");
req.overrideMimeType("text/plain");
req.send();

readyState number read-only

The current state of the request. See XMLHttpRequest for state values.

removeEventListener(type, listener)

Supported only in the v8 engine. Introduced in Max v9.2.0.

Removes a previously registered event listener.

removeEventListener(type: string, listener: (...args: any[]) => void): void;

Name	Type	Description
type	string	The event name
listener	(...args: any[]) => void	The callback to remove

response string | ArrayBuffer | Blob | any read-only

Supported only in the v8 engine. Introduced in Max v9.2.0.

The parsed response

The type depends on XMLHttpRequest.responseType: a string for ""/"text", an ArrayBuffer for "arraybuffer", a Blob for "blob", or parsed JSON for "json". Invalid JSON resolves to null.

responseText string read-only

The response body as a string.

Available when XMLHttpRequest.responseType is "" or "text".

responseType "" | "text" | "arraybuffer" | "blob" | "json"

The response type.

In the legacy [js] object only "" and "text" are supported. The v8 runtime (Max 9.2 and later) also supports "arraybuffer", "blob", and "json".

responseURL string read-only

Supported only in the v8 engine. Introduced in Max v9.2.0.

The final response URL, reflecting any redirects that were followed.

send(body)

Sends the request.

The legacy [js] engine accepts a string body. The v8 runtime (Max 9.2 and later) also accepts a buffer.IOBuffer, typed array / ArrayBuffer view, ArrayBuffer, Blob, FormData, or URLSearchParams.

send(body?: any): void;

Name	Type	Description
optional body	any	Optional request body (for POST, PUT, etc.).

Example

req.open("POST", "https://api.example.com/submit");
req.setRequestHeader("Content-Type", "application/json");
req.send('{"key": "value"}');

setRequestHeader(name, value)

Sets a request header.

Must be called after XMLHttpRequest.open() but before XMLHttpRequest.send().

setRequestHeader(name: string, value: string): void;

Name	Type	Description
name	string	The header name
value	string	The header value

Example

req.open("POST", "https://api.example.com/submit");
req.setRequestHeader("Content-Type", "application/json");
req.setRequestHeader("Authorization", "Bearer token123");
req.send(data);

status number read-only

The HTTP status code of the response (e.g., 200, 404, 500). A value of 0 indicates that the request has not completed or encountered an error.

statusText string read-only

The HTTP status text of the response (e.g., "OK", "Not Found").

timeout number

The timeout for the request in milliseconds. Set to 0 for no timeout.

UNSENT number read-only

State constant: open() has not been called (0).

upload XMLHttpRequestUpload read-only

Supported only in the v8 engine. Introduced in Max v9.2.0.

The upload object, exposing progress events for the request body.

withCredentials boolean

Whether to include credentials (cookies) in requests.

In the v8 runtime (Max 9.2 and later) this reuses the same fetch-session cookie jar and credential rules as fetch().