api-upload-and-create

1# SPDX-License-Identifier: Apache-2.02# yaml-language-server: $schema=https://nika.sh/spec/v1/workflow.schema.json3#4# TEMPLATE · api-upload-and-create · upload a file and create the resource in one authenticated call.5#6#   [create]7#   nika:fetch · multipart8#9# The product-API job: push the bytes AND the metadata that describe them, get10# the created resource back, keep only the fields you need. One round trip —11# `multipart:` carries a file part and text parts together, which is what most12# create-with-upload endpoints actually want.13#14# Demonstrates ·15#   - `multipart:` · a file part (`path:`) and text parts (`value:`) in one16#     request · exactly one of the two per part17#   - a masked `secrets:` entry in a header, with `egress:` naming the two18#     places it may travel (the call, and the returned value)19#   - `mode: jq` response narrowing · the workflow carries fields, not payloads20#   - `on_error: recover:` · rehearses green with no key and no endpoint, and21#     the same bindings work once it is wired22#23# WHY ONE CALL, not upload-then-create · a file part is `permits.fs.read`-gated,24#   and a private read + untrusted ingress + an onward authenticated POST is the25#   lethal trifecta (NEP-0002): chaining a second call onto the first response26#   fails NIKA-SEC-009 and demands a human gate. Measured both orderings. One27#   round trip needs no ceremony — reach for `human-gated-ship` when the job28#   genuinely wants a person in the loop.29#30# Needs · nothing to rehearse. To run it FOR REAL: a reachable API, the file at31#   `const.asset_path`, and EXAMPLE_API_KEY in the environment — then delete the32#   `on_error:` block so a genuine failure is loud.33#34# Run · nika run <file>          # offline rehearsal · no key, no endpoint35nika: v136workflow:37  id: api-upload-and-create-template  # SLOT: kebab-case workflow id38  # SLOT: one honest sentence — `nika new` matches intents against these words39  description: "upload + create in one authenticated call"40​41const:42  api_base: "https://api.example.com"     # SLOT: the product API base43  asset_path: "./out/assets/asset-1.png"  # SLOT: the file to upload44​45⛨secrets:46  ⛨API_KEY:47    ⛨source: env48    ⛨key: EXAMPLE_API_KEY            # SLOT: the OS env var holding the key49    ⛨egress:50      - ⛨to: "nika:fetch"            # the send · default-deny otherwise51      - ⛨to: "outputs"               # the return value derives from the authed response52​53⛨permits:                            # the blast radius · default-deny once present54  ⛨tools: ["nika:fetch"]55  # `egress:` above sanctions the FLOW (this secret may ride a fetch); it does56  # NOT grant the capability to reach anyone. The host is the separate, required57  # half — an unlisted host is refused at RUN, mid-flight, with the bytes58  # already on the wire.59  ⛨net: { http: ["api.example.com"] }   # SLOT: the host from const.api_base60  ⛨fs:61    # A `multipart:` file part names a path, and that read crosses the boundary62    # like any other: measured, without this entry the call dies `NIKA-SEC-004 ·63    # ./out/assets/asset-1.png resolves outside the declared permits.fs.read64    # boundary`. One exact file, never the tree it sits in. The drift detector65    # models a multipart part as a read (2026-07-29) — the former NIKA-DRIFT-00166    # false hint is closed.67    ⛨read: ["./out/assets/asset-1.png"]   # SLOT: keep in step with const.asset_path68​69tasks:70  create:71    ◆invoke:72      tool: "nika:fetch"73      args:74        url: "${{ const.api_base }}/items"   # SLOT: the create endpoint75        method: POST76        headers:77          x-api-key: "${{ secrets.API_KEY }}"  # SLOT: the auth header name78        multipart:79          # Exactly one of `path:` (file) or `value:` (text) per part — a part80          # carrying both, or neither, is refused before anything is sent.81          - { name: file, path: "${{ const.asset_path }}" }82          - { name: title, value: "Rehearsal item" }   # SLOT: the metadata fields83        mode: jq84        jq: "{ id: .id, url: .url }"   # SLOT: the fields downstream needs85    on_error:86      # Offline rehearsal · a literal shaped EXACTLY like what the jq above87      # projects, so `outputs.result` has the same shape on both paths. It also88      # absorbs the unset key: a `secrets:` entry whose env var is missing fails89      # NIKA-VAR-001, and a recover catches that too (measured).90      recover: { id: "rehearsal-0001", url: "https://app.example.com/items/rehearsal-0001" }91​92outputs:93  result: ${{ tasks.create.output }}   # SLOT: the callable contract94​