LazyCurl JavaScript Scripting API Reference

January 18, 2026 ยท View on GitHub

This document provides a comprehensive reference for all JavaScript APIs available in LazyCurl pre-request and post-response scripts.

Table of Contents


Overview

LazyCurl uses the Goja JavaScript runtime to execute scripts. Scripts have access to the lc global object which provides APIs for request/response manipulation, environment variables, testing, and utilities.

Script Types

TypeExecutionAvailable APIs
Pre-requestBefore HTTP request is sentlc.request (mutable), lc.env, lc.globals, lc.cookies, lc.sendRequest
Post-responseAfter HTTP response receivedlc.request (read-only), lc.response, lc.env, lc.globals, lc.test, lc.cookies

Quick Example

// Pre-request: Add authentication
var token = lc.env.get("auth_token");
if (token) {
  lc.request.setHeader("Authorization", "Bearer " + token);
}

// Post-response: Validate and store data
lc.test("Status is 200", function () {
  lc.expect(lc.response.status).toBe(200);
});

var data = lc.response.json();
if (data.token) {
  lc.env.set("auth_token", data.token);
}

lc.request

The lc.request object provides access to the current HTTP request data. It allows reading request properties and, in pre-request scripts, modifying the request before it is sent.

Properties

PropertyTypeMutabilityDescription
methodstringRead-onlyThe HTTP method (GET, POST, PUT, DELETE, etc.)
urlstringRead/Write (pre-request only)The request URL including query string

method (Read-only)

Returns the HTTP method of the request. This property cannot be modified.

// Read the HTTP method
var method = lc.request.method;
console.log("Method: " + method); // "GET", "POST", etc.

url

Returns or sets the request URL. In pre-request scripts, you can modify this property to change the target URL before the request is sent.

// Read the URL
var url = lc.request.url;
console.log("URL: " + url);

// Modify the URL (pre-request only)
lc.request.url = "https://api.example.com/v2/users";

// Add query parameters dynamically
lc.request.url = lc.request.url + "?timestamp=" + Date.now();

lc.request.headers

Object providing methods for header manipulation.

headers.get(name)

Returns the value of a header by name. Header lookup is case-insensitive.

var contentType = lc.request.headers.get("Content-Type");
var auth = lc.request.headers.get("authorization"); // Case-insensitive

Parameters:

  • name (string): The header name to retrieve

Returns: string | undefined - The header value, or undefined if not found

headers.set(name, value)

Sets or updates a header value. Available only in pre-request scripts.

// Set a new header
lc.request.headers.set("X-Custom-Header", "custom-value");

// Update an existing header
lc.request.headers.set("Content-Type", "application/json");

// Add authentication dynamically
var token = lc.env.get("auth_token");
lc.request.headers.set("Authorization", "Bearer " + token);

Parameters:

  • name (string): The header name
  • value (string): The header value

headers.remove(name)

Removes a header from the request. Available only in pre-request scripts. Header lookup is case-insensitive.

// Remove a header
lc.request.headers.remove("X-Deprecated-Header");

Parameters:

  • name (string): The header name to remove

headers.all()

Returns a copy of all headers as a key-value object.

var allHeaders = lc.request.headers.all();
console.log(JSON.stringify(allHeaders));
// { "Content-Type": "application/json", "Authorization": "Bearer ..." }

// Iterate over headers
var headers = lc.request.headers.all();
for (var name in headers) {
  console.log(name + ": " + headers[name]);
}

Returns: object - An object containing all headers as key-value pairs

lc.request.body

Object providing methods for request body access and manipulation.

body.raw()

Returns the raw request body as a string.

var rawBody = lc.request.body.raw();
console.log("Body length: " + rawBody.length);

Returns: string - The raw body content

body.json()

Parses the request body as JSON and returns the resulting object. Returns null if parsing fails or body is empty.

var data = lc.request.body.json();
if (data) {
  console.log("User ID: " + data.userId);
  console.log("Name: " + data.name);
}

Returns: object | null - Parsed JSON object, or null if invalid/empty

body.set(content)

Sets the request body content. Available only in pre-request scripts.

