APIZDocs

APIZ guide

Patch A Request Before It Reaches Upstream

Use a Policy patch when an agent's stable request shape needs a bounded adapter- validated transformation before forwarding—for example, adding a required API version header or rewriting a compatibility path. A patch cannot access or inject decrypted upstream credentials.

Web Console

  1. Open Policies → Create Policy → Scripted for conditional or multi-field transformations. A simple Structured outcome may also use patch parameters.
  2. Edit only the logical request fields needed for the transformation.
  3. Commit the editor and return api.patch with a stable reason.
  4. Add one patch fixture that asserts the expected output request and denial fixtures for unsafe or unsupported input.
  5. Publish, run the exact suite, enable, and attach at a known Policy order.

Example Scripted Policy fragment:

import { definePolicy } from "@apiz/policy-sdk";

export default definePolicy({
  version: "v1",
  decide(_ctx, api, request) {
    if (request.method !== "GET" || request.path !== "/readyz") {
      return api.deny("unsupported_request");
    }
    const editor = request.edit();
    editor.setPath("/version");
    editor.headers.set("X-API-Version", "2026-07-01");
    return api.patch("compatibility_rewrite", editor.commit());
  },
});

CLI

Use the source, manifest, and fixture structure from the Scripted Policy tutorial:

apiz -o json policy publish --project ./compatibility-rewrite > policy-review.json
POLICY_ID=$(jq -r '.candidate.policy_id' policy-review.json)
DRAFT_REVISION=$(jq -r '.candidate.draft_revision' policy-review.json)
POLICY_REVISION=$(jq -r '.candidate.current_published_revision' policy-review.json)
jq '{candidate, changes, evidence, traffic_effect}' policy-review.json
apiz -o json policy publish "$POLICY_ID" --project ./compatibility-rewrite \
  --expected-draft-revision "$DRAFT_REVISION" \
  --expected-policy-revision "$POLICY_REVISION" --confirm > policy.json
apiz policy test-suite "$POLICY_ID"
apiz policy enable "$POLICY_ID"
apiz client binding policy add <client-binding-id> \
  --policy "$POLICY_ID" --order 100

Verify Atomic Validation

Access Logs should show decision=patch, the safe reason, sanitized patch summary, final normalized request, and upstream result. APIZ re-normalizes the complete patched request and the adapter validates it before any mutation is committed or forwarded. Invalid path, query, header, body, or credential-control changes deny atomically; partial patches never reach upstream.

Later Policy Bindings evaluate the patched request in configured order. Keep security-critical Policies mandatory and test composition whenever ordering changes.