External Services

External service calls let code read small HTTP responses, check Minecraft server status, or send Discord webhooks. Keep these calls lightweight. Network calls can fail, and both engines limit requests to protect code execution.

HTTP JSON

Use this when an API returns JSON and code needs fields from the response.

Engine v2

Fetches JSON from a URL through the v2 runtime HTTP helper.

Read JSON fieldAdvanced Script

const data = http.getJson("https://httpbin.org/json");
async.messages.send(data.slideshow.title);

API reference

http.getJson

http.getJson(url)

Input

url

string

Absolute URL to request.

Output

any

Parsed JSON response body.

Example output

{
  "status": "online",
  "viewers": 42
}

Engine v1

{{$response := http.GetJson "https://swapi.dev/api/people/1"}}
Name: {{$response.name}}

HTTP JSON with Headers

Use headers when the external API requires tokens or accepts custom content negotiation.

Engine v2

Runs an HTTP request synchronously and returns a small Fetch-like response object.

Fetch JSON with headersAdvanced Script

const response = fetchSync("https://httpbin.org/json", {
  headers: { Accept: "application/json" },
});
const data = response.json();
async.messages.send(data.slideshow.title);

API reference

fetchSync

fetchSync(url, options?)

Input

url

string

Absolute URL to request.

optionsoptional

object

Request options.

methodoptional

string

HTTP method. Defaults to GET.

headersoptional

object

Header names mapped to header values.

bodyoptional

stringobjectarraynumberbooleannull

Request body. Objects and arrays are sent as JSON.

Output

object

Fetch-like response.

status

number

HTTP status code.

ok

boolean

True for successful 2xx responses.

headers

object

Response headers.

text

function

Returns the response body as text.

json

function

Parses and returns the response body as JSON.

Example output

{
  "status": 200,
  "ok": true,
  "headers": {
    "content-type": "application/json"
  }
}

Runs an HTTP request and returns a Fetch-like response object.

API reference

fetch

fetch(url, options?)

Input

url

string

Absolute URL to request.

optionsoptional

object

Request options.

methodoptional

string

HTTP method. Defaults to GET.

headersoptional

object

Header names mapped to header values.

bodyoptional

stringobjectarraynumberbooleannull

Request body. Objects and arrays are sent as JSON.

Output

object

Fetch-like response.

status

number

HTTP status code.

ok

boolean

True for successful 2xx responses.

headers

object

Response headers.

text

function

Returns the response body as text.

json

function

Parses and returns the response body as JSON.

Example output

{
  "status": 200,
  "ok": true,
  "headers": {
    "content-type": "application/json"
  }
}

Engine v1

{{$response := http.GetJsonWithHeaders "https://example.com" (dict "Authorization" "mySuperSecretToken")}}
Name: {{$response.name}}

HTTP Text

Use this when an endpoint returns plain text.

Engine v2

Fetches text from a URL through the v2 runtime HTTP helper.

Read HTTP textAdvanced Script

const status = http.getText("https://example.com/status.txt");
async.messages.send(`Status: ${status}`);

API reference

http.getText

http.getText(url)

Input

url

string

Absolute URL to request.

Output

string

Response body text.

Engine v1

{{http.GetText "https://example.com/status.txt"}}

HTTP Text with Headers

Engine v2

Runs an HTTP request synchronously and returns a small Fetch-like response object.

Fetch text with headersAdvanced Script

const response = fetchSync("https://example.com/status", {
  headers: { Authorization: "Bearer token" },
});
async.messages.send(response.text());

API reference

fetchSync

fetchSync(url, options?)

Input

url

string

Absolute URL to request.

optionsoptional

object

Request options.

methodoptional

string

HTTP method. Defaults to GET.

headersoptional

object

Header names mapped to header values.

bodyoptional

stringobjectarraynumberbooleannull

Request body. Objects and arrays are sent as JSON.

Output

object

Fetch-like response.

status

number

HTTP status code.

ok

boolean

True for successful 2xx responses.

headers

object

Response headers.

text

function

Returns the response body as text.

json

function

Parses and returns the response body as JSON.

Example output

{
  "status": 200,
  "ok": true,
  "headers": {
    "content-type": "application/json"
  }
}

Engine v1

{{http.GetTextWithHeaders "https://example.com/status" (dict "Authorization" "mySuperSecretToken")}}

HTTP POST JSON

Engine v2

Sends JSON to a URL through the v2 runtime HTTP helper.

Read POST JSON resultAdvanced Script

const result = http.postJson("https://example.com/api", {
  username: sender.username,
});
async.messages.send(result.ok ? "Sent." : "Failed.");

API reference

http.postJson

http.postJson(url, body)

Input

url

string

Absolute URL to request.

body

objectarraystringnumberbooleannull

JSON-serializable request body.

Output

any

Parsed JSON response body when the response is JSON.

Example output

{
  "ok": true,
  "id": "evt_123"
}

Engine v1

POST JSON is not exposed in the v1 template HTTP API.

Fetch API

Engine v2 also exposes fetchSync(url, options) and fetch(url, options).

Engine v2

Runs an HTTP request synchronously and returns a small Fetch-like response object.

Handle fetch responseAdvanced Script

const response = fetchSync("https://example.com/data.json");
if (response.ok) {
  async.messages.send(response.json().name);
} else {
  async.messages.send(`Request failed with ${response.status}`);
}

