> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brussle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Define a judgment once on a namespace prefix, and every tenant under it has it.

A platform with one namespace per tenant usually wants the same judgments in every tenant. A template does that. You define the judgment once, on a namespace prefix, and every namespace under the prefix inherits it. That includes tenants created later. There are no per-tenant calls.

<Note>Templates are on the Team plan and above. Below it, creating, changing or activating a judgment, or creating or changing a subscription, on a prefix returns `plan_required`. After a downgrade takes effect, a template freezes: its tenants keep answering with its active version and its subscriptions keep sending events, and you can still read it, backfill it, delete its judgments and subscriptions and detach tenants, but you can't change it, and a write that would create a new namespace under it returns `plan_required`. See [plans](/pricing#plans).</Note>

## Create a judgment on a prefix

A template is a namespace path ending in `/*`. Create a judgment there exactly as you would on a namespace:

```text theme={"theme":{"light":"css-variables","dark":"css-variables"}}
POST /namespaces/acme%2Fprod%2F*/judgments
```

<CodeGroup>
  ```ts TypeScript theme={"theme":{"light":"css-variables","dark":"css-variables"}}
  await db.namespace("acme/prod/*").judgments.create({
    name: "needs_escalation",
    type: "bool",
    question: "Does this ticket require a human to take over from the automated flow?",
    context: { fields: ["state.subject", "state.body"] },
    engine: { name: "jev", version: "current" },
    freshness: { policy: "on_change" },
    thresholds: { escalate: 0.85 },
  });
  ```

  ```python Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
  db.namespace("acme/prod/*").judgments.create(
      name="needs_escalation",
      type="bool",
      question="Does this ticket require a human to take over from the automated flow?",
      context={"fields": ["state.subject", "state.body"]},
      engine={"name": "jev", "version": "current"},
      freshness={"policy": "on_change"},
      thresholds={"escalate": 0.85},
  )
  ```
</CodeGroup>

