Skip to main content
POST
Author a candidate workflow without running it (stateless · source-only)

Authorizations

Authorization
string
header
required

Exactly one Authorization: Bearer value from the token file

Body

application/json

Generation 1 of the compile request. The encoded body is limited by the listener's configured HTTP body ceiling; no smaller field-size or answer-count quota is imposed. Unknown fields, a present null, duplicate keys (including inside answers) and positional arrays are refused. No field names a host path: an EDIT base travels inline in source.

compile_version
integer
required
mode
enum<string>
required

create requires intent and forbids source/change; edit requires source and change and forbids intent

Available options:
create,
edit
answers
object

Question key → one JSON literal with its type preserved, judged exactly as sent within the HTTP body envelope.

change
object
cognition
string

The only authoring cognition of this build. Any other value is refused; no authoring model is contacted

Allowed value: "deterministicOnly"
intent
string
source
string

Accepted .nika source, inline. The caller owns source selection, revision checks and materialization

workflow_id
string

Names a created workflow. On edit the core refuses it as data: an edit cannot rename its accepted base

Response

Authoring outcome — ready, incomplete and refused are all data

The engine-owned machine document of one authoring result — the document nika compile --json prints, without the CLI-only written. No field grants authority, writes or executes source.

candidate
string | null
required

Ordinary .nika source. It is proposed only when status is ready; under any other status it is never proposed. Under incomplete it is a preview: it may still carry unfilled holes, or, when an applied diagnostic targets verify_held, it is a candidate the verifier held: it answered on these bytes against the request and did not accept them. A preview is not to be run or saved as an accepted result. Null when no candidate is shown, a withdrawn one included.

check_preview
object | null
required

The engine's pure Check report over the source only. No child file, skill, credential probe, access plan or admission was evaluated

compile_version
integer
required
diagnostics
object[]
required

Findings, in order. kind and target are their machine-readable part; message is for a reader. target names what a finding concerns: a question key, a task, a source field, or one of the compiler's own targets, among them semantic_verification, a finding on the request against the candidate's bytes (a clause or the whole request that no admitted judgment of these bytes settled, a part a verifier judged missing with its reason, a part it left unsettled or contested, a verification stopped at a judge call that got no answer); verify_held (kind applied), the candidate is held: the verifier answered on these bytes against the request and did not accept them (it rejected them or abstained), so candidate is a preview only, no replayable round is kept, and that verifier is not asked about the same bytes again in this round; and verify_resume (kind applied), no admitted judgment of the candidate was made (the verifier's call failed or chose no offered answer): the candidate is withdrawn and the round's record kept, and a zero-call replay of that round asks no verifier. Each verification attempt is recorded in provenance.decision.semantic_verification.

provenance
object
required

Reproduction metadata; neither program identity nor run evidence

questions
object[]
required
requested_boundary
object | null
required

The candidate's requested permits, derived by Check. Requested, never granted

requested_trigger
object | null
required

The trigger the request names (kind · source_hint · event_hint · cadence · at · payload_input · status · timezone · missed · overlap · ceiling · cron), stated beside the candidate whose bytes carry no cadence, host or event. A requirement the operator binds through the schedule contract, never a grant or a schedule row. timezone, missed, overlap and ceiling are the answered binding values (null until answered). cron is the exact five-field schedule projection when supported and fully specified, otherwise null; older engines omit it. It never supplies a missing time or timezone.

status
enum<string>
required

Completeness of authoring, never permission to execute

Available options:
ready,
incomplete,
refused