@@ -3,9 +3,25 @@ Apply guardrails to a piece of text and deliver the sanitised result via a webho
 This endpoint exists for callers who manage their own LLM workflow but want to
 reuse Kaapi's guardrails service. It is symmetric for input and output
 guardrails: send the text that needs sanitisation in `text` along with one or
-more `validator_config_id`s, and receive the sanitised text on your
+more validators in `config`, and receive the sanitised text on your
 `callback_url`.
 
+Each `config` entry is either a stored validator config or an inline spec,
+picked by the presence of `validator_config_id`:
+
+```json
+{
+  "text": "...",
+  "config": [
+    { "validator_config_id": "<uuid>" },
+    { "type": "pii_remover", "on_fail": "fix" }
+  ]
+}
+```
+
+Inline `type` is one of the types listed by `GET /api/v1/guardrails`; its
+tuning params sit alongside it. Stored configs run before inline specs.
+
 ### Flow
 
 1. Caller POSTs `{text, config, callback_url}` to `/api/v1/guardrails`.
@@ -50,15 +66,12 @@ carries the upstream message, and `data` is `null`. If the guardrails service
 is unreachable the job still succeeds but the webhook carries the original
 text unchanged and `metadata.warnings` carries a human-readable note (e.g.
 `"Guardrails service was unavailable; original text was returned unchanged."`).
-Other warnings may surface for duplicate validator IDs, an empty validator
+Other warnings may surface for duplicate validators, an empty validator
 list, or a missing sanitised text in the upstream response.
 
 ### Notes
 
-- `config[].type` and `config[].tag` are caller-side
-  bookkeeping. They are not interpreted by the server but are useful for your
-  own correlation (echoed back via `request_metadata` if you include them
-  there).
+- To correlate callbacks with requests, put your keys in `request_metadata`.
 - For output-guardrail flows that need the original prompt paired with the
   LLM output, this endpoint v1 sends only `text`; pairing is not exposed.
 - The same webhook signing scheme as `/llm/call` is used when a webhook secret
 
@@ -1,7 +1,4 @@
-from app.models.guardrails.request import (
-    GuardrailValidator,
-    GuardrailsRequest,
-)
+from app.models.guardrails.request import GuardrailsRequest
 from app.models.guardrails.response import (
     GuardrailsCallbackData,
     GuardrailsCallbackResponse,
@@ -13,7 +10,6 @@
 )
 
 __all__ = [
-    "GuardrailValidator",
     "GuardrailsCallbackData",
     "GuardrailsCallbackResponse",
     "GuardrailsCallbackUsage",
 
@@ -1,43 +1,16 @@
 from typing import Any
-from uuid import UUID
 
 from pydantic import HttpUrl
 from sqlmodel import Field, SQLModel
 
-
-class GuardrailValidator(SQLModel):
-    """Single validator reference inside a /guardrails request.
-
-    Only ``validator_config_id`` is meaningful to the server. ``type`` and
-    ``tag`` are caller-side bookkeeping fields: they are accepted and
-    persisted on ``job.meta.request`` for traceability, but they are not
-    echoed back on the webhook payload. To correlate webhooks with
-    requests, put your correlation keys in ``request_metadata`` (which is
-    echoed under the callback's ``metadata`` field).
-    """
-
-    validator_config_id: UUID = Field(
-        ...,
-        description="ID of a validator configuration registered with the guardrails service.",
-    )
-    type: str | None = Field(
-        default=None,
-        description=(
-            "Optional bookkeeping label for the caller (e.g. 'input_guardrail' "
-            "or 'output_guardrail'). Server does not interpret this field."
-        ),
-    )
-    tag: str | None = Field(
-        default=None,
-        description="Optional caller-side tag. Server does not interpret this field.",
-    )
+from app.models.llm.request import GuardrailEntry
 
 
 class GuardrailsRequest(SQLModel):
     """Request body for ``POST /api/v1/guardrails``.
 
     The endpoint is symmetric for input and output guardrails: send the text
-    that needs sanitisation in ``text`` along with the validator IDs to apply.
+    that needs sanitisation in ``text`` along with the validators to apply.
     The sanitised text is delivered via the configured ``callback_url``.
     """
 
@@ -46,10 +19,13 @@ class GuardrailsRequest(SQLModel):
         min_length=1,
         description="Text to validate/sanitise. May be a user prompt or an LLM response.",
     )
