Skip to main content
POST
Create a judgment, or a new version of an existing name

Authorizations

​
Authorization
string
header
required

An organization API key. Keys carry a role (read_write or read_only) and may be restricted to a namespace prefix such as acme/*, or to one namespace such as acme/prod/tenant_1. A prefix matches on a / boundary: acme/prod/tenant_1* covers acme/prod/tenant_1 and everything under acme/prod/tenant_1/, never acme/prod/tenant_12.

Headers

​
Idempotency-Key
string

Returns the original response verbatim while the node still caches it. Correctness never depends on it.

Minimum string length: 1

Path Parameters

​
ns
string
required

A namespace name, or a template prefix ending in /* (§7.7), with any / sent as %2F: acme%2Fprod%2Ftenant_123 or acme%2Fprod%2F*.

A namespace name, or a template prefix: a namespace path ending in /*, such as acme/prod/*, which every namespace under acme/prod/ inherits judgments from (§7.7). Up to 256 bytes.

Required string length: 1 - 256
Pattern: ^[A-Za-z0-9._:/-]+(/\*)?$

Body

application/json

A definition plus its initial freshness settings.

​
name
string
required

A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
​
question
string
required
Minimum string length: 1
​
type
any
required
​
criteria
string
​
context
object

What the engine sees. Omitting it sends the whole state, subject to the engine limit; allowed but not recommended.

​
engine
object

Must be active in the registry. May be omitted only when the namespace has a default_engine.

​
horizon
string
default:0s

How far before observed_at an outcome's prediction was made, such as 30d for "churned within 30 days". Part of the definition, so changing it creates a version. Defaults to 0s, which joins labelled examples to current answers.

Pattern: ^(0|[1-9][0-9]*)[smhd]$
​
applies_to
object

Entities, E1 (§6.5). The judgment judges, answers and bills only documents whose attributes match. A document that does not match has no answer for it: answers omits it. Part of the definition, so changing it creates a version.

​
thresholds
object

Each threshold is true when p is at least the value.

​
parts
object[]

Composite judgments only: 2 to 8 narrow yes/no questions with names unique within the judgment. They share the judgment's context recipe and engine, so they go in one engine request with its other questions, and each counts toward the 32 questions per request. question then documents what the combination means and is not sent to the engine. Parts are part of the version. They cannot reference other judgments. Each part is billed as a judgment (§9). With features, one part is enough.

Required array length: 1 - 8 elements
​
features
string[]

Entities, E1 (§6.5.1). Composite judgments only: aggregates over related documents that the combiner takes as numeric inputs beside the parts. Each names an aggregate the recipe's related declares. The combiner takes sign(x) × ln(1 + |x|) of each value and standardises it with the parts' log-odds; a missing value counts as the feature's mean. Features add no questions, so they add no judgment units.

Required array length: 1 - 8 elements

Entities, E1 (§6.5.1). An aggregate the recipe declares, as <relation>.count or <relation>.<sum|min|max|latest>(<path>), such as tickets.count or invoices.sum(state.amount).

Pattern: ^[A-Za-z0-9_-]+\.(count|(sum|min|max|latest)\((state|attributes)(\.[^.()]+)+\))$
​
freshness
object

Settings, not part of the definition. Changing them creates no version.

​
activate
boolean

Activate this version on creation. In v1 this implies force. Refused for a composite judgment, which activation fits on your labels first (§6.5.1).

​
confirm
boolean
default:false

Entities, E1 (§6.9). Required to create a version with context.related on a judgment whose policy will be on_change. Without it, the response is the replay estimate of the monthly cost, and nothing is created. Ignored for other judgments.

Response

An entity judgment that needs confirm was not confirmed. Nothing was created; this is its replay estimate.

Entities, E1 (§6.9). An unconfirmed create of an entity judgment that runs on_change. Nothing was created.

​
replay
object
required

Entities, E1 (§6.9). What an entity judgment would cost a month, from the namespace's last 30 days of writes run through its touch, debounce and ceiling rules. Storage keeps each document's newest version, so the replay sees each related document's creation, its newest write and the deletes still recorded: exact for documents written once, the last edit only for documents edited many times, when the figures are a lower bound (lower_bound). It does not credit dedup, which only lowers the bill.