curl --request POST \
  --url https://api.example.com/types \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "type": {
    "id": "<string>",
    "fields": {},
    "version": 123,
    "label": "<string>",
    "description": "<string>",
    "parent": "<string>",
    "display_hints": {
      "title_field": "<string>",
      "body_field": "<string>"
    },
    "version_policy": {
      "recent_days": 123,
      "daily_snapshot_days": 123,
      "weekly_snapshot_days": 123,
      "max_versions": 123
    },
    "merge_policy": {
      "fields": {}
    }
  }
}

Types

Register a custom type

Registers a custom type at runtime. Identifier must namespace under one of app.<app-name>.<type>, user.<type>, or <publisher>.<type> — reserved roots (core, system, marfa) reject with 400 reserved_namespace. Bodies are validated; mismatched semver bumps (additive change submitted as major, etc.) reject with 400 version_bump_mismatch. Child types may not redefine ancestor fields — 400 inheritance_violation. Property names may not shadow first-class Item wire fields (device, source_id, timestamp, version, schema_version, tier, state, capture_latitude, capture_longitude, etc.) — 400 property_shadows_field.

Admin keys bypass; non-admin credentials need the metadata.types:write scope, default-off for new keys. See Authoring types for the rubric and error catalogue.

POST

types

curl --request POST \
  --url https://api.example.com/types \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "type": {
    "id": "<string>",
    "fields": {},
    "version": 123,
    "label": "<string>",
    "description": "<string>",
    "parent": "<string>",
    "display_hints": {
      "title_field": "<string>",
      "body_field": "<string>"
    },
    "version_policy": {
      "recent_days": 123,
      "daily_snapshot_days": 123,
      "weekly_snapshot_days": 123,
      "max_versions": 123
    },
    "merge_policy": {
      "fields": {}
    }
  }
}

Authorizations

Authorization

string

header

required

Pass an API key (marfa_k1_...) or OAuth access token (marfa_at_...)

Body

application/json

{key}

unknown

Response

Custom type registered

type

object

required

Show child attributes

List types Get a type

Documentation Index

Authorizations

Body

Response