Skip to main content
POST
Start a job in awaiting_confirm

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

id
string
required
Minimum string length: 1

Response

The job.

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. A fanout job (entities, E3a) re-judges the judged documents one referenced change touches (§6.9): referenced names the change and estimate its cost. It waits in awaiting_confirm unless the judgment's fanout.confirm_jobs is false. confirm is budget_exceeded when the estimate does not fit what is left of the namespace's budget, and cancel leaves the in-scope answers stale.

id
string
required
type
enum<string>
required
Available options:
backfill,
shadow,
periodic,
namespace_delete,
reference_index,
fanout
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

Entities, E3a (§6.9). fanout jobs only; null for other jobs.

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.