// Set body as string
lc.request.body.set('{"name": "John", "email": "john@example.com"}');

// Build body programmatically
var payload = {
  timestamp: Date.now(),
  requestId: Math.random().toString(36).substring(7),
  data: lc.request.body.json(),
};
lc.request.body.set(JSON.stringify(payload));

Parameters:

  • content (string): The new body content

lc.request.params

Object providing read-only access to URL query parameters.

params.get(name)

Returns the first value of a query parameter.

// URL: https://api.example.com/users?page=1&limit=10
var page = lc.request.params.get("page"); // "1"
var limit = lc.request.params.get("limit"); // "10"
var missing = lc.request.params.get("sort"); // undefined

Parameters:

  • name (string): The parameter name

Returns: string | undefined - The parameter value, or undefined if not found

params.getAll(name)

Returns all values for a query parameter (for parameters with multiple values).

// URL: https://api.example.com/search?tag=javascript&tag=golang&tag=rust
var tags = lc.request.params.getAll("tag");
// ["javascript", "golang", "rust"]

tags.forEach(function (tag) {
  console.log("Tag: " + tag);
});

Parameters:

  • name (string): The parameter name

Returns: string[] - Array of all values for the parameter (empty array if not found)

params.has(name)

Checks if a query parameter exists.

// URL: https://api.example.com/users?active=true
if (lc.request.params.has("active")) {
  console.log("Filtering by active status");
}

Parameters:

  • name (string): The parameter name to check

Returns: boolean - true if the parameter exists, false otherwise

params.keys()

Returns an array of all query parameter names.

// URL: https://api.example.com/search?q=test&page=1&limit=20
var keys = lc.request.params.keys();
// ["q", "page", "limit"]

Returns: string[] - Array of parameter names

params.all()

Returns all query parameters as a key-value object. For parameters with multiple values, only the first value is included.

// URL: https://api.example.com/users?page=1&limit=10&sort=name
var params = lc.request.params.all();
// { "page": "1", "limit": "10", "sort": "name" }

console.log("Page: " + params.page);

Returns: object - Object containing all parameters as key-value pairs

Mutability Notes

ContextPropertiesBehavior
Pre-request scripturl, headers, bodyFully mutable - changes affect the outgoing request
Post-response scriptAll propertiesRead-only - reflects the request as it was sent

lc.response

The lc.response object provides read-only access to HTTP response data in post-response scripts. This object is immutable and only available after the HTTP request has completed.

Availability: Post-response scripts only. Not available in pre-request scripts.

Properties

PropertyTypeDescription
statusnumberHTTP status code (e.g., 200, 404, 500)
statusTextstringFull status text including code (e.g., "200 OK", "404 Not Found")
timenumberResponse time in milliseconds
// Check status code
if (lc.response.status === 200) {
  lc.console.log("Request successful");
}

// Log response timing
lc.console.log("Response received in " + lc.response.time + "ms");

// Use full status text for logging
lc.console.log("Status: " + lc.response.statusText);

Methods

lc.response.headers.get(name)

Returns the value of a response header. Header name lookup is case-insensitive.

Parameters:

  • name (string): The header name to retrieve Returns: string | undefined - The header value, or undefined if not found ```javascript // Get content type var contentType = lc.response.headers.get("Content-Type"); lc.console.log("Content-Type: " + contentType);

// Case-insensitive lookup var auth = lc.response.headers.get("x-auth-token"); var authAlt = lc.response.headers.get("X-Auth-Token"); // Same result

#### lc.response.headers.all() Returns a copy of all response headers as a key-value object. **Returns:** `object` - Object containing all headers ```javascript // Get all headers
var headers = lc.response.headers.all();

// Iterate over headers
for (var key in headers) {
  lc.console.log(key + ": " + headers[key]);
}

lc.response.body.raw()

Returns the raw response body as a string.

Returns: string - The response body content

// Get raw body
var rawBody = lc.response.body.raw();
lc.console.log("Body length: " + rawBody.length + " characters");

lc.response.body.json()

Parses the response body as JSON and returns the resulting object. Returns null if the body is empty or cannot be parsed as valid JSON.

