Quickstart: Write a Custom Policy

Write the policy module

In your clone of the gateway repository, create a modules/ directory next to config/ if it doesn't exist yet, and add modules/content-filter.ts. A policy is a function that receives the request, a context, and the options configured for it—and returns the request to continue the chain, or a Response to answer immediately:

Code
import type { ZuploContext, ZuploRequest } from "@zuplo/runtime";

interface ContentFilterOptions {
  blockedTerms: string[];
}

export default async function contentFilter(
  request: ZuploRequest,
  context: ZuploContext,
  options: ContentFilterOptions,
): Promise<ZuploRequest | Response> {
  const body = await request.clone().json();
  const text = JSON.stringify(body.messages ?? body.input ?? "");

  const match = options.blockedTerms.find((term) =>
    text.toLowerCase().includes(term.toLowerCase()),
  );

  if (match) {
    context.log.warn(
      `Blocked request from app ${request.user?.sub}: matched "${match}"`,
    );
    return new Response(
      JSON.stringify({
        error: {
          message: "This request was blocked by your content policy.",
          type: "invalid_request_error",
        },
      }),
      { status: 400, headers: { "content-type": "application/json" } },
    );
  }

  return request;
}

The calling app is available on request.user when the request's API key resolves to one—sub is the app's name—so a policy can log, branch, or report per app. It can be undefined, so use optional chaining. The example inspects chat and response payloads; embeddings requests pass through unfiltered.

Declare the policy in config/policies.json

The repository already contains config/policies.json with the built-in policy declarations. Add one more entry to its policies array—the entry's name is how the policy appears in the portal. The declaration makes the policy available for apps to select; it doesn't run for any app yet:

Code
{
  "name": "content-filter",
  "policyType": "custom-code-inbound",
  "handler": {
    "export": "default",
    "module": "$import(./modules/content-filter)",
    "options": {
      "blockedTerms": ["acme-secret-project"]
    }
  }
}

Deploy

Commit both files and push to your default branch:

Code
git add modules/content-filter.ts config/policies.json
git commit -m "Add content-filter policy"
git push

The next production deploy puts the new policy on the menu—with GitHub, the push itself deploys; see Source Control for the other Git providers.

Add the policy to an app's chain

In the Zuplo Portal, open Apps, select your app, and open its Policies tab. Click Add Policy—content-filter now appears alongside the built-in policies. Add it, drag it to where in the chain it should run, and save.

The change applies within about a minute—no deploy.

Test it

Send a prompt containing a blocked term through the app, using the URL and API key from the app page (the URL below is a stand-in for it):

Code
curl https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/chat/completions \
  -H "Authorization: Bearer YOUR_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [{"role": "user", "content": "Tell me about acme-secret-project"}]
  }'

The gateway answers with the policy's 400 response. Send a harmless prompt and the request flows through to the provider as usual. Apps that don't include content-filter in their chains are unaffected.