History is kept by flow id: runs, cascades, rollups and events file the id in their flow column and nodes as <flow id>.<node>, the API answers flow plus flow_name and shows and takes nodes as <key>.<node>; events carry flow_id from the moment they are published; run queue items, the stage cache and cached curves keep ids and keys apart; endpoints, the brain graph, device bindings and search name the id to open

docs/concepts/runs.md

@@ -42,7 +42,9 @@ curl -X POST "$FLUKSIO/runs/flows/train" \
 ```
 
 Here `$FLUKSIO` is the API base URL ending in `/api/v1`, and `$TOKEN`
-is an access token. See [The HTTP API](../code/api.md) for authentication.
+is an access token. The path takes the flow's id, here a flow whose id is
+its key, as for one made before ids existed. See
+[The HTTP API](../code/api.md) for authentication.
 
 Submission returns immediately with status `queued`. Read
 `GET /api/v1/runs/{id}` for status and results. Unknown parameters or wrong
@@ -68,7 +70,7 @@ These four runs share a `group_id` and execute concurrently within the
 engine's limits. Each has its own state, so one run cannot overwrite another's
 messages. Vary seeds with `--param seed=1,2,3` if the flow declares that input.
 
-The API equivalent is `POST /api/v1/runs/flows/{name}/sweep` with a
+The API equivalent is `POST /api/v1/runs/flows/{flow id}/sweep` with a
 `runs` list of parameter dictionaries and optional seeds. Filter history
 with `GET /api/v1/runs?group=<group-id>`.
 
@@ -210,7 +212,11 @@ fluksio export runs --flow train --status ok -o results.csv
 
 Both include run IDs. Result rows also include input values, final numeric
 outputs, status, duration and code identifiers. Nested values use dotted paths,
-such as `metric.final_metrics.train_loss`.
+such as `metric.final_metrics.train_loss`. A row names the flow by its id in
+`flow` and by its key in `flow_name`. History stays with the id, so a flow
+keeps its runs whatever its key is later, and a new flow that takes the key
+of a deleted one starts without them. Metric names keep the key, as in
+`train.loss`.
 
 Python returns the same rows directly:
 
@@ -243,8 +249,9 @@ Client().import_runs([{
 }])
 ```
 
-The flow must exist, and parameters are checked against its inputs. Repeated
-imports of the same `external_id` reuse the existing record. Imported runs
+The flow must exist, and parameters are checked against its inputs. Over the
+HTTP API an entry's `flow` is the flow's id. Repeated imports of the same
+`external_id` reuse the existing record. Imported runs
 have no code commit or digest because the engine did not execute them.
 Entries may also carry metric points and base64-encoded artifacts; see the
 API schema for their fields.
@@ -257,7 +264,7 @@ the first run, and controls are disabled.
 
 If the flow has no dashboard, the same menu can create one from its streaming
 ports and outputs. The API equivalent is
-`POST /api/v1/dashboards/from-flow/{name}`. The generated dashboard is
+`POST /api/v1/dashboards/from-flow/{flow id}`. The generated dashboard is
 published and can be edited like any other dashboard.
 
 To keep a chart showing recent experiments, set its source to **Runs** and