Returns: object | array | null - Parsed JSON data, or null on parse failure

// Parse JSON response
var data = lc.response.body.json();

if (data !== null) {
  lc.console.log("User ID: " + data.id);
  lc.console.log("Username: " + data.username);
} else {
  lc.console.error("Failed to parse response as JSON");
}

Complete Example

// Comprehensive post-response script
lc.console.log("Status: " + lc.response.statusText);
lc.console.log("Time: " + lc.response.time + "ms");

if (lc.response.status >= 200 && lc.response.status < 300) {
  var data = lc.response.body.json();

  if (data && data.accessToken) {
    lc.env.set("access_token", data.accessToken);
    lc.console.log("Token saved");
  }
} else if (lc.response.status === 401) {
  lc.console.error("Unauthorized - check credentials");
}

lc.test("Authentication successful", function () {
  lc.expect(lc.response.status).toBe(200);
});

lc.env & lc.globals

LazyCurl provides two distinct mechanisms for managing variables in scripts: environment variables (lc.env) for project-level configuration and global variables (lc.globals) for cross-request data sharing within a session.

lc.env - Environment Variables

Environment variables are tied to your active environment file and persist to disk. Changes made via lc.env.set() are saved to the environment file after script execution.

MethodSignatureDescription
getlc.env.get(name)Retrieves the value of an environment variable. Returns empty string if not found.
setlc.env.set(name, value)Sets an environment variable. Value is persisted to the environment file.
unsetlc.env.unset(name)Removes an environment variable from the environment.
haslc.env.has(name)Returns true if the variable exists, false otherwise.
toObjectlc.env.toObject()Returns all environment variables as a JavaScript object.
// Get a variable
var baseUrl = lc.env.get("base_url");

// Set a variable (persisted to environment file)
lc.env.set("last_run", new Date().toISOString());

// Check if variable exists before using
if (lc.env.has("api_key")) {
  lc.request.setHeader("X-API-Key", lc.env.get("api_key"));
}

// Remove a variable
lc.env.unset("temp_token");

// Get all variables as an object
var allVars = lc.env.toObject();

lc.globals - Session Global Variables

Global variables exist only in memory during the current LazyCurl session. They persist across multiple request executions but are lost when you close the application. Unlike lc.env, globals can store any JavaScript value (objects, arrays, numbers, booleans) not just strings.

MethodSignatureDescription
getlc.globals.get(name)Retrieves a global variable. Returns null if not found.
setlc.globals.set(name, value)Sets a global variable. Accepts any JavaScript value.
unsetlc.globals.unset(name)Removes a global variable.
haslc.globals.has(name)Returns true if the variable exists, false otherwise.
clearlc.globals.clear()Removes all global variables.
toObjectlc.globals.toObject()Returns all global variables as a JavaScript object.
// Store complex data structures
lc.globals.set("user", {
  id: 123,
  name: "John Doe",
  roles: ["admin", "user"],
});

// Retrieve and use stored data
var user = lc.globals.get("user");
if (user) {
  lc.console.log("User ID: " + user.id);
}

// Store counters or state
var count = lc.globals.get("request_count") || 0;
lc.globals.set("request_count", count + 1);

// Clear all globals
lc.globals.clear();

Comparison: lc.env vs lc.globals

Featurelc.envlc.globals
PersistenceSaved to environment file on diskIn-memory only (lost on app close)
ScopeTied to active environmentSession-wide, all requests
Value TypesStrings onlyAny JavaScript value
Use CaseConfiguration, API keys, base URLsRequest chaining, temporary state

Request Chaining Example

// Request 1 - Post-response: Store token
var data = lc.response.json();
if (data && data.access_token) {
  lc.globals.set("access_token", data.access_token);
  lc.env.set("access_token", data.access_token);
}

// Request 2 - Pre-request: Use token
var token = lc.globals.get("access_token") || lc.env.get("access_token");
if (token) {
  lc.request.setHeader("Authorization", "Bearer " + token);
}

lc.test & lc.expect

The scripting API provides a Jest-like testing framework with lc.test() for organizing tests and lc.expect() for fluent assertions.

