Create dashboard card

POST /v1/cards

The definition is validated against the card schema: structural problems and authoring mistakes (unknown primitives, bad variants, command ids outside the allowlist, type mismatches) are rejected with 400; bindings this registry doesn't know are accepted and render as placeholders.

Requires: card.create

Request Body

Card name, optional description, and its definition document

CardInsert

definitionrequired

object

accentoptional

string

childrenrequired

object[]

max items: 32

bindoptional

string

crequired

string

commandoptional

string

densityoptional

any

slotoptional

any

variantoptional

string

entityrequired

string

formatVersionoptional

integer

layoutoptional

string

sizeoptional

string

descriptionoptional

string

namerequired

string

Example Request

application/json

{
  "name": "string",
  "definition": {
    "formatVersion": 1,
    "entity": "string",
    "size": "string",
    "layout": "string",
    "accent": "string",
    "children": [
      {
        "c": "string",
        "bind": "string",
        "command": "string",
        "variant": "string"
      }
    ]
  }
}

Response Schema

Card

createdAtrequired

string

format: date-time

definitionrequired

object

A card is a declarative schema, not code — a template bound to an entity type.

accentoptional

any

Omitted = `border`.

childrenrequired

object[]

bindoptional

string

crequired

string

commandoptional

string

densityoptional

any

slotoptional

any

variantoptional

string

entityrequired

any

formatVersionrequired

number

layoutoptional

any

Omitted = `stack`, so every card authored before layouts still renders as it did.

sizerequired

any

descriptionrequired

string

entityrequired

any

formatVersionrequired

number

idrequired

string

pattern: ^[a-z0-9]{24}$

namerequired

string

storeIdrequired

string

pattern: ^[a-z0-9]{24}$

updatedAtrequired

string

format: date-time

Example Response

201 OK — application/json

{
  "name": "string",
  "formatVersion": 1,
  "definition": {
    "formatVersion": 1,
    "children": [
      {
        "c": "string",
        "bind": "string",
        "command": "string",
        "variant": "string"
      }
    ]
  },
  "id": "string",
  "storeId": "string",
  "createdAt": "2026-09-02T09:16:20.019Z",
  "updatedAt": "2026-09-02T09:16:20.019Z"
}