-    config: list[GuardrailValidator] = Field(
+    config: list[GuardrailEntry] = Field(
         ...,
         min_length=1,
-        description="Validators to apply, identified by validator_config_id.",
+        description=(
+            "Validators to apply: `{validator_config_id}` for a stored config, "
+            "or an inline spec `{type, ...params}`."
+        ),
     )
     callback_url: HttpUrl | None = Field(
         default=None,
 
@@ -1,3 +1,4 @@
+import json
 import logging
 from typing import Any
 from uuid import UUID, uuid4
@@ -19,9 +20,8 @@
     GuardrailsOutput,
     GuardrailsOutputContent,
     GuardrailsRequest,
-    GuardrailValidator,
 )
-from app.models.llm.request import Validator
+from app.models.llm.request import InlineValidator, Validator
 from app.services.llm.guardrails import GuardrailsOutcome, apply_guardrails
 from app.utils import APIResponse, get_webhook_secret, send_callback
 
@@ -203,26 +203,35 @@ def _update_job(job_uuid: UUID, **fields: Any) -> None:
 
 
 def _dedupe_validators(
-    config: list[GuardrailValidator],
-) -> tuple[list[Validator], list[str]]:
-    """Drop duplicate validator IDs (preserve order) to avoid double-billing upstream.
+    config: list[Validator | InlineValidator],
+) -> tuple[list[Validator | InlineValidator], list[str]]:
+    """Drop duplicate validators (preserve order) to avoid double-billing upstream.
 
+    Refs are keyed by ID, inline specs by their full canonical JSON.
     Returns the unique validators plus any caller-facing warnings.
     """
-    seen_ids: set[UUID] = set()
-    validators: list[Validator] = []
+    seen_keys: set[str] = set()
+    validators: list[Validator | InlineValidator] = []
     duplicates = 0
-    for g in config:
-        if g.validator_config_id in seen_ids:
+    for validator in config:
+        # A disabled entry must not claim the key and shadow an enabled duplicate.
+        if not validator.is_enabled:
+            continue
+        key = (
+            str(validator.validator_config_id)
+            if isinstance(validator, Validator)
+            else json.dumps(validator.model_dump(mode="json"), sort_keys=True)
+        )
+        if key in seen_keys:
             duplicates += 1
             continue
-        seen_ids.add(g.validator_config_id)
-        validators.append(Validator(validator_config_id=g.validator_config_id))
+        seen_keys.add(key)
+        validators.append(validator)
 
     warnings: list[str] = []
     if duplicates:
         warnings.append(
-            f"Request contained {duplicates} duplicate validator_config_id "
+            f"Request contained {duplicates} duplicate validator "
             "entries; duplicates were ignored before calling the guardrails service."
         )
     if not validators:
 
@@ -187,6 +187,42 @@ def test_apply_guardrails_malformed_validator_id_422(
     assert resp.status_code == 422
 
 
+@pytest.mark.parametrize(
+    "config",
+    [
+        [{"type": "pii_remover", "on_fail": "fix"}],
+        [{"validator_config_id": VALIDATOR_ID}, {"type": "uli_slur_match"}],
+        # Legacy bookkeeping fields are ignored, not rejected.
+        [{"validator_config_id": VALIDATOR_ID, "type": "input_guardrail", "tag": "x"}],
+    ],
+    ids=["inline", "mixed", "legacy_type_tag"],
+)
+def test_apply_guardrails_accepts_ref_and_inline_entries(
+    client: TestClient, user_api_key_header: dict[str, str], config: list[dict]
+) -> None:
+    with patch("app.api.routes.guardrails.start_job") as mock_start:
+        mock_start.return_value = _stub_job()
+        resp = client.post(
+            "api/v1/guardrails",
+            json=_payload(config=config),
+            headers=user_api_key_header,
+        )
+
+    assert resp.status_code == 200
+    mock_start.assert_called_once()
+
+
+def test_apply_guardrails_unknown_inline_type_422(
+    client: TestClient, user_api_key_header: dict[str, str]
+) -> None:
+    resp = client.post(
+        "api/v1/guardrails",
+        json=_payload(config=[{"type": "not_a_validator"}]),
+        headers=user_api_key_header,
+    )
+    assert resp.status_code == 422
+
+
 def test_apply_guardrails_requires_auth(client: TestClient) -> None:
     resp = client.post("api/v1/guardrails", json=_payload())
     assert resp.status_code in (401, 403)
 
@@ -8,6 +8,7 @@
 
 from app.models import Job, JobStatus, JobType
 from app.models.guardrails import GuardrailsRequest
+from app.models.llm.request import InlineValidator, Validator
 from app.services.guardrails.jobs import (
     _build_callback_payload,
     _coerce_int,
@@ -301,6 +302,85 @@ def test_execute_job_dedupes_duplicate_validators_and_warns(
     assert any("duplicate" in w for w in warnings)
 
 
+def test_execute_job_passes_inline_specs_and_dedupes_them(
+    user_api_key: TestAuthContext,
+) -> None:
+    pii = {"type": "pii_remover", "on_fail": "fix"}
+    req = GuardrailsRequest.model_validate(
+        {
+            "text": "My email is alice@example.com",
+            "config": [
+                {"validator_config_id": str(VALIDATOR_A)},
+                pii,
+                {"on_fail": "fix", "type": "pii_remover"},
+            ],
+        }
+    )
+
+    with _patched_worker_db() as mock_crud, patch(
+        "app.services.guardrails.jobs.apply_guardrails"
+    ) as mock_apply:
+        mock_apply.return_value = GuardrailsOutcome(
+            safe_text="ok",
+            error=None,
+            bypassed=False,
+            rephrase_needed=False,
+            raw={"data": {}},
+        )
+        execute_job(
+            project_id=user_api_key.project_id,
+            job_id=str(uuid4()),
+            task_id="t",
+            task_instance=None,
+            request_data=req.model_dump(mode="json"),
+            organization_id=user_api_key.organization_id,
+        )
+
+    ref, inline = mock_apply.call_args.kwargs["validators"]
+    assert isinstance(ref, Validator) and ref.validator_config_id == VALIDATOR_A
+    assert isinstance(inline, InlineValidator)
+    assert inline.model_dump(mode="json", exclude={"is_enabled"}) == pii
+
+    warnings = _update_calls(mock_crud)[-1].meta["callback"]["warnings"]
+    assert any("duplicate" in w for w in warnings)
+
+
+def test_execute_job_disabled_entry_does_not_shadow_enabled_duplicate(
+    user_api_key: TestAuthContext,
+) -> None:
+    req = GuardrailsRequest.model_validate(
+        {
+            "text": "hi",
+            "config": [
+                {"validator_config_id": str(VALIDATOR_A), "is_enabled": False},
+                {"validator_config_id": str(VALIDATOR_A)},
+            ],
+        }
+    )
+
+    with _patched_worker_db(), patch(
+        "app.services.guardrails.jobs.apply_guardrails"
+    ) as mock_apply:
+        mock_apply.return_value = GuardrailsOutcome(
+            safe_text="hi",
+            error=None,
+            bypassed=False,
+            rephrase_needed=False,
+            raw={"data": {}},
+        )
+        execute_job(
+            project_id=user_api_key.project_id,
+            job_id=str(uuid4()),
+            task_id="t",
+            task_instance=None,
+            request_data=req.model_dump(mode="json"),
+            organization_id=user_api_key.organization_id,
+        )
+
+    (validator,) = mock_apply.call_args.kwargs["validators"]
+    assert validator.is_enabled
+
+
 def test_execute_job_bypassed_adds_warning(user_api_key: TestAuthContext) -> None:
     req = _make_request()
 
 
@@ -8,7 +8,7 @@ All paths relative to `backend/app/`. Related: [llm-call.md](llm-call.md) (guard
 
 | Entry point | Shape | Where |
 |---|---|---|
-| `POST /guardrails` | Standalone async job. Caller supplies text + validator IDs, gets `job_id`, result via webhook or poll. For callers running their own LLM workflow. | `api/routes/guardrails.py`, `services/guardrails/jobs.py` |
+| `POST /guardrails` | Standalone async job. Caller supplies text + validators (stored IDs or inline specs), gets `job_id`, result via webhook or poll. For callers running their own LLM workflow. | `api/routes/guardrails.py`, `services/guardrails/jobs.py` |
 | `/llm/call` + `/llm/chain` + **fast evaluation** | Inline hooks around the provider call, driven by `config_blob.input_guardrails` / `output_guardrails`. | `services/llm/jobs.py` (`apply_input_guardrails`, `apply_output_guardrails`) |
 
 Both funnel into `apply_guardrails()` in `services/llm/guardrails.py`. That module is the **only** place that talks HTTP to the guardrails service.
@@ -71,7 +71,8 @@ Worker (`execute_job`): PROCESSING → `_dedupe_validators` → `apply_guardrail
 
 Endpoint-specific behaviour, none of which exists on the `/llm/call` path:
 
-- **Dedupe.** `_dedupe_validators` drops repeated `validator_config_id`s (order-preserving) so callers are not double-billed upstream.
+- **Validator shape.** `GuardrailsRequest.config` is `list[GuardrailEntry]`, the same ref-or-inline union as `/llm/call` blobs. Refs run before inline specs (`apply_guardrails` concatenates `fetched + inline_specs`).
+- **Dedupe.** `_dedupe_validators` drops repeated entries (order-preserving) so callers are not double-billed upstream — refs keyed by `validator_config_id`, inline specs by canonical JSON.
 - **Warnings channel.** Bypass, dedupe, and "no validators resolved" become human-readable strings. Delivered as `metadata.warnings` in the callback and `warnings[]` on the poll response. A caller-supplied `warnings` key in `request_metadata` is overwritten (documented in the model docstring).
 - **`job.meta`** holds `{request, response, callback}`. Raw unsafe text is persisted on purpose — this endpoint exists to inspect unsafe content.
 - **`response_id` is server-minted** (`uuid4`), so callers always have a stable correlation handle even when upstream returns none.