Functions API
Run your own code on gateway requests. A gateway function is a Python script, or a remote MCP server, that the gateway runs for the requests you choose. This API creates and tests functions, stores the data they read, lists what they remembered, and attaches them to requests with function bindings.
For what functions can do, the script reference and worked examples, see Gateway functions. This page is the API reference.
Functions, their data and their memory are created and changed only through the Management API. The console shows them read-only under Govern > Policy Engine > LLM Gateway > Functions, and lets you attach saved functions to requests in the Functions control. Try every operation in the Management API playground.
Routes
Every path is relative to https://<your-gateway-host>/llmgateway/management/v1 and takes Authorization: Bearer <management key>. Reads need the read scope. Everything else needs functions:write (Manage functions in the console), including validating and test-running.
Function, data and memory writes go to the QuilrAI-hosted regional service. A self-hosted node connected to it answers 503 central_service_required.
Functions
Definition
A function id starts with a lower-case letter and has up to 64 lower-case letters, digits and underscores. Ids that start with quilr_ and the built-in names (web_search, fetch_url, get_category, inject_data, datetime, tool_search) are reserved (422 reserved_function_id). mcp is a kind, not a reserved id.
Create a function:
curl --request PUT \
"$MANAGEMENT_URL/llmgateway/management/v1/functions/add_account_context" \
--header "Authorization: Bearer $MANAGEMENT_KEY" \
--header 'Content-Type: application/json' \
--data '{
"display_name": "Add account context",
"description": "Adds the customer plan in front of the latest user message.",
"code": "plans = await data.get(\"support/plans\", {})\nemail = (request.get(\"user\") or {}).get(\"email\")\nawait conv.add_context(\"Customer plan: \" + plans.get(email, \"free\"))\n{\"added\": True}",
"timeout_ms": 2000
}'
The response returns function (with version, etag, updated_at and updated_by), changed, warnings and applies_within_seconds. A save reaches every gateway server within about two minutes.
Versions and concurrency
- Versions. Every change makes a new version. A save that changes nothing returns
changed: false. The newest 20 versions are kept, andPOST /functions/{function_id}/restorewith{"version": 3}saves the chosen version as a new one. - ETag.
GET /functions/{function_id}sends anETagheader: the bodyetagin double quotes. Send that header value as it is, quotes included, inIf-MatchonPUT,PATCH,DELETEand restore. A stale value answers412 version_conflict, and so does theetagwithout its quotes.If-Match: "absent"creates only. - No dry run. The function, function data and function memory routes have no dry run:
?dry_run=trueanswers400 invalid_requestand changes nothing. So does any other query parameter a route does not read;fieldslists them. To check a definition without saving it, usePOST /functions/_validate. Function bindings do support?dry_run=true. - PATCH.
nullresets a field to its default. Insidesecrets,nullremoves that secret.
Secrets
Secrets are write-only and stored encrypted. Reads show ********. A script never sees a secret value: http_request attaches the secrets a call names, and an MCP server function names them in its headers.
MCP server functions
A function of kind mcp is a remote MCP server whose tools the model may call. It has no code and no args_schema, and can only be attached as a tool.
{
"kind": "mcp",
"description": "Issue tracker",
"allowed_hosts": ["mcp.example.com"],
"secrets": {"token": "<your-mcp-token>"},
"mcp": {
"url": "https://mcp.example.com/mcp",
"headers": {"Authorization": {"secret": "token", "prefix": "Bearer "}},
"tools": ["search_issues"],
"user_header": "X-User-Email",
"tool_timeout_ms": 10000,
"max_tools": 32
}
}
timeout_ms, on_failure, detokenize_args, display_name and description are also accepted. Each tool is offered to the model as mcp__<function id>__<tool name>.
Validate and test
POST /functions/_validate takes {"function": {...}} and returns valid, errors (what a save would refuse), warnings (which do not block a save) and uses (the script features the code calls). For an MCP server function it checks the shape only and connects to nothing.
Validation checks syntax and shape: the code parses, fits the size limit and reads no name it never defines. It also returns a function_sandbox_warning when the code imports a module or calls a builtin that reaches for files, the network, the process or the environment, such as import os or open(...). The definition is still valid and can be saved, but that code fails when it runs. The sandbox is what enforces, and the warning list is not complete (eval and exec, for example, are not flagged), so test-run a function before you attach it. A save returns the same warnings.
POST /functions/_test runs a saved function (function_id) or an unsaved definition (function) in the sandbox. Nothing is sent anywhere and nothing is stored: outside calls answer from mocks.
curl --request POST \
"$MANAGEMENT_URL/llmgateway/management/v1/functions/_test" \
--header "Authorization: Bearer $MANAGEMENT_KEY" \
--header 'Content-Type: application/json' \
--data '{
"function_id": "add_account_context",
"request": {"user": {"email": "ana@example.com"}},
"mocks": {
"data": {"support/plans": {"ana@example.com": "enterprise"}},
"conv": {"messages": [{"role": "user", "text": "Where is my invoice?"}]}
}
}'
{
"ok": true,
"ms": 1,
"calls": [{"name": "data_get", "ok": true, "ms": 0}],
"logs": "",
"actions": [{"kind": "add_context", "where": "user", "text": "Customer plan: enterprise"}],
"result": {"added": true},
"request_id": "req_example"
}
The response has ok, ms, calls, logs, then result or outcome (respond, block or retry), actions (what the script asked to change, applied to nothing), and error with code and message when the run failed. A failed run still answers HTTP 200.
For an MCP server function, a test connects, lists the tools and returns ok, tools, tool_count, dropped and server without calling a tool. mocks: {"tools": [...]} skips the connection. An unsaved definition's secrets are never stored, so test a server that needs a credential by function_id.
Test runs are limited to 30 a minute per organization (429 function_test_rate_limited).
Delete a function that is still attached
DELETE /functions/{function_id} answers 409 function_in_use while a rule of your active policy runs the function or offers it as a tool, whether the rule comes from a function binding or from the console:
{
"error": {
"code": "function_in_use",
"message": "1 policy rule(s) run this function; remove it from them first.",
"references": [{"kind": "managed", "policy": "quilr_managed_functions_o10", "rule_index": 0, "priority": 889}]
},
"request_id": "req_example"
}
kind is managed for a binding of this API (change it through /controls/functions) and policy for a console policy rule. There is no force option. A disabled binding does not hold its functions. When the active policy cannot be read, the delete answers 503 policy_unavailable and deletes nothing; retry.
Function data
Function data is reference content your scripts read: instruction text, lookup tables, lists. Scripts read it with data.get("namespace/key") and search it with data.search(...). Scripts cannot change it.
curl --request PUT \
"$MANAGEMENT_URL/llmgateway/management/v1/function-data/support/plans" \
--header "Authorization: Bearer $MANAGEMENT_KEY" \
--header 'Content-Type: application/json' \
--data '{"value": {"ana@example.com": "enterprise"}, "description": "Plan per customer"}'
- Names. A namespace starts with a lower-case letter and has up to 64 lower-case letters, digits,
-and_. A key has up to 200 letters, digits and. _ -. - Values. Any JSON value up to 256 KB. Up to 5,000 entries per organization.
- Lists.
GET /function-datareturns sizes and descriptions, never values. Read one entry for its value. - Concurrency.
GET /function-data/{namespace}/{entry_key}sends anETagheader. Send its value, quotes included, inIf-Matchto avoid overwriting someone else's change.
Function memory
Function memory is what your scripts remembered with memory.set. It lasts until it expires or you delete it, and is shared by all of your functions. The API lists and erases it; only scripts write it.
- List.
GET /function-memorytakesscope(tenantoruser),owner,prefix,limit(1 to 1000, default 200; another value is400) andinclude_values. Each entry hasscope,owner,key,bytes,expires_at,updated_atandupdated_by.truncated: truemeans more entries exist. - Users. A user is shown as a digest (
u:...), never as an email. Filter withowner=<email>. - Values. Returned only with
include_values=true, which needsfunctions:writeand is recorded in the audit log. - Delete one entry.
DELETE /function-memory/{memory_scope}/{entry_key}. For theuserscope, name the user withowner=<email>. - Erase a person.
DELETE /function-memory?owner=<email>erases everything functions remembered about one user.?scope=tenanterases the organization-wide entries. The response is{erased, failed, scope, owner}; repeat the call untilfailedis0. - Timing. The list is read from the server that answers, so a value written elsewhere can take a few minutes to appear. Deletes reach every server within a few minutes.
Function bindings
A function does nothing until something attaches it to requests. A function binding says which functions run on which requests, at which stage. You can also attach functions in the console; see Attach a function.
Bindings are a managed control, like routes and rate limits. Each write publishes one policy revision, If-Match and Idempotency-Key work the same way, ?dry_run=true previews, and POST /controls/_batch changes several at once. See Writes, versions and idempotency. Bindings apply while the Policy Engine is on for the LLM Gateway.
curl --request PUT \
"$MANAGEMENT_URL/llmgateway/management/v1/controls/functions/support-context" \
--header "Authorization: Bearer $MANAGEMENT_KEY" \
--header 'Content-Type: application/json' \
--data '{
"description": "Account context and order lookup for the support bot",
"scope": {"apps": ["support-bot"]},
"order": 10,
"functions": [
{"id": "add_account_context", "run": "per_conversation"}
],
"tools": [
{"id": "lookup_order"}
],
"loop": {"max_turns": 4, "max_tool_calls": 12},
"post_call": [
{"id": "check_answer", "buffer": true, "max_retries": 1}
],
"on_complete": [
{"id": "report_failures"}
]
}'
A binding needs at least one entry in functions, tools, post_call or on_complete. Reads return every item with its defaults filled.
Items by stage
- Arguments.
argsis an object of plain JSON values, at most 4,096 characters as JSON. Numbers must be finite and written without an exponent: send a decimal below 0.0001, or 1e16 and above, as text. - One function, several bindings. A function id may appear once per list. A function named by two bindings runs once, with the settings of the binding that runs first.
- Per request. At most 16 functions run at each stage. The model is offered at most 32 gateway tools, and an MCP server function counts once per tool it offers. The first 64 tool items across the bindings that apply are considered; one that does not fit is left out and logged.
- Tool limits across bindings. When several bindings with a
loopapply to one request, the one with the lowestorderdecides all three values. Two enabled bindings with the sameorderthat can apply to the same request must not set differentloopvalues (422 function_loop_conflict). Give them the sameloop, differentordervalues, orscope.appsormatch.requested_modelslists with nothing in common. - MCP server functions can only be named in
tools(422 function_kind_not_allowed).argson an MCP server tool are ignored. - Built-in names (
tool_search,web_search,fetch_url,get_category,inject_data,datetime) cannot be named inpost_calloron_complete. - At most 50 bindings per organization.
With console policies
A console policy rule can attach functions too. Both count: the lists are combined, and for tool limits the higher policy priority decides. Bindings from this API sit at policy priorities 800 to 899 (899 - order). A console rule with a priority above 899 runs its functions before every binding here, one below 800 after them, and one inside 800 to 899 between them by priority.
Console rules that attach functions are listed read-only in GET /controls/functions. Bindings from this API are read-only in the console, where they carry a Managed by API tag.
Background run status
GET /functions/_on_complete/status reports how the functions that run after a request are doing:
{
"scope": "this_server",
"queued": 0,
"running": 0,
"succeeded": 412,
"failed": 3,
"dropped": 0,
"oldest_queued_at": null,
"functions": [
{"id": "report_failures", "queued": 0, "running": 0, "written": 415, "succeeded": 412, "failed": 3, "dropped": 0, "retried": 1, "last_error": "timeout", "last_error_at": 1795286331.06, "last_success": 1795286402.5}
],
"request_id": "req_example"
}
written counts the records saved for the function, and dropped the records that were never run. The numbers are those of the one server that took this call, not of the region or the whole deployment. Behind a load balancer, repeated calls can be answered by different servers and show different numbers, and a run that happened on another server is not counted here.
Audit
Function, data, memory and binding writes are recorded in the management audit log, with definitions shown with masked secrets and data values shown as sizes only. Read it with GET /audit, filtered by actor, operation, resource, since and until; see Audit. A test run is one function_test event that holds the function id, the stage and whether it passed, never code, arguments, mocks or output. A rejected write is recorded with its error code as the result.
In the console, the same events are under Settings > AI Gateway > LLM Gateway > Management API > History.
Errors
Management API errors use the usual envelope, {"error": {"code", "message", ...}, "request_id"}.
Binding writes also return the usual control errors (428 precondition_required, 429 publish_rate_limited and the others in Management API errors).
Two more codes can come back when you publish a policy in the console, not from this API:
Gateway clients, not Management API callers, receive these when a function refuses a request:
Limits
Endpoints
Functions, data and memory
/function-dataList function data
Data entries functions can read (for example instruction text to attach). Values are left out; sizes are in bytes.
readPath, query & header parameters 1
namespace (query)stringoptionalOnly entries in this namespace.
No request body.
curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/function-data' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/function-data/{namespace}/{entry_key}Delete a data entry
Delete the entry. Send If-Match with the ETag header value a read returned (the etag in double quotes) to avoid overwriting someone else's change. This route has no dry run: a dry_run query parameter is a 400.
functions:writePath, query & header parameters 2
namespace (path)stringrequiredThe data namespace (lower-case letters, digits, - and _).
entry_key (path)stringrequiredThe data key (letters, digits and . _ -).
Full request body specification application/json
Unknown fields are rejected in this object.
curl --request DELETE \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/function-data/namespace_example/entry_key_example' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/function-data/{namespace}/{entry_key}Read a data entry
One entry with its value. The ETag response header is the etag in double quotes; send it as it is in If-Match.
readPath, query & header parameters 2
namespace (path)stringrequiredThe data namespace (lower-case letters, digits, - and _).
entry_key (path)stringrequiredThe data key (letters, digits and . _ -).
No request body.
curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/function-data/namespace_example/entry_key_example' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/function-data/{namespace}/{entry_key}Create or replace a data entry
Store any JSON value up to 256 KB. Scripts read it with data.get('namespace/key') and cannot change it. Send If-Match with the ETag header value a read returned (the etag in double quotes) to avoid overwriting someone else's change. This route has no dry run: a dry_run query parameter is a 400.
functions:writePath, query & header parameters 2
namespace (path)stringrequiredThe data namespace (lower-case letters, digits, - and _).
entry_key (path)stringrequiredThe data key (letters, digits and . _ -).
Full request body specification application/json
descriptionstringoptionalvalueobjectrequiredUnknown fields are rejected in this object.
curl --request PUT \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/function-data/namespace_example/entry_key_example' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"value": "When a customer asks for a refund ..."
}'
Authentication, errors & retry rules Try it in the playground
/function-memoryErase one owner's function memory
Delete every entry of one owner: owner=<email> for a user (the way to erase what functions remembered about a person), or scope=tenant for the tenant-wide entries. Each key is deleted on its own; failed counts the ones that could not be, so repeat the call until it is 0.
functions:writePath, query & header parameters 2
scope (query)stringoptionaltenant erases the tenant-wide entries; user (with owner) erases one user's.
"tenant""user"owner (query)stringoptionalThe user: an email (the server derives the digest), or a digest a listing showed. Not used for the tenant scope.
Full request body specification application/json
Unknown fields are rejected in this object.
curl --request DELETE \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/function-memory' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/function-memoryList function memory
What this tenant's functions remembered with memory.set: keys, sizes and times, read from this server's copy (a write made elsewhere shows up within a few minutes). Values are left out unless include_values=true, which needs the functions:write scope and is recorded in the audit log. A user is shown as a digest, never as an email; filter by owner with the user's email.
readPath, query & header parameters 5
scope (query)stringoptionalOnly this scope.
"tenant""user"owner (query)stringoptionalThe user: an email (the server derives the digest), or a digest a listing showed. Not used for the tenant scope.
prefix (query)stringoptionalOnly keys that start with this.
limit (query)integeroptionalAt most this many entries.
include_values (query)booleanoptionaltrue returns each entry's value. Needs functions:write.
No request body.
curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/function-memory?limit=example' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/function-memory/{memory_scope}/{entry_key}Delete a function memory entry
Delete one entry. For the user scope name the user with owner=<email>.
functions:writePath, query & header parameters 3
memory_scope (path)stringrequiredtenant or user.
entry_key (path)stringrequiredThe memory key (letters, digits and . _ : @ -).
owner (query)stringoptionalThe user: an email (the server derives the digest), or a digest a listing showed. Not used for the tenant scope.
Full request body specification application/json
Unknown fields are rejected in this object.
curl --request DELETE \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/function-memory/memory_scope_example/entry_key_example' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/functionsList functions
The functions this tenant defined, without their code, and the names of the built-in functions. A function is code an administrator attaches to gateway requests; it runs in a sandbox.
readNo request body.
curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/functions' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/functions/_on_complete/statusBackground function status
How the functions a policy runs in the background after a request are doing on the server that answers this call: requests waiting, running now, and per function how many runs succeeded, failed or were dropped, with the last error. Counts are per server and start when that server first ran a background function; a deployment with several servers answers from one of them.
readNo request body.
curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/functions/_on_complete/status' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/functions/_testRun a function
Run a saved function (function_id) or an unsaved definition (function) in the sandbox with the given args and request facts. No request is sent anywhere: model calls, web search and HTTP calls answer from mocks, and a call with no mock fails inside the script. Admin data is read from the stored entries unless mocked. Limited to a number of runs per minute.
functions:writeFull request body specification application/json
argsobjectoptionalfunctionobjectoptionalObject fields
allowed_hostsarray<string>optionalHost names http_request may call (*.example.com allowed).
Array item specification
stringargs_schemaobjectoptionalJSON Schema (an object with typed properties) of args.
codestringoptionalPython source. It runs in a sandbox with no file, network or environment access and reaches the outside only through the host functions.
descriptionstringoptionaldeterministicbooleanoptionalTrue when the same input always gives the same result.
detokenize_argsbooleanoptionalRestore tokenized values in the arguments before the function runs. Needs allowed_hosts.
display_namestringoptionalkindstringoptional"python""mcp"llm_targetsarray<string>optionalProvider labels (or label/model) call_llm may use.
Array item specification
stringmax_host_callsintegeroptionalmax_output_charsintegeroptionalmcpobjectoptionalkind mcp only: the remote MCP server whose tools the gateway offers. {url, headers, tools, user_header, tool_timeout_ms, max_tools}. No code and no args_schema.
on_failurestringoptionalWhat the request does when the function fails: allow continues without it.
"allow""block"secretsmap<string, string | null>optionalWrite-only named secrets. Reads show ********; send ******** to keep a stored value. The script never sees a secret: http_request attaches the ones it names.
Map value specification
string | nulltimeout_msintegeroptionalUnknown fields are rejected in this object.
function_idstringoptionalA saved function. Send this or function.
mocksobjectoptionalAnswers for host functions by name; {"$error": "message"} makes one fail. conv is the conversation the script reads: {"system": text, "messages": [{role, text}]}. response tests a response-stage function: the model's answer the script reads as response ({"text", "tool_calls": [{id, name, arguments}], "stop_reason", "model", "usage", "attempt"}). event tests a background function: the finished request's record the script reads as event. Send response or event, not both.
requestobjectoptionalThe request facts the script reads as request.
Unknown fields are rejected in this object.
curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/functions/_test' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"args": {},
"function_id": "attach_refund_skill",
"mocks": {
"data": {
"skills/refunds": "When a customer asks for a refund ..."
}
},
"request": {
"user": "ana@example.com"
}
}'
Authentication, errors & retry rules Try it in the playground
/functions/_validateCheck a function
Check a definition without saving it. Errors are what a save would refuse; warnings do not block a save. This checks syntax and shape. Code that imports a module or calls a builtin that reaches for files, the network, the process or the environment (import os, open) gets a warning and fails when it runs: the sandbox is what enforces.
functions:writeFull request body specification application/json
functionobjectrequiredObject fields
allowed_hostsarray<string>optionalHost names http_request may call (*.example.com allowed).
Array item specification
stringargs_schemaobjectoptionalJSON Schema (an object with typed properties) of args.
codestringoptionalPython source. It runs in a sandbox with no file, network or environment access and reaches the outside only through the host functions.
descriptionstringoptionaldeterministicbooleanoptionalTrue when the same input always gives the same result.
detokenize_argsbooleanoptionalRestore tokenized values in the arguments before the function runs. Needs allowed_hosts.
display_namestringoptionalkindstringoptional"python""mcp"llm_targetsarray<string>optionalProvider labels (or label/model) call_llm may use.
Array item specification
stringmax_host_callsintegeroptionalmax_output_charsintegeroptionalmcpobjectoptionalkind mcp only: the remote MCP server whose tools the gateway offers. {url, headers, tools, user_header, tool_timeout_ms, max_tools}. No code and no args_schema.
on_failurestringoptionalWhat the request does when the function fails: allow continues without it.
"allow""block"secretsmap<string, string | null>optionalWrite-only named secrets. Reads show ********; send ******** to keep a stored value. The script never sees a secret: http_request attaches the ones it names.
Map value specification
string | nulltimeout_msintegeroptionalUnknown fields are rejected in this object.
Unknown fields are rejected in this object.
curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/functions/_validate' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"function": {
"code": "skill = await data.get('\''skills/refunds'\'')\n{'\''skill'\'': skill}"
}
}'
Authentication, errors & retry rules Try it in the playground
/functions/{function_id}Delete a function
Delete the function. While a policy rule or a function binding still runs it or offers it to the model as a tool, the delete answers 409 function_in_use with those references (kind, policy, rule_index, priority); remove the function from them first. There is no override. 503 policy_unavailable when the active policy cannot be read to check; retry. Send If-Match with the ETag header value a read returned (the etag in double quotes) to avoid overwriting someone else's change. This route has no dry run: a dry_run query parameter is a 400.
functions:writePath, query & header parameters 1
function_id (path)stringrequiredThe function id (lower-case letters, digits and underscores).
Full request body specification application/json
Unknown fields are rejected in this object.
curl --request DELETE \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/functions/function_id_example' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/functions/{function_id}Read a function
One function with its code. Secrets are shown as ********. The ETag response header is the etag in double quotes; send it as it is in If-Match.
readPath, query & header parameters 1
function_id (path)stringrequiredThe function id (lower-case letters, digits and underscores).
No request body.
curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/functions/function_id_example' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/functions/{function_id}Change a function
Change some fields. null resets a field to its default; inside secrets, null removes that secret. Send If-Match with the ETag header value a read returned (the etag in double quotes) to avoid overwriting someone else's change. This route has no dry run: a dry_run query parameter is a 400.
functions:writePath, query & header parameters 1
function_id (path)stringrequiredThe function id (lower-case letters, digits and underscores).
Full request body specification application/json
allowed_hostsarray<string>optionalHost names http_request may call (*.example.com allowed).
Array item specification
stringargs_schemaobjectoptionalJSON Schema (an object with typed properties) of args.
codestringoptionalPython source. It runs in a sandbox with no file, network or environment access and reaches the outside only through the host functions.
descriptionstringoptionaldeterministicbooleanoptionalTrue when the same input always gives the same result.
detokenize_argsbooleanoptionalRestore tokenized values in the arguments before the function runs. Needs allowed_hosts.
display_namestringoptionalkindstringoptional"python""mcp"llm_targetsarray<string>optionalProvider labels (or label/model) call_llm may use.
Array item specification
stringmax_host_callsintegeroptionalmax_output_charsintegeroptionalmcpobjectoptionalkind mcp only: the remote MCP server whose tools the gateway offers. {url, headers, tools, user_header, tool_timeout_ms, max_tools}. No code and no args_schema.
on_failurestringoptionalWhat the request does when the function fails: allow continues without it.
"allow""block"secretsmap<string, string | null>optionalWrite-only named secrets. Reads show ********; send ******** to keep a stored value. The script never sees a secret: http_request attaches the ones it names.
Map value specification
string | nulltimeout_msintegeroptionalUnknown fields are rejected in this object.
curl --request PATCH \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/functions/function_id_example' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"timeout_ms": 3000
}'
Authentication, errors & retry rules Try it in the playground
/functions/{function_id}Create or replace a function
Create the function or replace its definition. Each change makes a new version; a save that changes nothing returns changed false. Leave secrets out to keep the stored ones. Send If-Match with the ETag header value a read returned (the etag in double quotes) to avoid overwriting someone else's change. This route has no dry run: a dry_run query parameter is a 400.
functions:writePath, query & header parameters 1
function_id (path)stringrequiredThe function id (lower-case letters, digits and underscores).
Full request body specification application/json
allowed_hostsarray<string>optionalHost names http_request may call (*.example.com allowed).
Array item specification
stringargs_schemaobjectoptionalJSON Schema (an object with typed properties) of args.
codestringoptionalPython source. It runs in a sandbox with no file, network or environment access and reaches the outside only through the host functions.
descriptionstringoptionaldeterministicbooleanoptionalTrue when the same input always gives the same result.
detokenize_argsbooleanoptionalRestore tokenized values in the arguments before the function runs. Needs allowed_hosts.
display_namestringoptionalkindstringoptional"python""mcp"llm_targetsarray<string>optionalProvider labels (or label/model) call_llm may use.
Array item specification
stringmax_host_callsintegeroptionalmax_output_charsintegeroptionalmcpobjectoptionalkind mcp only: the remote MCP server whose tools the gateway offers. {url, headers, tools, user_header, tool_timeout_ms, max_tools}. No code and no args_schema.
on_failurestringoptionalWhat the request does when the function fails: allow continues without it.
"allow""block"secretsmap<string, string | null>optionalWrite-only named secrets. Reads show ********; send ******** to keep a stored value. The script never sees a secret: http_request attaches the ones it names.
Map value specification
string | nulltimeout_msintegeroptionalUnknown fields are rejected in this object.
curl --request PUT \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/functions/function_id_example' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"code": "skill = await data.get('\''skills/refunds'\'')\n{'\''skill'\'': skill}",
"deterministic": true,
"timeout_ms": 2000
}'
Authentication, errors & retry rules Try it in the playground
/functions/{function_id}/restoreRestore a version
Make an earlier kept version current. It is saved as a new version. Send If-Match with the ETag header value a read returned (the etag in double quotes) to avoid overwriting someone else's change. This route has no dry run: a dry_run query parameter is a 400.
functions:writePath, query & header parameters 1
function_id (path)stringrequiredThe function id (lower-case letters, digits and underscores).
Full request body specification application/json
versionintegerrequiredUnknown fields are rejected in this object.
curl --request POST \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/functions/function_id_example/restore' \
--header 'Authorization: Bearer <management-key>' \
--header 'Content-Type: application/json' \
--data '{
"version": 2
}'
Authentication, errors & retry rules Try it in the playground
/functions/{function_id}/versionsList a function's versions
The newest 20 versions, newest first.
readPath, query & header parameters 1
function_id (path)stringrequiredThe function id (lower-case letters, digits and underscores).
No request body.
curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/functions/function_id_example/versions' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
Function bindings
/controls/functionsList function bindings
Every managed function binding with its ETag, then the console policy rules of the same kind as read-only rows (source console, policy, rule_index, view). Console rows cannot be written here (409 rule_not_api_managed). Paginated (limit, cursor bound to the revision) and filtered by source, app, requested_model, mode and references.
readPath, query & header parameters 7
limit (query)integeroptionalPage size.
cursor (query)stringoptionalnext_cursor of the previous page; bound to the revision (409 collection_changed when the policy changed).
source (query)objectoptionalOnly managed resources or only console rows.
"managed""console"app (query)stringoptionalRows that can apply to this app (rows scoped only by smart group, user or tag are kept). app_name is a deprecated alias.
requested_model (query)stringoptionalRows that can apply to this requested model. model is a deprecated alias.
mode (query)stringoptionalRows with this mode (routes: active, observe, disabled; limits: enforce, alert, paused).
references (query)stringoptional<provider_label> or <provider_label>/<model>: rows that name it, following destination and failover-profile refs (adds references [paths]).
No request body.
curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/functions?limit=example' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/controls/functions/{resource_id}Delete a function binding
Removes the function binding; refused while other controls reference it. If-Match is required.
functions:writePath, query & header parameters 4
resource_id (path)stringrequiredClient-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).
dry_run (query)booleanoptionalPreview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.
If-Match (header)stringrequiredResource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.
Idempotency-Key (header)stringoptionalUnique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.
Full request body specification application/json
Unknown fields are rejected in this object.
curl --request DELETE \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/functions/eu-pool' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "r12-eu-pool-1a2b3c4d"'
Authentication, errors & retry rules Try it in the playground
/controls/functions/{resource_id}Read a function binding
One function binding and its ETag.
readPath, query & header parameters 1
resource_id (path)stringrequiredClient-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).
No request body.
curl --request GET \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/functions/eu-pool' \
--header 'Authorization: Bearer <management-key>'
Authentication, errors & retry rules Try it in the playground
/controls/functions/{resource_id}Update a function binding
JSON merge patch of the function binding (null removes a field); the result is validated as a whole. If-Match is required. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.
functions:writePath, query & header parameters 4
resource_id (path)stringrequiredClient-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).
dry_run (query)booleanoptionalPreview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.
If-Match (header)stringrequiredResource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.
Idempotency-Key (header)stringoptionalUnique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.
Full request body specification application/json
JSON merge patch of ControlsFunctions: send only the fields to change; null removes a field (nested objects merge, lists are replaced). The merged resource must be a valid ControlsFunctions.
descriptionstring | nulloptionalVariant 1 string
stringAlso accepts null.
enabledboolean | nulloptionalVariant 1 boolean
booleanfalse keeps the binding but runs nothing.
Also accepts null.
functionsarray<object> | nulloptionalVariant 1 array<object>
array<object>Functions that run before the request is sent to the model, in this order. A function id may appear once in the list.
Also accepts null.
loopobject | nulloptionalVariant 1 object
max_tool_callsinteger | nulloptionalVariant 1 integer
integerHow many function calls one request may make in total.
Also accepts null.
max_turnsinteger | nulloptionalVariant 1 integer
integerHow many times the model may be called again after tool results.
Also accepts null.
on_tool_errorstring | nulloptionalVariant 1 string
stringcontinue gives the model the error so it can carry on; stop ends the answer there.
Values: "continue""stop"
Also accepts null.
Unknown fields are rejected in this object.
Also accepts null.
matchobject | nulloptionalVariant 1 object
requested_modelsarray<string> | nulloptionalVariant 1 array<string>
array<string>Also accepts null.
Unknown fields are rejected in this object.
Also accepts null.
on_completearray<object> | nulloptionalVariant 1 array<object>
array<object>Functions that run in the background after the request is finished, in this order. They cannot change the request or the answer. A function id may appear once in the list.
Also accepts null.
orderinteger | nulloptionalVariant 1 integer
integerThe lower order runs first. Bindings with the same order run in id order.
Also accepts null.
post_callarray<object> | nulloptionalVariant 1 array<object>
array<object>Functions that run on the model's answer before the client gets it, in this order. A function id may appear once in the list. On a streamed answer a function runs after the stream has ended and can only log, unless its buffer is true.
Also accepts null.
scopeobject | nulloptionalVariant 1 object
agent_familiesarray<string> | nulloptionalVariant 1 array<string>
array<string>Agent families (claude_code) or family/surface (claude_code/cli).
Also accepts null.
agent_groupsarray<string> | nulloptionalVariant 1 array<string>
array<string>Agent group ids, including the built-in all-agents, undeclared-agents and coding-tools.
Also accepts null.
agentsarray<string> | nulloptionalVariant 1 array<string>
array<string>Agent keys (<family>/<id>, as listed by GET /agents). The agent is inferred from what the client sends; the caller is authenticated by its API key or token.
Also accepts null.
app_tagsarray<string> | nulloptionalVariant 1 array<string>
array<string>Also accepts null.
appsarray<string> | nulloptionalVariant 1 array<string>
array<string>Also accepts null.
smart_groupsarray<string> | nulloptionalVariant 1 array<string>
array<string>Also accepts null.
usersarray<string> | nulloptionalVariant 1 array<string>
array<string>Also accepts null.
Unknown fields are rejected in this object.
Also accepts null.
toolsarray<object> | nulloptionalVariant 1 array<object>
array<object>Functions the model can call as tools, offered in this order. A function id may appear once in the list. The id tool_search is the gateway's own tool that finds deferred tools; it takes no other field.
Also accepts null.
Unknown fields are rejected in this object.
curl --request PATCH \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/functions/eu-pool' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "r12-eu-pool-1a2b3c4d"'
Authentication, errors & retry rules Try it in the playground
/controls/functions/{resource_id}Create or replace a function binding
Creates (201) or replaces (200) the function binding. Changing an existing one needs If-Match; If-None-Match: * creates only. Writes publish one policy revision. A PUT whose content equals the stored resource returns changed false and publishes nothing.
functions:writePath, query & header parameters 5
resource_id (path)stringrequiredClient-chosen control ID, ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ (console rules read as console:<policy>:<rule_index>).
dry_run (query)booleanoptionalPreview: spec and policy diff, diagnostics, warnings, would_publish and impact; nothing is saved.
If-Match (header)stringoptionalResource ETag "r<revision>-<id>-<hash8>" from the latest read, or the collection ETag "r<revision>". Required to change or delete an existing resource (428 when missing, 412 when stale); an unrelated publish does not invalidate it.
Idempotency-Key (header)stringoptionalUnique per logical write. A retry with the same key and body returns the original result, including after a crash once the revision was published. Optional on PUT, PATCH and DELETE.
If-None-Match (header)"*"optionalCreate only: 412 when the resource exists with different content.
Full request body specification application/json
A function binding runs gateway functions (see the Functions routes) on the requests its scope and match select, before the request is sent to the model. order decides which binding runs first when several apply: the lower order runs first, and bindings with the same order run in id order. A function named by two bindings runs once, with the settings of the one that runs first. Functions bound by console policy rules also run; they are listed here as read-only rows. At most 16 functions run for one request. tools offers functions to the model as tools: when the model calls one, the gateway runs the function and continues the answer, and the client sees one answer without those tool calls. A function named as a tool by two bindings is offered once, with the settings of the binding that comes first; at most 32 tools are offered for one request. loop limits that tool use. post_call runs functions on the model's answer before the client gets it: a function can pass the answer, rewrite it, block it or ask the model to answer again. on_complete runs functions in the background after the request is finished; they cannot change anything. Both follow the same order rules as functions, and at most 16 of each run for one request. A binding needs at least one entry in functions, tools, post_call or on_complete.
descriptionstringoptionalenabledbooleanoptionalfalse keeps the binding but runs nothing.
functionsarray<object>optionalFunctions that run before the request is sent to the model, in this order. A function id may appear once in the list.
Array item specification
argsobjectoptionalPassed to the function. Plain JSON values, at most 4096 characters as JSON. Keys are returned sorted.
idstringrequiredThe id of one of the tenant's functions.
observebooleanoptionaltrue runs the function and logs what it would do without changing the request.
runstringoptionalper_message runs on every request; per_conversation once per conversation.
"per_message""per_conversation"Unknown fields are rejected in this object.
loopobjectoptionalLimits for the tools of this binding; needs tools. Returned with every field. When several bindings apply, the one that runs first decides; two bindings with the same order that can apply to the same request must not set different values (422 function_loop_conflict).
Object fields
max_tool_callsintegeroptionalHow many function calls one request may make in total.
max_turnsintegeroptionalHow many times the model may be called again after tool results.
on_tool_errorstringoptionalcontinue gives the model the error so it can carry on; stop ends the answer there.
"continue""stop"Unknown fields are rejected in this object.
matchobjectoptionalOnly requests that ask for one of these models.
Object fields
requested_modelsarray<string>optionalArray item specification
stringUnknown fields are rejected in this object.
on_completearray<object>optionalFunctions that run in the background after the request is finished, in this order. They cannot change the request or the answer. A function id may appear once in the list.
Array item specification
argsobjectoptionalPassed to the function. Plain JSON values, at most 4096 characters as JSON. Keys are returned sorted.
idstringrequiredThe id of one of the tenant's functions.
Unknown fields are rejected in this object.
orderintegeroptionalThe lower order runs first. Bindings with the same order run in id order.
post_callarray<object>optionalFunctions that run on the model's answer before the client gets it, in this order. A function id may appear once in the list. On a streamed answer a function runs after the stream has ended and can only log, unless its buffer is true.
Array item specification
argsobjectoptionalPassed to the function. Plain JSON values, at most 4096 characters as JSON. Keys are returned sorted.
bufferbooleanoptionaltrue holds a streamed answer until the function has passed it, so the function can rewrite it, block it or ask the model to answer again. The client then gets the answer later. No effect on answers that are not streamed.
idstringrequiredThe id of one of the tenant's functions.
max_retriesintegeroptionalHow many times this function may ask the model to answer again.
observebooleanoptionaltrue runs the function and logs what it would do without changing the answer. Cannot be combined with buffer.
Unknown fields are rejected in this object.
scopeobjectoptionalEvery non-empty list must match (AND); empty or omitted lists do not restrict, so an empty scope selects every request. Returned with every field present.
Object fields
agent_familiesarray<string>optionalAgent families (claude_code) or family/surface (claude_code/cli).
Array item specification
stringagent_groupsarray<string>optionalAgent group ids, including the built-in all-agents, undeclared-agents and coding-tools.
Array item specification
stringagentsarray<string>optionalAgent keys (<family>/<id>, as listed by GET /agents). The agent is inferred from what the client sends; the caller is authenticated by its API key or token.
Array item specification
stringapp_tagsarray<string>optionalArray item specification
stringappsarray<string>optionalArray item specification
stringsmart_groupsarray<string>optionalArray item specification
stringusersarray<string>optionalArray item specification
stringUnknown fields are rejected in this object.
toolsarray<object>optionalFunctions the model can call as tools, offered in this order. A function id may appear once in the list. The id tool_search is the gateway's own tool that finds deferred tools; it takes no other field.
Array item specification
argsobjectoptionalFixed arguments: used in place of whatever the model sends for the same names. Plain JSON values, at most 4096 characters as JSON. Keys are returned sorted.
deferbooleanoptionaltrue keeps the tool out of the request until the model finds it with tool_search; the list must then also contain tool_search.
detokenize_argsbooleanoptionaltrue gives the function the real values behind tokenized data in the model's arguments.
idstringrequiredThe id of one of the tenant's functions, or tool_search.
Unknown fields are rejected in this object.
Unknown fields are rejected in this object.
curl --request PUT \
'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/controls/functions/eu-pool' \
--header 'Authorization: Bearer <management-key>' \
--header 'If-Match: "r12-eu-pool-1a2b3c4d"' \
--header 'Content-Type: application/json' \
--data '{
"description": "Account context for the support bot",
"functions": [
{
"args": {
"fields": [
"plan",
"region"
]
},
"id": "add_account_context",
"run": "per_conversation"
},
{
"id": "audit_request",
"observe": true
}
],
"loop": {
"max_tool_calls": 12,
"max_turns": 4,
"on_tool_error": "continue"
},
"on_complete": [
{
"args": {
"target": "warehouse"
},
"id": "export_request"
}
],
"order": 10,
"post_call": [
{
"args": {
"tone": "formal"
},
"buffer": true,
"id": "check_answer_tone",
"max_retries": 2
},
{
"id": "audit_answer",
"observe": true
}
],
"scope": {
"apps": [
"support-bot"
]
},
"tools": [
{
"args": {
"region": "eu"
},
"id": "lookup_order"
},
{
"defer": true,
"id": "search_knowledge_base"
},
{
"id": "tool_search"
}
]
}'
Authentication, errors & retry rules Try it in the playground
Related
- Gateway functions - what functions do, the script reference and worked examples.
- Management API - authentication, scopes, errors and retry rules.
- Routing and failover API - the write, ETag and dry-run rules shared by every control.
- Hooks API - call your own HTTPS API instead of running a script in the gateway.
- Management API playground - list functions, check and test-run a script, and manage bindings from the browser.