Skip to main content
POST
Simulate a change to a referenced document

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

The namespace name, with any / sent as %2F. Up to 256 bytes. / separates levels of the hierarchy, as in acme/prod/tenant_123.

Required string length: 1 - 256
Pattern: ^[A-Za-z0-9._:/-]+$
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_-]+$

Body

application/json

Relations (§6.5.2). A proposed body for a referenced document.

relation
string
required

A relation of the judgment that reads a referenced document.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
document
object
required

The proposed document, as an upsert would write it. id names the referenced document.

sample
integer
default:200

Judged documents to evaluate both ways.

Required range: 1 <= x <= 1000

Response

The simulation job. Its simulation fills in when it is done.

A job row (§7.10.5). A shadow job comes from activating a differing version without force (§6.9). It starts in awaiting_confirm and runs its sample while it waits; report fills in when the sample is done. confirm activates version and the job ends done; cancel leaves the active version unchanged. On a template prefix, namespace is the prefix. A reference_index job (entities, E1) builds the index an entity judgment's relations need (§6.5.2); it starts running, and attribute names the attribute it indexes. An evaluation_export job (§9 Plans) starts running, counts evaluations written in progress.documents_done, never spends, and has export.

From relations: a resync job re-renders the readers of a changed threshold (resync) and touches the parents whose rendering flipped; a group_build job computes a new group's or aggregate's first aggregates with no fan-out (group); a discover job fills in proposal (§6.5.4); a simulation job fills in simulation (§6.5.2). Each starts running; discover and simulation never spend. E3a's fanout jobs are retired: none is created, and a server may still return an old one until it stops.

id
string
required
type
enum<string>
required
Available options:
backfill,
shadow,
periodic,
namespace_delete,
reference_index,
fanout,
evaluation_export,
resync,
group_build,
discover,
simulation
status
enum<string>
required
Available options:
estimating,
awaiting_confirm,
running,
paused,
done,
failed,
cancelled
namespace
string
required

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._:/-]+(/\*)?$
spend_usd
number
required

Judging billed by this job so far, in US dollars.

Required range: x >= 0
progress
object
required
created_at
string<date-time>
required

RFC 3339, UTC.

updated_at
string<date-time>
required

RFC 3339, UTC.

judgment
string

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_-]+$
estimate
object | null
estimated_completion_at
string<date-time> | null

RFC 3339, UTC.

error
string | null
attribute
string | null

Entities, E1 (§6.5.2). reference_index jobs only, as attributes.<name>. The attribute whose reference index the job builds. Null for other jobs.

Pattern: ^attributes\.[A-Za-z0-9_-]+$
referenced
object | null
deprecated

Retired with E3a's fanout jobs; null.

resync
object

Relations. resync jobs only.

group
string

Relations. group_build jobs only, the group whose aggregates it computes.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
proposal
object | null

Relations. discover jobs only; null until done.

simulation
object | null

Relations. simulation jobs only; null until done.

version
integer<int32>

Shadow jobs only. The version being activated.

Required range: x >= 1
report
object

Shadow jobs only. Null while the sample runs; progress counts the sampled documents. A composite version's job has a CompositeShadowReport (§6.5.1), and when it has too few labels it fails with an error that starts with insufficient_labels.

export
object

evaluation_export jobs only (§9 Plans): the range, the evaluations written, and once done the download links.