Create a judgment, or a new version of an existing name
Posting a name that exists creates version n+1; versions are
immutable. The first version of a name is active on creation; a later
version is inactive until activated, unless activate: true, which
implies force and skips the shadow report.
Freshness settings belong to the judgment, not the version:
freshness sets them with the name’s first version. A later version
keeps the judgment’s settings, and warnings says so when the
freshness sent differs from them. Change them with PATCH, which
asks for confirm before a switch to on_change.
Thresholds are a setting of the judgment, not part of the version. Thresholds given here replace the judgment’s thresholds when
this version becomes active, because they are written for its type; a
version created without them keeps the current thresholds. After that,
change them with PATCH.
On a prefix path (acme%2Fprod%2F*) this creates a template that every
namespace under the prefix inherits. A namespace cannot create a
judgment with the name of one it inherits (conflict). Templates need
the Team plan or above: on a prefix path, creating a version, PATCH
and activating are plan_required below it, while reading, backfill,
delete and detach work on every plan.
A composite judgment (a bool with parts) is never active on
creation, not even as the first version, and activate: true is
invalid_request for one: it cannot answer until its combiner is
fitted on your labels by the shadow job that activation starts.
An entity judgment has context.related.
Creating a version of one on a judgment whose policy will be
on_change needs confirm: true. Without it, the response is 200
with the replay estimate of its monthly cost, and nothing is created. A confirmed request whose estimate is more than the
namespace’s budget is budget_exceeded. When the version
joins on attributes with no reference index yet, job_ids names the
reference_index job that builds each one, and job_id the first.
A ninth reference index in a namespace is
invalid_request, and details.reference_indexes names the current
ones.
A relation that reads a referenced document joins with
{theirs: "id", mine: "attributes.<name>"}. It needs a reference
index on the judged documents’ mine attribute, built by a
reference_index job like any other and counted toward the same 8.
Its replay estimate cannot count fan-out, so it has
excludes: ["fanout"] and lower_bound: true, and without confirm
the response’s fanout shows the rolling limit the confirm sets. A
join on two different attributes is invalid_request, and
warnings names a relation that renders a referenced document’s
updated_at, which changes on every write to it.
A blocking relation joins on one key attribute
on both sides, and a choice can choose among it with
options.from; context.previous reads the document as the
judgment last saw it. A judgment with a blocking relation needs
confirm like one with a referenced relation, and a key value over
block_cap at create is invalid_request naming it in
details.key.
A definition needs a context recipe. Leaving out
context is invalid_request, and details.suggested_context is a
recipe suggested from up to 100 of the namespace’s documents, with
its cost per answer beside the whole state’s (null when there are
no documents). Send it back as context, or use_context: "suggested" to create with it, or use_context: "whole_state" to
send the whole state.
A starter (GET /starters) is created with
from_starter and paths: the server fills the starter’s
placeholders with your paths and validates the result like any
definition. The 201 carries definition, exactly what was
created, and for a starter with a suggested outcome setting,
outcomes: applied with the name’s first version, its rules only on
a plan with outcome rules.
dry_run: true validates the body as a create would and returns the
definition with its cost per answer and backfill estimate (200);
nothing is created.
Authorizations
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
One key per logical request, reused only on its retries. A key
belongs to one request: within your organization, the same method,
path, query and body. For 24 hours after a successful response, a
request with the key and the same body gets that response back
verbatim, with Idempotent-Replayed: true, and runs nothing. Only a
successful response is kept, so the retry of a request that failed
runs again. While the first request runs or its response is kept,
the key with a different request is idempotency_key_reused (422).
A request sent while one with its key is still running is
rate_limited with Retry-After: 1, without running: retry it to
get the first one's response. In the rare case the key can't be
checked, the request runs as if it had none.
1 - 255Path Parameters
A namespace name, or a template prefix ending in /*, 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. Up to 256 bytes. Never exactly
. or .., which a URL path can't carry.
1 - 256^(?!\.\.?$)[A-Za-z0-9._:/-]+(/\*)?$Body
- Option 1
- Option 2
- Option 3
- Option 4
A definition, or a starter filled with your paths.
A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..
1 - 128^[A-Za-z0-9_-]+$1What the engine sees. A create without it is refused with a suggested
recipe, unless use_context asks for the suggestion or the whole
state; a version with no recipe sends the whole
state, subject to the engine limit.
Must be active in the registry. May be omitted only when the namespace has a default_engine.
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.
^(0|[1-9][0-9]*)[smhd]$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.
Each threshold is true when p is at least the value.
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. With features, one part is enough.
1 - 8 elementsComposite 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. Features are scaled automatically beside the parts; a
missing value counts as typical. Features add no questions, so
they are never billed.
1 - 8 elementsAn aggregate the recipe declares, as
<relation>.count or <relation>.<sum|min|max|latest>(<path>), such
as tickets.count or invoices.sum(state.amount).
^[A-Za-z0-9_-]+\.(count|(sum|min|max|latest)\((state|attributes)(\.[^.()]+)+\))$Settings, not part of the definition. Changing them creates no version.
Activate this version on creation. In v1 this implies force. Refused for a composite judgment, which activation fits on your labels first.
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; for a judgment that can fan out it also carries
fanout, the rolling limit the confirm sets. Ignored for other
judgments.
Instead of context: suggested creates with the
recipe suggested from a sample of the namespace's documents, the
one a create without context returns in
details.suggested_context; whole_state sends the whole
state, with a warning. Refused together with context.
suggested, whole_state Validate the body as a create would, and return the definition with
its cost per answer and backfill estimate, creating nothing
(CreateJudgmentDryRun).
Response
Nothing was created: a dry run (dry_run: true), or an entity
judgment that needs confirm and was not confirmed, whose replay
estimate this is.
- Option 1
- Option 2
What a create would make, and what it would cost. Nothing was created, written or billed.
The answer has p. With parts it is a composite judgment:
the engine is asked each part instead of question, and p combines
the parts' answers with weights fitted on the judgment's outcomes.
- Option 1
- Option 2
- Option 3
Mean judgments per answer over sampled_documents of the
documents the definition applies to, each counted by its size
class as a backfill estimate counts them: 1 when every answer is
standard, 4 when every one is large. Null when there is nothing
to sample, and on a template's prefix path.
x >= 0x >= 0What backfilling every document the definition applies to would cost once it exists. Creating never backfills by itself. Null on a template's prefix path.
An entity judgment's monthly replay estimate, whatever its policy; null for others.
For a starter with a suggested outcome setting, what the create would apply; null otherwise.