> ## Documentation Index > Fetch the complete documentation index at: https://docs.nika.sh/llms.txt > Use this file to discover all available pages before exploring further. # Admit a workflow as a durable job — by served name, or as immutable snapshot bytes > Two forms, one admission (ADR-131). `{"workflow": ""}` names a workflow the served registry lists: the resident captures its world through ExecutionService, exactly as a schedule does. Optional `access` on that form is CLI `--access` for this job only. A snapshot body is the world `nika check --json --sdk-snapshot` prints, decoded and readmitted through the same ExecutionService; its digests are optional caller-supplied integrity digests (a content assertion, never a signature). Snapshot jobs inherit the resident's unpinned plan. The server never interprets a caller filesystem path. Idempotency binds to the exact request bytes. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/jobs openapi: 3.1.0 info: description: >- Authenticated loopback remote execution and declarative schedules. Artifacts, schedule list/delete/trigger/backfill, /v1/arm, and POST /v1/run are absent. title: nika serve version: 0.120.0 servers: - url: http://127.0.0.1 security: - bearerAuth: [] paths: /v1/jobs: post: summary: >- Admit a workflow as a durable job — by served name, or as immutable snapshot bytes description: >- Two forms, one admission (ADR-131). `{"workflow": ""}` names a workflow the served registry lists: the resident captures its world through ExecutionService, exactly as a schedule does. Optional `access` on that form is CLI `--access` for this job only. A snapshot body is the world `nika check --json --sdk-snapshot` prints, decoded and readmitted through the same ExecutionService; its digests are optional caller-supplied integrity digests (a content assertion, never a signature). Snapshot jobs inherit the resident's unpinned plan. The server never interprets a caller filesystem path. Idempotency binds to the exact request bytes. parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/JobByName' - $ref: '#/components/schemas/ExecutionSnapshot' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Job' description: Idempotent replay '202': content: application/json: schema: $ref: '#/components/schemas/Job' description: Created '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Invalid idempotency key '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Error envelope '408': content: application/json: schema: $ref: '#/components/schemas/Error' description: Request deadline '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: Idempotency key already bound to another request '413': content: application/json: schema: $ref: '#/components/schemas/Error' description: Encoded body or decoded snapshot resource limit '415': content: application/json: schema: $ref: '#/components/schemas/Error' description: Content-Type or Content-Encoding refused '422': content: application/json: schema: $ref: '#/components/schemas/Error' description: Malformed, unsupported, tampered, or semantically refused snapshot '503': content: application/json: schema: $ref: '#/components/schemas/Error' description: Execution queue or durable store unavailable '507': content: application/json: schema: $ref: '#/components/schemas/Error' description: Durable job capacity exhausted components: parameters: IdempotencyKey: in: header name: Idempotency-Key required: true schema: maxLength: 255 minLength: 1 type: string schemas: JobByName: additionalProperties: false description: >- The by-name form (ADR-131): a workflow the served registry lists (GET /v1/workflows · project-root-relative, `.nika`). The resident captures its world exactly as a schedule does — the one owner of the snapshot and its digest domain. Idempotency binds to these request bytes. Optional `access` is the same pin as CLI `--access` (a pin is a pin). Absent: the resident's unpinned plan. Snapshot bodies reject both access and inputs overlays, including null or empty maps. Optional inputs are literal JSON values checked against declared keys, types and required values before a job exists; strings are never CLI @env instructions or expressions. properties: access: description: >- Access pin, same vocabulary as `--access` (class or harness id). A pin never silently substitutes a metered seat. maxLength: 64 minLength: 1 type: string inputs: additionalProperties: true description: >- Literal JSON overrides for declared workflow inputs. Unknown keys, wrong types and missing required values refuse with 422; defaults remain authored. A present null is refused. Inputs bind exact request identity and survive durable queue recovery; workflow bytes are unchanged. type: object workflow: maxLength: 4096 minLength: 1 type: string required: - workflow type: object ExecutionSnapshot: additionalProperties: false description: >- Immutable byte-owned execution world — the body `nika check --json --sdk-snapshot` prints (the engine is the one producer; a client never hashes). Unit bytes are canonical lowercase hexadecimal. `digest` and every unit `digest` are OPTIONAL caller-supplied integrity digests (canonical lowercase SHA-256 · a content assertion, never a signature): absent, the resident computes them and the receipt carries the result; present, they must match the bytes or the request is refused as `snapshot_tampered`. The decoded unit aggregate is limited to 16 MiB and the complete encoded request to 33 MiB. This object is the request body itself, not a path-bearing wrapper. properties: digest: description: >- Optional caller-supplied integrity digest of the world (never a signature) pattern: ^[0-9a-f]{64}$ type: string format_version: const: 1 type: integer root: maxLength: 4096 minLength: 1 type: string units: items: additionalProperties: false properties: bytes_hex: pattern: ^(?:[0-9a-f]{2})*$ type: string digest: description: >- Optional caller-supplied integrity digest of the unit (never a signature) pattern: ^[0-9a-f]{64}$ type: string kind: description: >- 0 root (the admitted workflow) · 1 child (a transitively invoked workflow) · 2 skill (an Agent Skill document) · 3 import (an opaque import the caller supplied) maximum: 3 minimum: 0 type: integer path: maxLength: 4096 minLength: 1 type: string required: - path - kind - bytes_hex type: object maxItems: 256 type: array required: - format_version - root - units type: object Job: additionalProperties: false properties: error: additionalProperties: false properties: code: type: string message: type: string required: - code - message type: object evidence: $ref: '#/components/schemas/JournalEvidence' execution_id: type: string id: format: uuid type: string outputs: additionalProperties: true description: >- Declared workflow outputs; present only after settlement when supplied by the execution adapter type: object receipt: $ref: '#/components/schemas/JobReceipt' settlement: $ref: '#/components/schemas/RunSettlement' status: $ref: '#/components/schemas/JobStatus' trace_id: type: string required: - id - status type: object Error: additionalProperties: false properties: error: additionalProperties: false properties: code: type: string message: type: string required: - code - message type: object required: - error type: object JournalEvidence: additionalProperties: false description: >- Reported journal delivery loss, independent of execution status. The reason classifies the mirror's first error without exposing OS text or paths. Absence is not a claim that a journal exists. properties: reason: enum: - write_failed - record_refused type: string status: const: mirror_lost type: string required: - status - reason type: object JobReceipt: additionalProperties: false description: Terminal binding to the exact immutable admitted execution properties: chain_head: minLength: 1 type: string execution_id: minLength: 1 type: string job_id: format: uuid type: string origin: $ref: '#/components/schemas/JobOrigin' snapshot_digest: pattern: ^[0-9a-f]{64}$ type: string trace_id: minLength: 1 type: string required: - job_id - execution_id - trace_id - snapshot_digest type: object RunSettlement: additionalProperties: false description: >- The run's settlement (ADR-128), built once by the runtime and projected whole: the state word every door speaks, why, the elapsed time on the kernel clock, the task tally, the spend with its qualifier, the failure named. Unknown cost is never zero: `total_cost_usd` is absent when nothing was metered. Present on the terminal event and durable job response of a job whose runtime settled; absent when the resident lost the execution (interrupted) or refused it before any task. Reattachment and idempotent admission replay project the same hash-bound terminal event, never a new settlement. properties: cause: enum: - normal - human_gate - task_failed - output_contract - budget - operator - refused type: string elapsed_ms: minimum: 0 type: integer error: additionalProperties: false properties: code: type: string message: type: string task: description: The task that failed · absent for a run-level cause type: string required: - code - message type: object spend: additionalProperties: false properties: by_source: additionalProperties: type: number type: object priced_calls: minimum: 0 type: integer pricing_as_of: type: string qualifier: enum: - priced - partially_priced - unpriced - unmetered type: string total_cost_usd: description: Present only when at least one leaf metered real spend minimum: 0 type: number unpriced_calls: minimum: 0 type: integer required: - priced_calls - unpriced_calls - qualifier type: object status: enum: - succeeded - failed - paused - cancelled type: string tasks: additionalProperties: false properties: cancelled: minimum: 0 type: integer failed: minimum: 0 type: integer never_started: description: >- Cancelled at the boundary without ever starting (counted in `cancelled` too) minimum: 0 type: integer ok: description: A recovered task IS a success (counted here too) minimum: 0 type: integer recovered: minimum: 0 type: integer skipped: minimum: 0 type: integer total: minimum: 0 type: integer required: - total - ok - failed - recovered - skipped - cancelled - never_started type: object required: - status - cause - spend type: object JobStatus: description: >- queued and running: the resident owns the execution. interrupted: execution ownership was lost and effect settlement is unknown — an EVIDENCE state (the journal is INCOMPLETE), never a run state (ADR-129). paused, succeeded, failed and cancelled: the run's own settlement, the words its terminal frame carries (ADR-128). enum: - queued - running - interrupted - paused - succeeded - failed - cancelled type: string JobOrigin: oneOf: - additionalProperties: false properties: kind: const: manual type: string required: - kind type: object - additionalProperties: false properties: arm_generation: pattern: ^[0-9a-f]{64}$ type: string decision: enum: - scheduled - catch_up type: string fired_at: format: date-time type: string kind: const: schedule type: string schedule_id: description: >- Origin-local identifier, bounded to 255 UTF-8 bytes by the server maxLength: 255 minLength: 1 type: string schedule_origin: enum: - project - api type: string schedule_revision: pattern: ^sha256:[0-9a-f]{64}$ type: string scheduled_for: format: date-time type: string slot_id: pattern: ^[0-9a-f]{64}$ type: string required: - kind - schedule_origin - schedule_id - schedule_revision - slot_id - decision - scheduled_for - fired_at - arm_generation type: object securitySchemes: bearerAuth: description: 'Exactly one Authorization: Bearer value from the token file' scheme: bearer type: http ````