lc.test(name, fn)

Defines a named test case. The test passes if the function executes without throwing an error.

lc.test("Response status is OK", function () {
  lc.expect(lc.response.status).toBe(200);
});

lc.test("User data is valid", function () {
  var data = lc.response.body.json();
  lc.expect(data).toHaveProperty("id");
  lc.expect(data.name).toBeDefined();
});

lc.expect(value)

Creates an expectation object for fluent assertions. Returns a chainable object with matcher methods.

Matchers

MatcherDescription
toBe(expected)Strict equality comparison
toEqual(expected)Deep equality comparison
toBeTruthy()Asserts value is truthy
toBeFalsy()Asserts value is falsy
toContain(substring)Asserts string contains substring
toHaveProperty(name)Asserts object has property
toMatch(pattern)Asserts value matches regex
toBeNull()Asserts value is null
toBeUndefined()Asserts value is undefined
toBeDefined()Asserts value is not null/undefined
toHaveLength(n)Asserts length of string/array
toBeGreaterThan(n)Asserts number > n
toBeLessThan(n)Asserts number < n
toBeGreaterThanOrEqual(n)Asserts number >= n
toBeLessThanOrEqual(n)Asserts number <= n
lc.expect(200).toBe(200); // Pass
lc.expect({ a: 1 }).toEqual({ a: 1 }); // Pass
lc.expect("hello").toContain("ell"); // Pass
lc.expect(data).toHaveProperty("id"); // Pass
lc.expect("user@example.com").toMatch("@"); // Pass
lc.expect([1, 2, 3]).toHaveLength(3); // Pass
lc.expect(lc.response.time).toBeLessThan(1000); // Pass

Negation with .not

All matchers can be negated using the .not chain:

lc.expect(200).not.toBe(404);
lc.expect("hello").not.toContain("goodbye");
lc.expect(data).not.toHaveProperty("deleted");
lc.expect(null).not.toBeDefined();

Complete Example

lc.test("API returns valid user", function () {
  lc.expect(lc.response.status).toBe(200);

  var user = lc.response.body.json();
  lc.expect(user).not.toBeNull();
  lc.expect(user).toHaveProperty("id");
  lc.expect(user.email).toMatch("@");
  lc.expect(user.roles).toHaveLength(2);
});

lc.test("Response time acceptable", function () {
  lc.expect(lc.response.time).toBeLessThan(2000);
});

lc.cookies

Cookie management API for handling HTTP cookies in pre-request and post-response scripts.

Methods

MethodSignatureDescription
getlc.cookies.get(name)Get cookie value by name
getAlllc.cookies.getAll()Get all cookies as array of objects
setlc.cookies.set(name, value, options?)Set a cookie
deletelc.cookies.delete(name)Remove a cookie
clearlc.cookies.clear()Remove all cookies
haslc.cookies.has(name)Check if cookie exists
toHeaderlc.cookies.toHeader()Generate Cookie header string

set() Options

PropertyTypeDescription
domainstringDomain scope for the cookie
pathstringPath scope for the cookie
securebooleanCookie sent only over HTTPS
httpOnlybooleanCookie inaccessible to JavaScript
expiresstringExpiration date (RFC1123 format)
// Get a cookie
var sessionId = lc.cookies.get("session_id");

// Set a cookie with options
lc.cookies.set("auth_token", "abc123xyz", {
  domain: "api.example.com",
  path: "/",
  secure: true,
  httpOnly: true,
});

// Check and use cookie
if (lc.cookies.has("csrf_token")) {
  lc.request.setHeader("X-CSRF-Token", lc.cookies.get("csrf_token"));
}

// Generate Cookie header
lc.request.setHeader("Cookie", lc.cookies.toHeader());

// Clear all cookies
lc.cookies.clear();

CSRF Token Workflow

// Post-response: Capture CSRF token
if (lc.cookies.has("csrf_token")) {
  lc.env.set("csrf_token", lc.cookies.get("csrf_token"));
}

