Scripts

How to use scripts in your HTTP endpoint?

Maxim Workflows provide powerful scripting capabilities to modify requests and responses. These scripts help you transform data, add authentication, and handle complex response structures.

Scripts are optional - you’ll only need them when you want to modify your API’s behavior.

Request Modification

The prescript function runs before sending requests to your API. Use it to modify request parameters, add headers, or transform data.

function prescript(request) {
	request.headers["Authorization"] = "Bearer your-token";

	request.data = {
		...JSON.parse(request.data || "{}"),
		timestamp: Date.now(),
	};

	return request;
}

All script hooks also support asynchronous operation. You can define them as async functions, for example: async function prescript(request) { ... }.

Response Processing

The postscriptV2 function processes API responses before displaying them. Use it to transform response data or extract specific fields:

function postscriptV2(response, request) {
	return {
		content: response.data.message,
		confidence: response.data.metadata?.confidence || 1.0,
	};
}

Conversation Management

Simulation scripts only run for multi-turn conversations. They won’t execute for single-turn tests.

Use these scripts to set up and clean up multi-turn conversation tests:

function preSimulation() {
	return {
		simulationId: maxim.getVariable("simulationId"), // Unique simulation identifier provided by the platform
		startTime: Date.now(),
	};
}

function postSimulation() {
	return {
		simulationId: maxim.getVariable("simulationId"), // Unique simulation identifier provided by the platform
		endTime: Date.now(),
	};
}

Async Scripts

You can use async functions in any script hook to perform asynchronous operations such as fetching data or reading secrets before returning. Simply define the hook with the async keyword and await the required promises:

async function prescript(request) {
	const tokenResponse = await fetch("https://example.com/token");
	const { token } = await tokenResponse.json();

	request.headers["Authorization"] = `Bearer ${token}`;
	request.data = {
		...JSON.parse(request.data || "{}"),
		fetchedAt: Date.now(),
	};

	return request;
}

Viewing Logs

Scripts support standard JavaScript console methods for debugging and monitoring. You can use console.log(), console.error(), or any other console method to track execution flow and inspect data:

function prescript(request) {
	console.log("Processing request:", request.url);
	console.log("Request data:", request.data);
	
	request.headers["Authorization"] = "Bearer your-token";
	
	return request;
}

function postscriptV2(response, request) {
	console.log("Response status:", response.status);
	console.log("Response data:", response.data);
	
	return {
		content: response.data.message,
		confidence: response.data.metadata?.confidence || 1.0,
	};
}

function preSimulation() {
	console.log("Starting simulation");
	return {
		simulationId: maxim.getVariable("simulationId"),
		startTime: Date.now(),
	};
}

Variable Management

Maxim’s scripts flow providers a robust programmatic access to manage variable across the simulation course. Each sandbox has access to 4 methods

Add a new variable

Adds a variable to the simulation context using the given key and value. The variable remains accessible throughout the entire simulation.

maxim.addVariable("variable-name", "value-to-set")

Get a variable

Retrieves the value of a variable that was previously added to the simulation context, or provided by the dataset during test runs. Returns undefined if the variable is not found in the current context.

// Returns string or undefined
var test = maxim.getVariable("test-variable")

Set a variable

Sets the value of an existing variable in the simulation context, or creates it if it doesn’t exist. Use this to update the value of a variable at any point during the simulation.

maxim.setVariable("variable-name", "value to set");

Get a vault variable

This method allows you to securely retrieve a variable stored in the vault. Vault variables are typically used for secrets or sensitive data that should not be exposed in plain text. If the variable does not exist in the vault, this method will return undefined.

var vaultVariable = maxim.getVaultVariable("variable-name");

Pre-built Variables

Maxim provides several pre-built variables that are available in the script context for you to use:

input: The current input query or prompt from the dataset that is being sent to the endpoint. This represents the user’s message or query for the current turn of the conversation.
history: Contains all previous messages in a multi-turn conversation. This allows your scripts to access the complete conversation context, including all prior user messages and assistant responses.
simulationId: A unique identifier for the current simulation or test run. This can be used to track and correlate data across multiple interactions within the same simulation.

// Access predefined variables using getVariable
var simulationId = maxim.getVariable("simulationId"); // Unique identifier for the simulation
var input = maxim.getVariable("input"); // Input prompt/query to the endpoint
var history = maxim.getVariable("history"); // All previous messages in the conversation

function prescript(request) {
	// Get the input query from the dataset
	var userQuery = maxim.getVariable("input");
	
	// Access conversation history
	var conversationHistory = maxim.getVariable("history");
	
	request.data = {
		query: userQuery,
		history: conversationHistory,
		timestamp: Date.now(),
	};
	
	return request;
}

function preSimulation() {
	// Get simulation identifier
	var simId = maxim.getVariable("simulationId");
	
	console.log("Starting simulation:", simId);
	
	return {
		simulationId: simId,
		startTime: Date.now(),
	};
}

Available Libraries

You don’t need to use require or import to use these modules in scripts. These are directly available in the script environment.

axios: Axios is a popular HTTP client library for JavaScript. It provides a simple API for making HTTP requests and supports various features like request and response interceptors, request cancellation, and automatic JSON parsing.
fetch: Fetch is a modern web API for making HTTP requests in JavaScript. It provides a promise-based interface for fetching resources and supports features like streaming, request/response customization, and automatic JSON parsing.

Need access to more libraries in javascript sandbox?

Reach out to us if you need access to any other node libraries in the sandbox.

Introduction

Prompt Engineering

Offline Evals

Online Evals

Tracing

Simulations

Library

Dashboards

Integrations

Settings

CI/CD

How to use scripts in your HTTP endpoint?

Request Modification

Response Processing

Conversation Management

Async Scripts

Viewing Logs

Variable Management

Add a new variable

Get a variable

Set a variable

Get a vault variable

Pre-built Variables

Available Libraries

Need access to more libraries in javascript sandbox?

​How to use scripts in your HTTP endpoint?

​Request Modification

​Response Processing

​Conversation Management

​Async Scripts

​Viewing Logs

​Variable Management

​Add a new variable

​Get a variable

​Set a variable

​Get a vault variable

​Pre-built Variables

​Available Libraries

Need access to more libraries in javascript sandbox?

How to use scripts in your HTTP endpoint?

Request Modification

Response Processing

Conversation Management

Async Scripts

Viewing Logs

Variable Management

Add a new variable

Get a variable

Set a variable

Get a vault variable

Pre-built Variables

Available Libraries