Send the `*` as it is and each `/` as `%2F`. The SDKs do this for you. The judgment routes work on the prefix path as on a namespace: create, list, get, `PATCH`, delete, activate, backfill, calibration, threshold recommendations, and recipe suggestions and tuning, which test smaller context recipes on the pooled outcomes. The [labelling queue](/guides/measure-improve-tune#label-a-random-sample) works per namespace: preview, draw and label on each tenant's path. A prefix path returns `invalid_request`.

Every namespace under `acme/prod/` now has `needs_escalation`. A tenant's judgment list and get include it, marked with the template it comes from:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
{
  "name": "needs_escalation",
  "active_version": 1,
  "freshness": {"policy": "on_change", "debounce_ms": 0},
  "thresholds": {"escalate": 0.85},
  "outcomes": {},
  "template": "acme/prod/*",
  "overrides": []
}
```

The get's `versions`, every version with its definition, is left out of the example.

## Which template a namespace follows

* **The most specific prefix wins.** Templates do not nest. With templates on `acme/*` and `acme/prod/*`, the namespace `acme/prod/tenant_123` inherits only the judgments of `acme/prod/*`. That stays true even if every judgment on `acme/prod/*` is deactivated.
* **A namespace's own judgment wins.** If a namespace already has a judgment with the template judgment's name, it keeps its own, and does not inherit that one.

`GET /templates` lists your organization's templates, 100 per page, with an optional `prefix`. It is `db.templates.list()` in both SDKs. A template stays listed after its judgments are deactivated. `GET /namespaces` does not list templates. To list the namespaces a template reaches, use `GET /namespaces?prefix=acme/prod/`.

## New and existing tenants

A namespace created after the template's first version is judged in full, from its first write.

A namespace that already existed when you added the template judgment is treated as if you had just created the judgment there. For an `on_change` judgment, documents written from then on are judged, and existing documents wait for a backfill you confirm, because nothing is backfilled without an estimate.

A backfill on the prefix path covers every tenant:

* Without `confirm`, the estimate covers every namespace that follows the template's judgment. It counts up to 100 of them, spread evenly by name, and scales that to all of them, so it can be off when tenant sizes vary a lot. Each namespace's counts are reused for 5 minutes, so an estimate can miss the last few minutes of writes.
* With `"confirm": true`, one job runs the namespaces one at a time. Each stays within its own budget. A namespace whose budget is paused is skipped and its answers stay `stale`, so it does not hold up the rest.

## Change the question for every tenant

Create a new version on the prefix path, then activate it there. You get one [shadow report](/guides/measure-improve-tune#change-a-question-safely-with-a-shadow-report), sampled across the tenants, and the job's `namespace` is the prefix. Confirming it switches every tenant. `force: true` skips the report, as on a namespace.

Tenants always follow the template's active version.

## Tenant overrides

A tenant may override two settings of an inherited judgment: its thresholds and its freshness policy. Use the usual `PATCH` on the tenant's own path:

<CodeGroup>
  ```ts TypeScript theme={"theme":{"light":"css-variables","dark":"css-variables"}}
  await db.namespace("acme/prod/tenant_123").judgments.update("needs_escalation", { thresholds: { escalate: 0.7 } });
  ```

  ```python Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
  db.namespace("acme/prod/tenant_123").judgments.update("needs_escalation", thresholds={"escalate": 0.7})
  ```
</CodeGroup>

* An override replaces the whole object. A thresholds override replaces the template's whole set, as any threshold `PATCH` does. A freshness override is the whole freshness setting: once a tenant overrides freshness, a later template change to its debounce does not reach that tenant.
* A `PATCH` on the prefix path changes the settings of every tenant that has no override of them.

## Detach

A tenant that needs more than an override can detach the judgment:

```text theme={"theme":{"light":"css-variables","dark":"css-variables"}}
POST /namespaces/acme%2Fprod%2Ftenant_123/judgments/needs_escalation/detach
```

It is `ns.judgments.detach(name)` in both SDKs. The judgment becomes the tenant's own copy, and it stops following the template.

* It keeps the template's version numbers, up to and including the active version, which stays active.
* It keeps the tenant's effective thresholds and freshness, override or inherited.
* It keeps its answers and evaluations. Nothing is judged again.
* It drops the template's pooled calibration. Its answers have no `calibrated` object until its own nightly fit on the tenant's outcomes. To give a tenant calibration of its own without leaving the template, use [its own fit](#each-tenant-grows-its-own-fit-scale) instead.

Detaching a judgment the namespace already owns changes nothing, so a retry is safe.

## Subscriptions for every tenant

A [subscription](/concepts/subscriptions) created on the prefix path applies to every tenant under it, including tenants created later, with the same rules for which template a tenant follows:

<CodeGroup>
  ```ts TypeScript theme={"theme":{"light":"css-variables","dark":"css-variables"}}
  await db.namespace("acme/prod/*").subscriptions.create({
    name: "escalations",
    filters: ["answers.needs_escalation.thresholds.escalate", "Eq", true],
    events: ["entered", "exited"],
    endpoint: endpoint.id,
  });
  ```

  ```python Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
  db.namespace("acme/prod/*").subscriptions.create(
      name="escalations",
      filters=("answers.needs_escalation.thresholds.escalate", "Eq", True),
      events=["entered", "exited"],
      endpoint=endpoint["id"],
  )
  ```
</CodeGroup>

* **Per tenant.** Each tenant keeps its own set of matching documents, and each event names the tenant in `namespace` and the prefix in `subscription.defined_on`. A tenant starts evaluating it at its next change, so idle tenants cost nothing; until then it reads `syncing` there.
* **Listed with `template`.** A tenant's subscription list and get include it, marked with the template, and show its `status` in that tenant. On the prefix path, `status`, `live_at` and `lag_ms` are null.
* **Managed on the prefix.** Change and delete it on the prefix path; a tenant gets `409 conflict`. Its query runs on a tenant's path, over that tenant's documents.
* **Its endpoint** must cover the whole prefix: an endpoint scoped to `acme/prod/` or wider, not one tenant.
* **The limit.** A tenant creates a subscription only while it has fewer than 100, counting its template's. Creating one on the prefix checks the template's own count, so subscriptions the template gains later can take a tenant past 100.
* **Plans.** Creating and changing one on a prefix needs the Team plan, like any template change. After a downgrade, existing ones keep sending events, deleting one works on any plan, and a new tenant under the frozen template returns `plan_required`.

## What a tenant cannot do

On an inherited judgment, these return `409 conflict`:

* Creating a judgment with the inherited name.
* Activating a version. The tenant follows the template's active version.
* Deleting it. Detach it first.
* Changing or deleting an inherited subscription. Subscriptions can't be detached, and creating one with an inherited subscription's name is `invalid_request`.

Detach, the labelling queue, a subscription's query, suggested parts, outcomes, documents, queries and writes take a namespace, never a prefix.

## Calibration across tenants

Tenants post [outcomes](/guides/measure-improve-tune#post-labelled-examples) on their own namespace paths. Calibration on the prefix pools every tenant's outcomes into one fit per template version and engine epoch, refitted nightly. A tenant without a fit of its own reads that pooled fit, so a tenant created today is calibrated from its first answer. Tenants under a [non-production prefix](/guides/staging-environments#what-it-changes), such as `acme/staging/`, are left out of the pool unless the template is under that prefix too.

### Each tenant grows its own fit (Scale)

A tenant's data can differ from the pool's: another language, a stricter review team, a different base rate. On the Scale plan, a tenant with enough outcomes of its own in an epoch, 100 with 20 of each kind, also gets its own fit, weighted more heavily as its own outcomes grow (the report shows `weight`). Below 100 it reads the pool.

A tenant's own fit is used only when it clearly beats the pool on that tenant's held-out outcomes. The tenant keeps what it would read otherwise (the pooled fit, or raw where the pool does not beat raw) until then.

The template's nightly fit makes every tenant's fit in the same run, and tenants keep following the template: a new version starts every tenant on that version's pool again, and there is nothing to detach. Composite judgments keep one pooled combiner for every tenant.

Below Scale, every tenant reads the pooled fit. After a downgrade takes effect, the next nightly fit leaves every tenant on the pool again; an upgrade gives tenants their own fits at the next one.

### Reports

The calibration report and threshold recommendations on the prefix path use the pooled outcomes. On a tenant's path they use that tenant's outcomes, and each epoch's `tenant` says what the tenant reads:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
{
  "tenant": {
    "applied": "tenant_shrunk",
    "reason": "tenant_better",
    "message": "This tenant's own fit, blended with the template's pool, did best on its held-out outcomes, and clearly better than the pool, so its answers read it.",
    "outcomes": 3000,
    "weight": 0.968,
    "held_out": {"raw_log_loss": 0.61, "pooled_log_loss": 0.55, "tenant_log_loss": 0.42}
  }
}
```

`applied` is `tenant_shrunk` (the tenant's own fit, blended with the pool's), `pooled` or `raw`. `weight` is how much the tenant's own fit counts, rising with its outcomes. `reason` is `tenant_better`, `pooled_better` or `raw_better` once the tenant has its own fit; `too_few_outcomes`, `awaiting_fit` (the next nightly fit makes one) or `plan_required` before. It is `non_production` for a tenant under a [non-production prefix](/guides/staging-environments#mark-the-prefix-non-production), which reads the pool but adds nothing to it. The epoch's `stage`, `held_out`, `not_fitted` and `calibrated` then describe the fit the tenant reads, measured on its own outcomes.

On the prefix path, each epoch's `tenants` counts the tenants with outcomes in it, and how many read their own fit, the pool, or raw.

## What stays per tenant

Answers, evaluations, budgets and billing stay with each tenant's namespace. The limit of 100 active judgments counts a namespace's own judgments only. A template has its own limit of 100.

## In the dashboard

* The **Templates** page lists your templates and each template's tenants.
* A tenant's judgment shows the template it comes from, and marks the settings the tenant overrides.
* **Detach** asks you to confirm before it runs.
* A tenant's **Calibration** tab says, per epoch, whether it reads its own fit or the pool, and how much its own outcomes weigh. A template's says how many tenants read their own fit. Below Scale, both say that every tenant reads the pool, with an upgrade for owners.
* Below Team, the **Templates** page and each template say what templates do and that yours are frozen, with an upgrade for owners. A frozen template's page still offers backfill; its new versions, activation and settings wait for an upgrade.


## Related topics

- [List templates](/api-reference/judgments/list-templates.md)
- [Detach an inherited judgment from its template](/api-reference/judgments/detach-an-inherited-judgment-from-its-template.md)
- [Publish a tenant document per namespace under a template](/api-reference/groups/publish-a-tenant-document-per-namespace-under-a-template.md)
- [Subscriptions](/concepts/subscriptions.md)
- [Report on groups of documents](/guides/groups.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.