chore(docs): Add guardrails detailed API docs

backend/app/api/docs/guardrails/create_ban_list.md

@@ -0,0 +1,34 @@
+Create a ban list — a named set of words the `ban_list` validator redacts from text.
+
+A ban list is stored by the guardrails service and scoped to the calling project. Reference it from a validator config by setting that config's `ban_list_id` to the `id` returned here.
+
+### Request
+
+```json
+{
+  "name": "Safety Banned Terms",
+  "description": "Terms not allowed for this tenant policy",
+  "domain": "abuse",
+  "is_public": false,
+  "banned_words": ["slur_a", "slur_b"]
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | string | yes | 1–100 chars. Must be unique for the project. |
+| `description` | string | yes | 1–500 chars. |
+| `banned_words` | string[] | yes | Up to 1000 entries, each 1–100 chars. |
+| `domain` | string | yes | Free-form grouping label used to filter on list. |
+| `is_public` | boolean | no | Defaults to `false`. |
+
+### Notes
+
+- `is_public: true` makes the list readable by other tenants. Updating and deleting stay restricted to the owning project regardless.
+- The response is `200`, not `201` — the guardrails service does not use `201`.
+
+### Errors
+
+- `400` — a ban list with this configuration already exists.
+- `422` — the guardrails service rejected the body.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/create_llm_prompt_config.md

@@ -0,0 +1,49 @@
+Create a stored prompt for one of the LLM-backed validators.
+
+Two validators read their instructions from a stored prompt instead of hard-coding them: `topic_relevance` (does this text stay on topic?) and `answer_relevance_custom_llm` (does this answer address the question?). Create the prompt here, then reference its `id` from the matching validator config.
+
+### Request
+
+```json
+{
+  "validator_name": "topic_relevance",
+  "name": "Maternal Health Scope",
+  "description": "Topic guard for maternal health support bot",
+  "prompt_schema_version": 1,
+  "llm_prompt": "Pregnancy care: Questions about prenatal care, ANC visits, nutrition, supplements, danger signs. Postpartum care: Questions about recovery after delivery, breastfeeding, and mother health checks."
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `validator_name` | enum | yes | `topic_relevance` or `answer_relevance_custom_llm`. Immutable after creation. |
+| `name` | string | yes | 1–100 chars. |
+| `description` | string | yes | 1–500 chars. |
+| `prompt_schema_version` | integer | no | Defaults to `1`. Must be >= 1. |
+| `llm_prompt` | string | yes | The prompt text. Non-empty. |
+
+### Placeholders
+
+For `answer_relevance_custom_llm` the prompt **must** contain both `{query}` and `{answer}`; the service rejects it otherwise. Example:
+
+```
+You are evaluating a maternal health assistant.
+Query: {query}
+Answer: {answer}
+
+Does the answer directly address the maternal health query?
+Answer only YES or NO.
+```
+
+`topic_relevance` prompts have no required placeholders.
+
+### Notes
+
+- New configs are created active. `is_active` can only be changed via `PATCH`.
+- Responds `200`, not `201`.
+
+### Errors
+
+- `400` — a config with the same validator, version and prompt text already exists.
+- `422` — the guardrails service rejected the body, e.g. an `answer_relevance_custom_llm` prompt missing `{query}`/`{answer}`.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/create_validator_config.md

@@ -0,0 +1,44 @@
+Register a validator configuration — a named, reusable validator setup that `POST /guardrails` applies by id.
+
+This is the object you point at from a guardrails run: create one here, then pass its `id` as a `validator_config_id` in the `config` array of `POST /guardrails`.
+
+### Request
+
+The body is a fixed set of base fields **plus** whatever tuning keys the chosen validator type accepts. Call `GET /guardrails` to discover the accepted keys per type.
+
+```json
+{
+  "name": "PII Redaction Input",
+  "type": "pii_remover",
+  "stage": "input",
+  "on_fail_action": "fix",
+  "is_enabled": true,
+  "entity_types": ["EMAIL_ADDRESS", "PHONE_NUMBER", "IN_AADHAAR"]
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | string | yes | 5–225 chars. |
+| `type` | enum | yes | One of the validator types from `GET /guardrails`. |
+| `stage` | enum | yes | `input` or `output`. |
+| `on_fail_action` | enum | no | `exception` \| `fix` \| `rephrase`. Defaults to `fix`. |
+| `is_enabled` | boolean | no | Defaults to `true`. |
+| *(extra keys)* | any | no | Validator-specific tuning, stored as the config blob. |
+
+In the example above, `entity_types` is a `pii_remover` tuning key — not part of the base schema, which is why it appears as an additional property rather than a named field.
+
+This endpoint forwards the body to the guardrails service unchanged; that service validates it. A tuning key or validator type newer than this documentation still works — check `GET /guardrails` for what your deployment accepts.
+
+### Notes
+
+- **Uniqueness is enforced on `name` alone**, scoped to the project. The same validator type may be registered many times under different names.
+- `stage` is advisory. `POST /guardrails` routes on the text it is actually given, not on this field, so one config can serve both directions.
+- Do **not** send `organization_id` or `project_id`. The tenant is derived from your authenticated context, and the guardrails service rejects those keys in the body.
+- Responds `200`, not `201`.
+
+### Errors
+
+- `400` — a validator config with this name already exists in the project.
+- `422` — the guardrails service rejected the body, or it contained `organization_id`/`project_id`.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/delete_ban_list.md

@@ -0,0 +1,12 @@
+Delete a ban list permanently. Restricted to the owning project.
+
+Validator configs that still reference the deleted list by `ban_list_id` are not cleaned up; they will fail when the guardrails service next tries to resolve the list.
+
+Responds `200` with a confirmation body rather than `204`.
+
+### Errors
+
+- `403` — the list belongs to another tenant.
+- `404` — no such ban list.
+- `422` — `ban_list_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/delete_llm_prompt_config.md

@@ -0,0 +1,11 @@
+Delete a stored LLM prompt config permanently, scoped to the calling project.
+
+Validator configs that still reference the deleted prompt will fail when the guardrails service next tries to resolve it. Repoint or remove them first.
+
+Responds `200` with a confirmation body rather than `204`.
+
+### Errors
+
+- `404` — no such config, or it belongs to another project.
+- `422` — `prompt_config_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/delete_validator_config.md

@@ -0,0 +1,11 @@
+Delete a validator config permanently, scoped to the calling project.
+
+Guardrails runs that still pass the deleted `validator_config_id` will no longer resolve it. Remove the id from your `POST /guardrails` calls first.
+
+Responds `200` with a confirmation body rather than `204`.
+
+### Errors
+
+- `404` — no such config, or it belongs to another project.
+- `422` — `config_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/get_ban_list.md

@@ -0,0 +1,10 @@
+Fetch a single ban list by id.
+
+Readable if the list belongs to the calling project, or if it belongs to another tenant and is marked `is_public`.
+
+### Errors
+
+- `403` — the list belongs to another tenant and is not public.
+- `404` — no such ban list.
+- `422` — `ban_list_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/get_guardrails_job.md

@@ -0,0 +1,28 @@
+Poll a guardrails job for its status and sanitised result.
+
+Use this when you submitted `POST /guardrails` without a `callback_url`, or to inspect a completed job for traceability. The job id comes from the `POST /guardrails` response.
+
+### Status values
+
+| `status` | Meaning |
+|---|---|
+| `PENDING` | Queued, not yet picked up. |
+| `PROCESSING` | A worker is applying the validators. |
+| `SUCCESS` | Finished; `guardrails_response` carries the sanitised text. |
+| `FAILED` | The text was hard-blocked, or the job errored. `error_message` explains why. |
+
+### Response
+
+`guardrails_response` is populated only on `SUCCESS`; it is `null` in every other state. The sanitised text sits at `guardrails_response.response.output.content.value`.
+
+`warnings` mirrors the `metadata.warnings` of the webhook payload, so polling callers do not miss a bypass signal — most importantly the case where the guardrails service was unavailable and the original text was returned unchanged. It is always empty for a hard-blocked job.
+
+### Notes
+
+- If the upstream response carried no sanitised text, the value falls back to the original submitted text.
+- `usage` counters default to zero when the guardrails service reports none.
+
+### Errors
+
+- `404` — no such job in this project, or the id belongs to a job that is not a guardrails job.
+- `422` — `job_id` is not a valid UUID.

backend/app/api/docs/guardrails/get_llm_prompt_config.md

@@ -0,0 +1,7 @@
+Fetch a single LLM prompt config by id, scoped to the calling project.
+
+### Errors
+
+- `404` — no such config, or it belongs to another project.
+- `422` — `prompt_config_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/get_validator_config.md

@@ -0,0 +1,9 @@
+Fetch a single validator config by id, scoped to the calling project.
+
+The response is the stored row flattened together with its validator-specific tuning config, so it carries keys beyond the declared schema — `id`, `organization_id`, `project_id`, `created_at`, `updated_at`, and every tuning key for that validator type.
+
+### Errors
+
+- `404` — no such config, or it belongs to another project.
+- `422` — `config_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/list_ban_lists.md

@@ -0,0 +1,16 @@
+List the ban lists visible to the calling project.
+
+Returns lists owned by the project plus any list from another tenant marked `is_public`. Ordered newest first.
+
+### Query parameters
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `domain` | string | no | — | Return only lists carrying this domain label. |
+| `offset` | integer | no | `0` | Rows to skip. Must be >= 0. |
+| `limit` | integer | no | — | Max rows to return, 1–100. Omit for no limit. |
+
+### Errors
+
+- `422` — `offset` is negative, or `limit` is outside 1–100.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/list_llm_prompt_configs.md

@@ -0,0 +1,14 @@
+List the stored LLM prompt configs belonging to the calling project, oldest first.
+
+### Query parameters
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `validator_name` | enum | no | — | `topic_relevance` or `answer_relevance_custom_llm`. |
+| `offset` | integer | no | `0` | Rows to skip. Must be >= 0. |
+| `limit` | integer | no | — | Max rows to return, 1–100. Omit for no limit. |
+
+### Errors
+
+- `422` — `validator_name` is not a recognised value, `offset` is negative, or `limit` is outside 1–100.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/list_validator_configs.md

@@ -0,0 +1,20 @@
+List the validator configs belonging to the calling project, oldest first.
+
+### Query parameters
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `ids` | UUID | no | — | Repeat the parameter to fetch several by id (`?ids=A&ids=B`). |
+| `stage` | enum | no | — | `input` or `output`. |
+| `type` | enum | no | — | A validator type from `GET /guardrails`. |
+
+This route is not paginated.
+
+### Response
+
+Each item is the stored row flattened together with its validator-specific tuning config, so entries carry keys beyond the declared schema — `id`, `organization_id`, `project_id`, `created_at`, `updated_at`, and every tuning key for that validator type.
+
+### Errors
+
+- `422` — a value in `ids` is not a valid UUID, or `stage`/`type` is not a recognised value.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.

backend/app/api/docs/guardrails/list_validator_types.md

@@ -0,0 +1,77 @@
+Lists every validator type the guardrails service can run, with the JSON Schema of the tuning keys each one accepts.
+
+Start here when you are setting guardrails up. This endpoint is the authority on what **your** deployment supports: if a type is listed you can configure it, and if it is missing that deployment does not have it yet — whatever other documentation says.
+
+<br>
+
+## Setting one up
+
+Two steps.
+
+**Step 1 — save a reusable config** with `POST /guardrails/validators/configs`. The body is the five shared fields, plus the tuning keys of the type you picked:
+
+```json
+{
+  "name": "PII Redaction Input",
+  "type": "pii_remover",
+  "stage": "input",
+  "on_fail_action": "fix",
+  "is_enabled": true,
+  "entity_types": ["EMAIL_ADDRESS", "PHONE_NUMBER", "IN_AADHAAR"]
+}
+```
+
+| Shared field | Required | What it means |
+|---|---|---|
+| `name` | yes | Your label for this setup, 5–225 characters, unique in the project. The same type can be saved many times under different names. |
+| `type` | yes | One of the types listed below. |
+| `stage` | yes | `input` checks the user's message, `output` checks the model's reply. Advisory only — a run checks whatever text you hand it. |
+| `on_fail_action` | no, defaults to `fix` | `fix` repairs the text where it can, `rephrase` returns a stand-in reply instead, `exception` fails the request outright. |
+| `is_enabled` | no, defaults to `true` | Whether this config is allowed to run. |
+
+The response carries an `id`. That id is what you use everywhere else.
+
+**Step 2 — run it** with `POST /guardrails`:
+
+```json
+{
+  "text": "Call me on 9876543210",
+  "config": [{"validator_config_id": "<id from step 1>"}]
+}
+```
+
+Guardrails compose: list several ids and they run in that order over the same message.
+
+<br>
+
+## One naming trap
+
+The schemas below describe each validator *as it runs*, so they spell the failure action `on_fail`. When you *save* a config in step 1, the same setting is called `on_fail_action`. Same three values, two names, depending on which endpoint you are talking to.
+
+<br>
+
+## What this endpoint returns
+
+The one guardrails route that is **not** wrapped in the usual `{"success": ..., "data": ...}` envelope. The body is a bare object:
+
+```json
+{
+  "validators": [
+    {
+      "type": "pii_remover",
+      "config": {"type": "object", "properties": {"entity_types": {"...": "..."}}}
+    }
+  ]
+}
+```
+
+Each `config` is generated from the service's own model, so it is always current — and a little noisy, carrying the `title`, `$defs` and `anyOf` wrappers that JSON Schema needs for optional fields. The reference below is that same information, trimmed and explained.
+
+<br>
+
+## Errors
+
+| Code | Meaning |
+|---|---|
+| `401` / `403` | Your API key is missing, invalid, or not allowed to use guardrails. |
+| `502` | The guardrails service is unreachable, or returned something that was not JSON. |

backend/app/api/docs/guardrails/update_ban_list.md

@@ -0,0 +1,22 @@
+Update a ban list. Fields you omit are left unchanged.
+
+`banned_words` is replaced wholesale, not merged — send the full list you want stored.
+
+### Request
+
+```json
+{
+  "description": "Updated description",
+  "banned_words": ["slur_a", "slur_b", "slur_c"]
+}
+```
+
+All five fields (`name`, `description`, `banned_words`, `domain`, `is_public`) are optional and follow the same constraints as on create.
+
+### Errors
+
+- `400` — the update collides with an existing ban list.
+- `403` — the list belongs to another tenant. Public lists are readable but not writable across tenants.
+- `404` — no such ban list.
+- `422` — the body failed validation, or `ban_list_id` is not a valid UUID.
+- `502` — the guardrails service is unreachable or returned a non-JSON body.