---
title: Functions Reference
subtitle: Built-in functions available in Rhai scripts
---

Apollo MCP Server provides several built-in function namespaces in the Rhai scripting environment. These functions are available in all Rhai scripts without any imports.

## Env

Read environment variables from the server process.

| Function         | Description                                                                                | Example                          |
| ---------------- | ------------------------------------------------------------------------------------------ | -------------------------------- |
| `Env::get(name)` | Returns the value of an environment variable or an empty string if the variable isn't set. | `let key = Env::get("API_KEY");` |

<Note>

When an environment variable isn't set, `Env::get` logs a warning and returns an empty string; it doesn't throw an error.

</Note>

```rhai
let api_key = Env::get("API_KEY");
let region = Env::get("AWS_REGION");

fn on_execute_graphql_operation(ctx) {
    ctx.headers["x-api-key"] = api_key;
}
```

## JSON

Parse and serialize JSON data.

| Function                 | Description                                                                                                    | Example                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `JSON::parse(input)`     | Parses a JSON string into a Rhai value (for example, a map, array, string, or number). Throws on invalid JSON. | `let obj = JSON::parse("{\"key\": \"value\"}");` |
| `JSON::stringify(value)` | Converts a Rhai value into a JSON string.                                                                      | `let s = JSON::stringify(#{name: "apollo"});`    |

```rhai
// Parse a JSON string into an object
let data = JSON::parse("{\"name\": \"Apollo\", \"version\": 1}");
print(data.name);    // "Apollo"
print(data.version); // 1

// Convert a Rhai map to a JSON string
let obj = #{status: "ok", count: 42};
let json_string = JSON::stringify(obj);
print(json_string);  // {"count":42,"status":"ok"}
```

## Sha256

Compute SHA-256 cryptographic hashes.

| Function                | Description                                              | Example                               |
| ----------------------- | -------------------------------------------------------- | ------------------------------------- |
| `Sha256::digest(input)` | Returns the hex-encoded SHA-256 hash of an input string. | `let hash = Sha256::digest("hello");` |

```rhai
let hash = Sha256::digest("hello");
// hash = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
```

## Regex

Perform regular-expression operations on strings.

| Function                                       | Description                                                                                                                                         | Example                                     |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `Regex::is_match(string, pattern)`             | Returns `true` if the pattern matches anywhere in the string. Throws on invalid pattern.                                                            | `Regex::is_match("hello123", "\\d+")`       |
| `Regex::replace(string, pattern, replacement)` | Replaces all matching patterns with the replacement string. Supports numbered (`$1`) and named (`$name`) capture groups. Throws on invalid pattern. | `Regex::replace("foo bar", "foo", "baz")`   |
| `Regex::matches(string, pattern)`              | Returns an array of all matching substrings or an empty array if there are no matches. Throws on invalid pattern.                                   | `Regex::matches("abc 123 def 456", "\\d+")` |

```rhai
// Check if a string contains digits
let has_numbers = Regex::is_match("order-123", "\\d+");
// has_numbers = true

// Replace all matches
let result = Regex::replace("foo bar foo", "foo", "baz");
// result = "baz bar baz"

// Use capture groups to reformat a date
let reformatted = Regex::replace("2025-01-15", "(\\d{4})-(\\d{2})-(\\d{2})", "$2/$3/$1");
// reformatted = "01/15/2025"

// Use named capture groups
let swapped = Regex::replace("John Smith", "(?P<first>\\w+) (?P<last>\\w+)", "$last, $first");
// swapped = "Smith, John"

// Find all matches
let numbers = Regex::matches("abc 123 def 456", "\\d+");
// numbers = ["123", "456"]
```

## Http

Make HTTP requests from Rhai scripts.

### Functions

| Function                   | Description                                                          | Example                                               |
| -------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- |
| `Http::get(url)`           | Sends a GET request to the given URL. Returns a `Promise`.           | `Http::get("https://api.example.com/data")`           |
| `Http::get(url, options)`  | Sends a GET request with the provided options. Returns a `Promise`.  | `Http::get(url, #{ headers: #{ "x-api-key": key } })` |
| `Http::post(url)`          | Sends a POST request to the given URL. Returns a `Promise`.          | `Http::post("https://api.example.com/data")`          |
| `Http::post(url, options)` | Sends a POST request with the provided options. Returns a `Promise`. | `Http::post(url, #{ body: payload })`                 |

All `Http` functions return a `Promise`. Call `.wait()` on the promise to block until the response is available.

### Options

The optional `options` parameter is a map that can contain any of the following keys:

| Key       | Type    | Description                      |
| --------- | ------- | -------------------------------- |
| `headers` | Map     | A map of header names to values. |
| `body`    | String  | The request body.                |
| `timeout` | Integer | Request timeout in seconds. Defaults to 30. |

### Response

Calling `.wait()` on a `Promise` returns an `HttpResponse` with these properties and methods:

| Property / Method | Return type | Description                                                             |
| ----------------- | ----------- | ----------------------------------------------------------------------- |
| `.status`         | Integer     | The HTTP status code.                                                   |
| `.text()`         | String      | The response body as a string.                                          |
| `.json()`         | Dynamic     | Parses the response body as JSON. Throws if the body is not valid JSON. |

### Examples

```rhai
// Simple GET request
let response = Http::get("https://api.example.com/health").wait();
print(response.status); // 200
print(response.text()); // "OK"

// GET with custom headers
let response = Http::get("https://api.example.com/data", #{
    headers: #{
        "authorization": "Bearer " + token,
        "accept": "application/json"
    },
    timeout: 30
}).wait();

// Parse a JSON response
let data = response.json();
print(data.name); // access fields directly

// POST with a JSON body
let response = Http::post("https://api.example.com/items", #{
    headers: #{
        "content-type": "application/json"
    },
    body: JSON::stringify(#{ name: "new item", count: 1 })
}).wait();

if response.status != 201 {
    throw #{
        message: "Failed to create item: " + response.text(),
        code: ErrorCode::INTERNAL_ERROR
    };
}
```

## ErrorCode

These are the constants for structured error responses when using `throw` in lifecycle hooks. Go to [Lifecycle Hooks](/apollo-mcp-server/rhai-lifecycle#error-handling-with-throw) for details about error handling.

| Constant                     | Description                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------- |
| `ErrorCode::INVALID_REQUEST` | Indicates a client error, like a missing header or invalid input.                         |
| `ErrorCode::INTERNAL_ERROR`  | Indicates a server-side error. This is the default when no other error code is specified. |

```rhai
fn on_execute_graphql_operation(ctx) {
    if ctx.incoming_request.headers["authorization"] == "" {
        throw #{
            message: "Authorization required",
            code: ErrorCode::INVALID_REQUEST
        };
    }
}
```