// Pre-request: Use CSRF token
if (lc.cookies.has("csrf_token")) {
  lc.request.setHeader("X-CSRF-Token", lc.cookies.get("csrf_token"));
  lc.request.setHeader("Cookie", lc.cookies.toHeader());
}

lc.base64

Base64 encoding and decoding utilities. Global btoa() and atob() functions are also available for browser-style compatibility.

Methods

MethodDescription
lc.base64.encode(data)Encode string to Base64
lc.base64.decode(encoded)Decode Base64 string
btoa(data)Global function, same as encode()
atob(encoded)Global function, same as decode()
// Encode/decode
var encoded = lc.base64.encode("Hello, World!");
// Returns: "SGVsbG8sIFdvcmxkIQ=="

var decoded = lc.base64.decode("SGVsbG8sIFdvcmxkIQ==");
// Returns: "Hello, World!"

// Browser-style functions
var encoded = btoa("username:password");
var decoded = atob("dXNlcm5hbWU6cGFzc3dvcmQ=");

// Basic Auth header
var credentials = btoa("username:password");
lc.request.setHeader("Authorization", "Basic " + credentials);

Edge Cases

ScenarioBehavior
No argumentReturns empty string ""
Empty stringReturns empty string
Invalid Base64Returns empty string (no exception)

lc.crypto

Cryptographic hash functions and HMAC operations. All functions return lowercase hex-encoded strings.

Hash Functions

FunctionOutput LengthDescription
lc.crypto.md5(data)32 charsMD5 hash (legacy)
lc.crypto.sha1(data)40 charsSHA-1 hash (legacy)
lc.crypto.sha256(data)64 charsSHA-256 hash
lc.crypto.sha512(data)128 charsSHA-512 hash
var hash = lc.crypto.sha256("hello world");
// Returns: "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"

HMAC Functions

FunctionOutput LengthDescription
lc.crypto.hmacSha1(data, secret)40 charsHMAC-SHA1 (OAuth 1.0)
lc.crypto.hmacSha256(data, secret)64 charsHMAC-SHA256
lc.crypto.hmacSha512(data, secret)128 charsHMAC-SHA512
var signature = lc.crypto.hmacSha256("message", "secret");
// Returns: "6e9ef29b75fffc5b7abae527d58fdadb2fe42e7219011976917343065f58ed4a"

Use Cases

// API Request Signing
var timestamp = Math.floor(Date.now() / 1000).toString();
var body = lc.request.body || "";
var signature = lc.crypto.hmacSha256(
  timestamp + body,
  lc.env.get("api_secret"),
);

lc.request.setHeader("X-Timestamp", timestamp);
lc.request.setHeader("X-Signature", signature);

// Webhook Signature Verification
var payload = lc.response.body;
var expected =
  "sha256=" + lc.crypto.hmacSha256(payload, lc.env.get("webhook_secret"));
var received = lc.response.getHeader("X-Hub-Signature-256");

lc.test("Webhook signature valid", function () {
  lc.expect(received).toBe(expected);
});

lc.variables

Dynamic variable generation for creating test data.

Functions

FunctionReturnsDescription
uuid()stringUUID v4
timestamp()numberUnix timestamp (seconds)
timestampMs()numberUnix timestamp (milliseconds)
isoTimestamp()stringISO 8601 timestamp
randomInt(min?, max?)numberRandom integer (default 0-100)
randomFloat()numberRandom float 0-1
randomString(length?)stringAlphanumeric string (default 16)
randomHex(length?)stringHex string (default 16)
randomEmail()stringRandom email address
randomFirstName()stringRandom first name
randomLastName()stringRandom last name
randomBoolean()booleanRandom true/false
// Generate test data
var user = {
  id: lc.variables.uuid(),
  email: lc.variables.randomEmail(),
  firstName: lc.variables.randomFirstName(),
  lastName: lc.variables.randomLastName(),
  isActive: lc.variables.randomBoolean(),
  createdAt: lc.variables.isoTimestamp(),
  score: lc.variables.randomInt(0, 100),
  apiKey: lc.variables.randomHex(32),
};

lc.request.body = JSON.stringify(user);
lc.request.setHeader("X-Request-ID", lc.variables.uuid());

lc.info

