<!-- source: https://docs.dreamlake.ai/ml-dash/reference/native-run-metadata @ 0.1.192 b2f973b1 -->
# Native Experiment run metadata

A native run has a human `description` and `tags`. Projects whose
`GET .../status` lists the `run-metadata` capability accept them on create and
on update. Both writes require a signed-in user with write access to the
project, or a write session that user minted. A job session cannot set them and
gets `403 NATIVE_FORBIDDEN`.

`PUT /native-experiments/ns/:namespace/projects/:project/runs/:runKey` creates
or returns the run, and `PATCH .../runs/:runId` updates it:

```json
{"description": "lr sweep baseline", "tags": ["lr-sweep", "v2"]}
```

| Field | Absent | `null` / `""` / `[]` | Value |
| --- | --- | --- | --- |
| `description` | unchanged | `null` or `""` clears it | a string of at most 2,000 code points |
| `tags` | unchanged | `[]` clears them | replaces the whole set |

Tags are trimmed and de-duplicated in order; there can be at most 20 tags of
at most 50 code points each. Writing the stored values again changes nothing,
so a repeated `PUT` is safe. `PATCH` also accepts `archived` (a boolean). A
change to `description` or `tags` restores an archived run unless the same body
sets `archived: true`. A write-protected run rejects a change with
`409 NATIVE_RUN_WRITE_PROTECTED`, but can still be archived.

The same rules apply wherever the run is stored: in the main DreamLake
database, or in the separate Dash database used for new runs when the server
runs the native Dash store. A run keeps its storage, so a metadata write never
moves it.

An invalid value returns `400 NATIVE_INVALID_RUN_METADATA`. Any other field
returns `400 NATIVE_INVALID_RUN` on `PUT` and `400 NATIVE_INVALID_ARCHIVE` on
`PATCH`. Every run response and the run list return `description` (`null` when
unset) and `tags` (`[]` when unset).

## Additional metadata

The API also accepts a `metadata` object or `null` on run creation and
updates. GraphQL `Experiment.metadata` and its experiment `Node.metadata` return
that value from the run's original storage. `me`, namespace and project metadata
use DreamLake's canonical records; workload and job credentials do not gain
project or account metadata access.

Run, file and folder PATCH routes also accept `priority`, a signed 32-bit integer.
GraphQL tree children put higher priorities first. Files initially use ml-dash's
defaults: `.dashrc` 200, `README.md` 100 (case-insensitive), and other names 0.
Renaming or moving a file retains its priority. File metadata can be any JSON
value; run metadata remains an object or `null`.

## Project folders

`POST /native-experiments/ns/:namespace/projects/:project/folders` and
`PATCH …/folders/:folderId` also accept `description`, `tags`, `metadata` (any JSON)
and `priority` (a signed 32-bit integer). Missing fields stay unchanged; `null`
clears the description or metadata, and `[]` clears tags. These values stay with
the folder's ID through renames and moves. GraphQL `updateNode` edits its
description and tags. Writes require a person's WRITE access and refuse a
protected, trashed or pending folder. Empty project folders are retained.

Inside a run, `GET/POST …/runs/:runId/folders` and
`GET/PATCH/DELETE …/runs/:runId/folders/:folderId` manage file folders, including
empty ones. Create with `{ "path": "/checkpoints/empty" }`; PATCH accepts the same
metadata fields and an optional new `path`. A move keeps folder and file IDs.
Delete removes the subtree permanently. These operations stay in the run's
original storage, honor its write protection, and restrict a run-bound writer
or job to that run. The server advertises them as `file-folders`.

Run file prefixes accept Unicode, spaces, commas and percent signs. For example,
`/实验 记录/a,b/%2C` keeps those names literally through uploads, folder moves,
file listings and downloads. File names are single path segments; control
characters and `.` or `..` segments are rejected. Extended paths use the same
lifecycle rollout gate as file folders.
