Update a screen (fails with 404 if absent).
const url = 'https://example.com/example/example/screens/example';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"hfxSource":"example","label":null}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://example.com/example/example/screens/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "hfxSource": "example", "label": null }'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”First path segment; must be metadata@<branchId> (validated by the BranchRef extractor). Not a business parameter – an artifact of axum’s matchit being unable to match a literal-prefixed param within one segment.
Module key.
Screen key.
Request Bodyrequired
Section titled “Request Bodyrequired”Request body for POST and PUT screen write endpoints.
Request body for POST and PUT screen write endpoints.
object
Raw HFX source text. The // @hfx N directive inside the source is the
single source of truth for the version — no separate version field accepted.
Optional human-readable label. Accepted but not yet persisted separately —
the loader derives the screen’s label as None until a label convention
lands in the HFX source format.
Responses
Section titled “Responses”Successful metadata write response.
pub(crate), not pub(super): named directly in
crate::routes::metadata::mod::write_router’s .response::<CODE, ...>()
OpenAPI response documentation (#814), which sits outside handlers.
Successful metadata write response.
pub(crate), not pub(super): named directly in
crate::routes::metadata::mod::write_router’s .response::<CODE, ...>()
OpenAPI response documentation (#814), which sits outside handlers.
object
The branch the write was committed to (sigil already stripped).
The .json5 file path relative to the metadata directory.
Example
{ "status": "created"}default
Section titled “default”Structured error envelope (SPEC-DATA-0006): {"errors": [{"scope", "target", "code", "message"}, ...]}.
The top-level response body. Wraps a non-empty list of [ErrorEntry].
object
The error entries making up the envelope. Always non-empty.
One entry in the error envelope.
Carries an anchoring [ErrorScope], an optional target that
disambiguates within the scope, a stable SCREAMING_SNAKE_CASE code, and
a human-readable English message. See SPEC-DATA-0006 for the full
envelope contract.
object
Machine-readable, stable, SCREAMING_SNAKE_CASE identifier.
HFX source location for a [DataError::HfxCompileError] entry.
Emitted as the extra location field on the entry JSON when present,
per SPEC-UI-0043. The line/column are 1-based. The frame is the
offending source line extracted verbatim from the input.
object
1-based column within the line, measured in UTF-16 code units of the prefix so browser-side editors can consume it directly.
The offending source line text, when available.
1-based line number within the source text.
Server-authored English message. Not part of the API contract; may change across releases without notice.
The key of the ValidationRule that
failed, when the code is RULE_FAILED. None for all other codes.
Skipped during serialization when absent so it does not appear on
unrelated entries (same pattern as location).
Documented here as a plain string (#[schemars(with = "...")])
rather than a $ref to ValidationRuleKey’s own schema: that type
lives in metadata-types, which does not derive JsonSchema yet
(tracked by #812). ValidationRuleKey serializes transparently as
its inner string (serde’s default newtype-struct behavior), so this
is an accurate wire-shape description, not a placeholder.
Field key for field scope, record id for record scope, null
otherwise. Always serialized, even when null.
Example
{ "errors": [ { "scope": "field" } ]}