API reference

fetchSync

fetchSync(url, options?)

Input

url

string

Absolute URL to request.

optionsoptional

object

Request options.

methodoptional

string

HTTP method. Defaults to GET.

headersoptional

object

Header names mapped to header values.

bodyoptional

stringobjectarraynumberbooleannull

Request body. Objects and arrays are sent as JSON.

Output

object

Fetch-like response.

status

number

HTTP status code.

ok

boolean

True for successful 2xx responses.

headers

object

Response headers.

text

function

Returns the response body as text.

json

function

Parses and returns the response body as JSON.

Example output

{
  "status": 200,
  "ok": true,
  "headers": {
    "content-type": "application/json"
  }
}

Engine v1

Use http.GetJson, http.GetText, http.GetJsonWithHeaders, or http.GetTextWithHeaders instead.

Minecraft Status

Use this to read a Minecraft server status response.

Engine v2

Returns the current player count for a Minecraft server.

API reference

minecraft.players

minecraft.players(host)

Input

host

string

Minecraft server host.

Output

number

Current player count.

Minecraft statusAdvanced Script

const players = minecraft.players("mc.example.com");
async.messages.send(`Players: ${players}`);

For the full status object:

Returns the Minecraft server status from mcapi.us, including online state and player counts.

API reference

minecraft.status

minecraft.status(host)

Input

host

string

Minecraft server host.

Output

object

Minecraft server status response.

online

boolean

Whether the server is online.

players

object

Player count information.

now

number

Current player count.

max

number

Maximum player count reported by the server.

Minecraft status objectAdvanced Script

const status = minecraft.status("mc.example.com");
async.messages.send(`Online: ${status.online}
Players: ${status.players.now}`);

Engine v1

There are currently {{minecraft.Players "hypixel.net"}} players on Hypixel.net!

Discord Webhooks

Use Discord webhooks when code should send a message to a Discord channel.

Engine v2

Sends a message to a Discord webhook.

API reference

discord.send

discord.send(webhookUrl, payload)

Input

webhookUrl

string

Discord webhook URL.

payload

object

Discord webhook payload, for example {content: "..."}.

Output

boolean

True when the webhook send completed.

Discord webhookAdvanced Script

discord.send("https://discord.com/api/webhooks/xx/xx", {
  content: `${sender.username} triggered a command.`,
});
async.messages.send("Discord webhook sent.");

Engine v1

In v1, define a template block containing the Discord JSON payload, then pass that block name to discord.SendMessage.

{{discord.SendMessage "https://discord.com/api/webhooks/xx/xx" "discord"}}

{{define "discord"}}
{"content": "{{sender}} triggered a command."}
{{end}}

Advanced Script:

const json = {
    content: "Hello from JavaScript!",
};

Discord.sendMessage("https://discord.com/api/webhooks/xx/xx", json);

Custom Events

Custom events notify overlay widgets and are documented with the other overlay helpers. See Overlay Effects.

Async external-service wrappers

Async wrapper for http.getJson(url).

API reference

async.http.getJson

async.http.getJson(url)

Input

url

string

Absolute URL to request.

Output

any

Parsed JSON response body.

Example output

{
  "status": "online",
  "viewers": 42
}

Async wrapper for http.getText(url).

API reference

async.http.getText

async.http.getText(url)

Input

url

string

Absolute URL to request.

Output

string

Response body text.

Async wrapper for http.postJson(url, body).

API reference

async.http.postJson

async.http.postJson(url, body)

Input

url

string

Absolute URL to request.

body

objectarraystringnumberbooleannull

JSON-serializable request body.

Output

any

Parsed JSON response body when the response is JSON.

Example output

{
  "ok": true,
  "id": "evt_123"
}

Async wrapper for discord.send(webhookUrl, payload).

API reference

async.discord.send

async.discord.send(webhookUrl, payload)

Input

webhookUrl

string

Discord webhook URL.

payload

object

Discord webhook payload, for example {content: "..."}.

Output

boolean

True when the webhook send completed.

Async wrapper for minecraft.players(host).

API reference

async.minecraft.players

async.minecraft.players(host)

Input

host

string

Minecraft server host.

Output

number

Current player count.

Async wrapper for minecraft.status(host).

API reference

async.minecraft.status

async.minecraft.status(host)

Input

host

string

Minecraft server host.

Output

object

Minecraft server status response.

online

boolean

Whether the server is online.

players

object

Player count information.

now

number

Current player count.

max

number

Maximum player count reported by the server.

Limits and Safety

v1 HTTP template calls are limited to 3 requests per render and response bodies are limited. v1 Minecraft status calls are limited to 3 unique servers per render. v1 Discord webhook sends are limited to 3 messages per render.

v2 HTTP, fetchSync, and remote-import network requests are limited to 3 requests per render. Discord sends are limited to 3 sends per render. Minecraft status calls are limited to 3 requests per render. All external network actions together are limited to 6 per render.

v2 blocks local, numeric-IP, Kick, and other unsafe request targets for HTTP calls. Discord sends are restricted to https://discord.com URLs. Each outbound HTTP call has a 5 second request timeout and a 256 KB response body limit, and the whole render still runs inside the normal v2 execution timeout and memory limits.