Skip to content
Henceforth Docs

Create an object within a module (fails with 409 if it already exists).

POST
/{branchRoot}/{moduleKey}/objects/{objectKey}
curl --request POST \
  --url https://example.com/example/example/objects/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "description": "example", "identity": "example", "label": "example", "rules": {} }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
branchRoot
required
string

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.

moduleKey
required
string

Module key.

objectKey
required
string

Object key.

Request Bodyrequired

Section titled “Request Bodyrequired”

Request body for POST/PUT /metadata@{branchId}/{moduleKey}/objects/{objectKey}.

Media typeapplication/json

Request body for POST/PUT /metadata@{branchId}/{moduleKey}/objects/{objectKey}.

object
description

Optional description.

string | null
identity

Optional visual identity (color + icon), SPEC-UI-0049. Schema pending #812 – shape is metadata::IdentityConfig.

label
required

Human-readable label.

string
rules

Validation rules to apply on this object, keyed by rule name. Schema pending #812 – values are metadata::ValidationRule.

object
Examplegenerated
{
  "description": "example",
  "identity": "example",
  "label": "example",
  "rules": {}
}

Responses

Section titled “Responses”

201

Section titled “201”

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.

Media typeapplication/json

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
apply
Any of:

Abbreviated apply engine result for the API response.

object
columnsAdded
required

Number of columns added.

integer format: uint
ddlExecuted
required

Number of DDL changes executed.

integer format: uint
tablesCreated
required

Number of new tables created.

integer format: uint
branch
required

The branch the write was committed to (sigil already stripped).

string
file
required

The .json5 file path relative to the metadata directory.

string
status
required

What was written ("created", "updated", or "deleted").

One of:

The resource was newly created.

string
Allowed value: created
Example
{
  "status": "created"
}

default

Section titled “default”

Structured error envelope (SPEC-DATA-0006): {"errors": [{"scope", "target", "code", "message"}, ...]}.

Media typeapplication/json

The top-level response body. Wraps a non-empty list of [ErrorEntry].

object
errors
required

The error entries making up the envelope. Always non-empty.

Array<object>

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
code
required

Machine-readable, stable, SCREAMING_SNAKE_CASE identifier.

string
location
Any of:

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
column
required

1-based column within the line, measured in UTF-16 code units of the prefix so browser-side editors can consume it directly.

integer format: uint32
frame

The offending source line text, when available.

string | null
line
required

1-based line number within the source text.

integer format: uint32
message
required

Server-authored English message. Not part of the API contract; may change across releases without notice.

string
rule

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.

string | null
scope
required

Anchoring category. Drives client-side rendering.

One of:

Attached to a specific request field. target is the field key.

string
Allowed value: field
target

Field key for field scope, record id for record scope, null otherwise. Always serialized, even when null.

string | null
Example
{
  "errors": [
    {
      "scope": "field"
    }
  ]
}