Skip to main content

API Helper

The api helper is the only way to make HTTP requests from AutessaScript. Every method takes a JSON string describing the request, blocks until the response arrives, and returns a JSON string envelope containing the status code, body, and headers. All requests pass through the platform's SSRF protection before leaving the box.

Methods​

Requests and responses are JSON strings on both sides — build the request with JSON.stringify(...) and unpack the result with JSON.parse(...).

  • Name
    api.get
    Type
    (requestJson: string) => string
    Description

    Sends a GET request. No body.

  • Name
    api.post
    Type
    (requestJson: string, body?: string) => string
    Description

    Sends a POST request. The optional second argument is the raw request body; if omitted, a body field inside requestJson is used instead.

  • Name
    api.put
    Type
    (requestJson: string, body?: string) => string
    Description

    Sends a PUT request. Body handling is identical to post.

  • Name
    api.patch
    Type
    (requestJson: string, body?: string) => string
    Description

    Sends a PATCH request. Body handling is identical to post.

  • Name
    api.delete
    Type
    (requestJson: string) => string
    Description

    Sends a DELETE request. No body variant — only the body field inside requestJson is honored.

The request JSON​

  • Name
    endpoint
    Type
    string, required
    Description

    Full URL including scheme. Only http and https are allowed.

  • Name
    headers
    Type
    object, optional
    Description

    Header name to string value. Set your own Authorization header here for authenticated calls.

  • Name
    body
    Type
    any, optional
    Description

    Request body, serialized as JSON and sent verbatim. Ignored when the separate body argument to post/put/patch is provided (the argument wins).

Body rules worth knowing:

  • Whenever a body is present (argument or field), Content-Type: application/json is set automatically.
  • POST, PUT, and PATCH with no body at all send an empty body.
  • Redirects are never followed — a 301/302 comes back to your script as-is, with the Location header intact.
// GET with headers
const raw = api.get(JSON.stringify({
  endpoint: "https://api.example.com/v1/orders?status=open",
  headers: { "Authorization": "Bearer " + variables.get("apiToken") }
}));

// POST with a body field
const created = api.post(JSON.stringify({
  endpoint: "https://api.example.com/v1/orders",
  headers: { "Authorization": "Bearer " + variables.get("apiToken") },
  body: { sku: "A-100", quantity: 2 }
}));

// POST with a separate body argument (handy for pre-serialized payloads)
const alsoCreated = api.post(
  JSON.stringify({ endpoint: "https://api.example.com/v1/orders" }),
  JSON.stringify({ sku: "A-100", quantity: 2 })
);

The response envelope​

Every call returns a JSON string with the same shape — parse it and check statusCode:

{
  "statusCode": 200,
  "body": "{\"orders\":[...]}",
  "headers": {
    "content-type": "application/json",
    "x-request-id": "abc123"
  }
}
  • Name
    statusCode
    Type
    number
    Description

    The HTTP status code, or -1 when the request never completed (see errors below).

  • Name
    body
    Type
    string
    Description

    The raw response body. If the endpoint returns JSON, JSON.parse it yourself — it arrives as a string.

  • Name
    headers
    Type
    object
    Description

    Response headers; multi-valued headers are joined with ", ".

const res = JSON.parse(raw);
if (res.statusCode >= 200 && res.statusCode < 300) {
  const data = JSON.parse(res.body);   // second parse: body is a string
  response.setResponse(JSON.stringify({ count: data.orders.length }));
} else {
  response.setResponse(JSON.stringify({ error: "upstream returned " + res.statusCode }));
}

Two parses are always needed for JSON APIs: one for the envelope, one for body. Forgetting the second parse is the most common api.* mistake.

Error shape​

When the request fails before an HTTP response exists (blocked URL, network error, interrupt), the envelope carries error fields instead, with statusCode: -1:

{
  "error": true,
  "errorCode": "SSRF_BLOCKED",
  "errorMessage": "Requests to private addresses are not allowed",
  "statusCode": -1,
  "body": "",
  "headers": {}
}
  • Name
    SSRF_BLOCKED
    Type
    errorCode
    Description

    The URL failed SSRF validation (see below).

  • Name
    SECURITY_ERROR
    Type
    errorCode
    Description

    The SSRF protection service wasn't available, so the request was refused outright.

  • Name
    IO_ERROR
    Type
    errorCode
    Description

    Network-level failure: DNS, connection refused, timeout, TLS.

  • Name
    INTERRUPTED
    Type
    errorCode
    Description

    The request thread was interrupted mid-flight.

  • Name
    UNKNOWN_ERROR
    Type
    errorCode
    Description

    Anything else — malformed request JSON, unexpected runtime failure.

Check res.error === true (or statusCode === -1) before treating the envelope as an HTTP response.

SSRF protection​

Every endpoint is validated before the request is sent; requests to private networks, internal infrastructure, and non-HTTP(S) schemes are rejected with SSRF_BLOCKED.

Timeouts: 30 seconds to establish a connection, 60 seconds for the full request. A timeout surfaces as IO_ERROR.