Read-only contextual information about the current script execution.

Properties

PropertyTypeDescription
scriptTypestring"pre-request" or "post-response"
requestNamestring | undefinedName of the request
requestIdstring | undefinedID of the request
collectionNamestring | undefinedName of the collection
environmentNamestring | undefinedActive environment name
iterationnumberCurrent iteration (default: 1)
// Conditional logic based on script type
if (lc.info.scriptType === "pre-request") {
  lc.request.setHeader("Authorization", "Bearer " + lc.env.get("token"));
}

// Environment-specific behavior
if (lc.info.environmentName === "production") {
  lc.console.warn("Running against production!");
}

// Iteration-aware testing
if (lc.info.iteration === 1) {
  lc.test.assertStatus(201); // First iteration creates
} else {
  lc.test.assertStatus(200); // Subsequent iterations update
}

// Logging with context
lc.console.log(
  "[" +
    lc.info.collectionName +
    "/" +
    lc.info.requestName +
    "] Status: " +
    lc.response.status,
);

console & lc.sendRequest

Console API

Standard JavaScript-style logging functions. All output is captured and displayed in the Console tab.

MethodDescription
console.log(args...)General logging
console.info(args...)Informational messages
console.warn(args...)Warning messages
console.error(args...)Error messages
console.debug(args...)Debug messages
console.log("Request sent successfully");
console.info("Processing", 42, "items");
console.warn("Rate limit approaching:", 95, "%");
console.error("Failed to parse response");
console.log({ name: "John", age: 30 }); // Objects are JSON-formatted

lc.sendRequest

Enables request chaining by sending HTTP requests from within scripts.

Syntax

lc.sendRequest(options, callback);

Options Object

PropertyTypeRequiredDescription
urlstringYesTarget URL (supports {{variable}} substitution)
methodstringNoHTTP method (default: "GET")
headersobjectNoKey-value pairs for headers
bodyanyNoRequest body (objects are JSON-stringified)

Callback Response

PropertyTypeDescription
statusnumberHTTP status code
statusTextstringHTTP status text
timenumberResponse time (ms)
headersobjectResponse headers
body.rawstringRaw response body
body.json()functionParse body as JSON
// Basic request
lc.sendRequest(
  {
    url: "https://api.example.com/users",
    method: "GET",
  },
  function (err, response) {
    if (err) {
      console.error("Request failed:", err);
      return;
    }
    console.log("Status:", response.status);
    console.log("Users:", response.body.json());
  },
);

// POST with body
lc.sendRequest(
  {
    url: "{{base_url}}/auth/login",
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ username: "admin", password: "secret" }),
  },
  function (err, response) {
    if (err) return;

    var data = response.body.json();
    if (data && data.token) {
      lc.env.set("auth_token", data.token);
    }
  },
);

OAuth2 Token Refresh Example

// Pre-request: Auto-refresh expired token
var tokenExpiry = lc.globals.get("token_expiry");
var now = Date.now();

if (!tokenExpiry || now >= tokenExpiry) {
  console.info("Token expired, refreshing...");

  lc.sendRequest(
    {
      url: "{{auth_url}}/oauth/token",
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: "grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}",
    },
    function (err, response) {
      if (err || response.status !== 200) return;

      var data = response.body.json();
      lc.env.set("access_token", data.access_token);
      lc.globals.set("token_expiry", now + data.expires_in * 1000 - 60000);
    },
  );
}

lc.request.setHeader("Authorization", "Bearer " + lc.env.get("access_token"));

Summary

APIPurposeAvailability
lc.requestHTTP request manipulationPre-request (mutable), Post-response (read-only)
lc.responseHTTP response accessPost-response only
lc.envEnvironment variables (persisted)Both
lc.globalsSession variables (in-memory)Both
lc.test / lc.expectTesting and assertionsBoth
lc.cookiesCookie managementBoth
lc.base64Base64 encoding/decodingBoth
lc.cryptoCryptographic functionsBoth
lc.variablesDynamic data generationBoth
lc.infoExecution context infoBoth
consoleLoggingBoth
lc.sendRequestRequest chainingBoth