Skip to main content
POST

Authorizations

Authorization
string
header
required

Pass the API key in the Authorization header, You need to put Token keyword before the API key. e.g. 'Authorization: Token '

Body

application/json
functionMacroId
string<uuid>

A saved function or macro to run.

name
string

For an unsaved macro: its name, which picks the {% macro %} definition to run (left out: the first one in code). A HELPER is called by this name.

Required string length: 1 - 255
type
enum<string>

JAVASCRIPT_FUNCTION: the body of function (text, vars) { ... }. JINJA_MACRO: a Jinja template with text, vars and args in scope, or a {% macro <name>(...) %} definition.

Available options:
JAVASCRIPT_FUNCTION,
JINJA_MACRO
usedAs
enum<string>

CHECK: answers "does this text match?" (a guardrail's lookFor). ACTION: answers "what changes?" (a guardrail's behaviour): new text, or variables to set. HELPER: a macro prompts call by its name, as {{ <name>(...) }} (JINJA_MACRO only).

Available options:
CHECK,
ACTION,
HELPER
code
string

The code (1-20,000 characters), compiled when you save it.

Function: the body of function (text, vars) { ... }. text is what was said, as said; vars are the call's variables, as text unless a value is JSON. A CHECK returns true to match. An ACTION returns a string (the new text) or an object (the variables to set). JavaScript built-ins only (no console, fetch or timers); 50 ms and 16 MiB per run.

Macro: a template with text, vars and args, or a {% macro <name>(...) %} definition (required for HELPER, named like the record). A CHECK matches unless it renders empty, false, 0, none or no. An ACTION sets variables when it renders a JSON object; anything else is the new text. 50 ms and 64 KiB of output.

Required string length: 1 - 20000
params
string[] | null

HELPER macros only, and optional: the parameters that the {% macro <name>(...) %} in code declares, in order. Hamsa reads them from the code; if you send them they must match it (FunctionMacroParamsMismatch). Leave out or null for CHECK and ACTION.

Maximum array length: 20
Maximum string length: 64
Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
side
enum<string>
default:caller

CHECK and ACTION only: the side a guardrail is checking, passed to the script as vars._side. caller: what the caller said. agent: the agent's reply.

Available options:
caller,
agent
args
any[]

HELPER only: the arguments of the prompt call, in order, as in {{ greet('Sara') }}. Left out: each parameter is read from vars by name.

Maximum array length: 20
text
string
default:""

What was said (up to 20,000 characters), used as sent.

Maximum string length: 20000
vars
object

The call's variables. Numbers and booleans reach the script as text, as on a call; objects and arrays stay as they are.

Response

Successful response

success
boolean
Example:

true

message
string
Example:

"success"

data
object

What the code produced and what a call would do with it. A failing script still returns 200, with error set.