Who controls what

Block types and fields are developer territory. The content inside those fields is marketer territory. That split is the whole design, and it is why there is no field editor in the dashboard.

There is deliberately no "create a block type" button in the dashboard. A block type is a contract with your app's rendering code, so it is versioned in your repository alongside the code that renders it, exactly like a database migration. Adding one is a two minute API call, documented below.

Block types

Every block picks a design type; the renderer and dashboard badge follow it. What the block holds is its fields, described next.

Field types

Eight types, all first class, all editable in the dashboard and all delivered over GET /sdk/v1/sync. Seven are scalars. The eighth, collection, holds a list.

Fields are addressed by tag

Every field carries a tag, a string like #title_main or #header_image. Your app reads values by tag. It never reads them by array index, and it never depends on field order.

GET /sdk/v1/sync returns each block's values object keyed by tag, alongside a fields array that repeats each tag with its type, so a renderer can branch on type instead of guessing from the name.

// values is keyed by TAG
const title = block.values['#title_main']
const image = block.values['#header_image']

// fields tells you the type, so you can render by type
block.fields.forEach(f => {
  if (f.type === 'image') paintBackground(block.values[f.tag])
})

• Tags are yours to choose. Pick names that describe the slot, not the current copy.
• Tags must be unique within their immediate scope. Two different block types may both use #title_main. The server enforces this inside a collection only; for scalar fields it is not validated, but treat it as required, because a repeated tag makes the value ambiguous.
• Renaming a tag is a breaking change for any app version already reading the old one. Add a new field instead, then retire the old one once old app versions have aged out.

Block definition shape

A block definition is a small JSON object. This is the whole contract.

And a single field:

A scalar field that declares allowedBlockKeys, minItems, or maxItems is rejected, and so is any field that declares an inline fields sub schema. No field type carries a nested schema: a collection names other definitions by key, and each referenced definition owns its own fields.

{
  "key": "hero_banner",
  "name": "Hero banner",
  "screen": "Home screen",
  "crumb": "home_screen / hero_banner",
  "inCampaigns": true,
  "fields": [
    { "id": "bg",    "tag": "#header_image",  "type": "image",    "label": "Background image", "default": "" },
    { "id": "title", "tag": "#title_main",    "type": "text",     "label": "Headline",         "default": "" },
    { "id": "body",  "tag": "#body_desc",     "type": "textarea", "label": "Supporting text",  "default": "" },
    { "id": "cta",   "tag": "#cta_label",     "type": "text",     "label": "CTA label",        "default": "" },
    { "id": "on",    "tag": "#block_enabled", "type": "toggle",   "label": "Block enabled",    "default": true }
  ],
  "blank": { "bg": "", "title": "", "body": "", "cta": "", "on": true }
}

The definition schema is not the delivery schema

There are two different fields arrays in this product, and conflating them is an expensive mistake. The one you write when registering a block type is not the one you read from GET /sdk/v1/sync.

Which credential to use

Three keys, not interchangeable. The write key and read key are in the dashboard under Developers → Your keys (shown to admin and editor seats only, and rotated there); the SDK key is under Settings → API keys. Write and read keys are stored hashed: the full value is shown once, when it is created or rotated, and masked afterwards. If you lost it, rotate it.

Register one block type: POST /cards/register

Authenticated with X-CF-Write-Key. Upserts by key, so running it twice is safe and the second run updates the definition in place. The body needs key (matching /^[a-z0-9_]+$/) and optionally takes name (defaults to the key), screen, crumb, fields, blank, inCampaigns and seedInstance. By default it also seeds one blank starter draft instance; send "seedInstance": false to skip it.

$ curl -X POST https://api.contentflow.click/sdk/v1/cards/register \
     -H "X-CF-Write-Key: $CF_WRITE_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "key": "hero_banner",
       "name": "Hero banner",
       "screen": "Home screen",
       "fields": [
         { "id": "bg",    "tag": "#header_image",  "type": "image",    "label": "Background image" },
         { "id": "title", "tag": "#title_main",    "type": "text",     "label": "Headline" },
         { "id": "body",  "tag": "#body_desc",     "type": "textarea", "label": "Supporting text" },
         { "id": "cta",   "tag": "#cta_label",     "type": "text",     "label": "CTA label" },
         { "id": "on",    "tag": "#block_enabled", "type": "toggle",   "label": "Block enabled" }
       ],
       "blank": { "bg": "", "title": "", "body": "", "cta": "", "on": true }
     }'

Use this for a one-off registration or a quick experiment. Use the manifest below for anything that runs in CI.

Register many at once: POST /cards/sync, the manifest

Authenticated with the workspace write key in X-CF-Write-Key. The workspace is resolved from the key itself, so no tenant header is needed. This is the endpoint to run from CI on every merge: it declares the full set of block types your app expects, and reconciles the workspace to match.

• Idempotent by externalId for seeded instances. Re-running updates in place rather than duplicating.
• Definitions are upserted by key.
• Each entry takes the same shape as a POST /cards/register body, plus an optional instances array carrying content.
• The manifest array is blocks. The alias cards is accepted for the same array, and inside an entry the alias items is accepted for instances.
• Any active block type not present in a landed manifest is archived. This endpoint declares the full set, it does not merge, so send your complete set every time.
• An empty or malformed manifest is rejected with 400.
• There is no dry-run mode. A dryRun flag in the body is ignored and the sync is applied, so read archived in the response.
• Keys must match /^[a-z0-9_]+$/. An invalid key is reported per entry and the rest of the manifest still lands.

$ curl -X POST https://api.contentflow.click/sdk/v1/cards/sync \
     -H "X-CF-Write-Key: $CF_WRITE_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "blocks": [
         {
           "key": "hero_banner",
           "name": "Hero banner",
           "screen": "Home screen",
           "fields": [
             { "id": "bg",    "tag": "#header_image", "type": "image", "label": "Background image" },
             { "id": "title", "tag": "#title_main",   "type": "text",  "label": "Headline" }
           ],
           "instances": [
             {
               "externalId": "home_hero_default",
               "title": "Summer campaign",
               "status": "draft",
               "values": {
                 "#header_image": "https://your-cdn.example.com/summer-hero.jpg",
                 "#title_main": "Summer rates are live"
               }
             }
           ]
         }
       ]
     }'

Seeded instance content may be supplied as values keyed by tag, which is the readable form shown above. Seeded instances land as draft unless you set status, so importing your app's existing content never publishes anything by accident.

{
  "prune": true,
  "blocks": []
}

An image background banner, end to end

The full path from nothing to a banner whose background is a marketer editable image: define the type, register it, let an editor fill it, read it back, and paint it. Four calls and one loop.

1 · Define the type with an image field

One image field tagged #header_image, alongside the text fields that sit on top of it. The image field is what the customer facing upload control binds to.

{
  "key": "hero_banner",
  "name": "Hero banner",
  "screen": "Home screen",
  "crumb": "home_screen / hero_banner",
  "fields": [
    { "id": "bg",    "tag": "#header_image",  "type": "image",    "label": "Background image" },
    { "id": "title", "tag": "#title_main",    "type": "text",     "label": "Headline" },
    { "id": "body",  "tag": "#body_desc",     "type": "textarea", "label": "Supporting text" },
    { "id": "cta",   "tag": "#cta_label",     "type": "text",     "label": "CTA label" },
    { "id": "on",    "tag": "#block_enabled", "type": "toggle",   "label": "Block enabled" }
  ],
  "blank": { "bg": "", "title": "", "body": "", "cta": "", "on": true }
}

2 · Register it in the workspace

With the write key and the single-type route, which upserts this one definition and leaves every other block type alone. @hero_banner.json is the file above.

$ curl -X POST https://api.contentflow.click/sdk/v1/cards/register \
     -H "X-CF-Write-Key: $CF_WRITE_KEY" \
     -H "Content-Type: application/json" \
     -d @hero_banner.json

// 201 Created
{ "success": true,
  "data": { "registered": "hero_banner", "definitionCreated": true,
            "instanceId": "…", "instanceCreated": true } }

In CI, put this definition in your full manifest and use POST /cards/sync. That endpoint archives every block type the manifest leaves out, so never send it a partial list.

3 · An editor fills it in

hero_banner now appears in the dashboard Blocks library with a real upload control on the Background image field. A marketer creates an instance, uploads or picks an image, writes the copy, targets a segment, and publishes. No further developer involvement, and no app release.

To seed the first instance yourself instead, include an instances array in the manifest with values keyed by tag, as shown in Path 2.

4 · Read it back from the SDK surface

This is the delivery read, so it uses the publishable SDK key, not the write key. The key alone is enough here: the tenant is resolved from the key's stored record (for a publishable key), so there is no X-Tenant-Id header to set. A conflicting X-Tenant-Id is refused with 401 TENANT_KEY_MISMATCH.

$ curl https://api.contentflow.click/sdk/v1/sync \
     -H "X-CF-Key: $CF_SDK_KEY" \
     -H "X-CF-Device: $CF_DEVICE_ID"

$CF_SDK_KEY is your test-environment publishable key while you test (it also sees instances published to Test) and your live publishable key in production.

{
  "success": true,
  "data": {
    "blocks": [
      {
        "key": "hero_banner",
        "name": "Hero banner",
        "screen": "Home screen",
        "instanceId": "b1f0…",
        "segment": "All users",
        "version": 3,
        "values": {
          "#header_image": "https://your-cdn.example.com/summer-hero.jpg",
          "#title_main": "Summer rates are live",
          "#body_desc": "Fixed for 12 months, from 3.5%.",
          "#cta_label": "See the rate",
          "#block_enabled": true
        },
        "fields": [
          { "tag": "#header_image",  "type": "image" },
          { "tag": "#title_main",    "type": "text" },
          { "tag": "#body_desc",     "type": "textarea" },
          { "tag": "#cta_label",     "type": "text" },
          { "tag": "#block_enabled", "type": "toggle" }
        ]
      }
    ],
    "version": "9c2a…"
  }
}

A workspace with no live blocks yet returns the same shape with an empty blocks array. That is a valid 200, not an error.

5 · Paint the background

Access the image by tag. An image value arrives as a plain URL string, ready to hand to an image view or a background style.

const hero = data.blocks.find(b => b.key === 'hero_banner')
if (!hero) return null   // nothing live for this device, render nothing

const bg    = hero.values['#header_image']  // '' when unset, never a broken URL
const title = hero.values['#title_main']
const cta   = hero.values['#cta_label']

banner.style.backgroundImage = bg ? `url(${bg})` : 'none'
banner.querySelector('.t').textContent = title
banner.querySelector('.cta').textContent = cta

That is the entire loop. The image is now marketer editable forever: they swap the file in the dashboard, publish, and the next sync paints the new background with no release.

Binding a Content Library upload to an image field

An image field value is a URL. Two sources work:

• Your own CDN. Any HTTPS URL you host. Paste or set it as the field value.
• The ContentFlow Content Library. Upload the asset, then use its stable public URL, https://api.contentflow.click/api/v1/content/<assetId>/raw. That route resolves the asset by its unguessable id and redirects to a freshly signed download URL on every request, so the value you store in a block field does not expire.

Which block type exposes #header_image

These are the demo block types that ship with image fields, and the tags they use:

Copying the demo tags exactly is a reasonable starting point if you want your app code to match our onboarding snippets, but you are free to name every tag yourself.

A list is a wrapper around real card instances

A collection field holds an ordered list of references to other block instances. The block that owns the field is the wrapper, for example a carousel. Each referenced instance is a card. A card is an ordinary block instance, which is the entire reason this shape exists: it carries its own segment targeting, its own schedule, its own approval state, its own A/B variants and its own analytics, because all of that already lives at the instance level and a card is an instance.

Nothing in the list is a nested value. The wrapper stores instance ids, ContentFlow resolves them, and your app receives whole blocks.

1 · Define the card, then the wrapper

The card is an ordinary block definition with ordinary scalar fields. The wrapper declares which definition keys its collection may reference, and nothing about their contents.

{
  "key": "reading_card",
  "name": "Reading card",
  "screen": "Home screen",
  "fields": [
    { "id": "title", "tag": "#title", "type": "text",     "label": "Title" },
    { "id": "image", "tag": "#image", "type": "image",    "label": "Artwork" },
    { "id": "body",  "tag": "#body",  "type": "textarea", "label": "Body" }
  ]
}

{
  "key": "reading_carousel",
  "name": "Reading carousel",
  "screen": "Home screen",
  "fields": [
    { "id": "heading", "tag": "#heading", "type": "text", "label": "Heading" },
    { "id": "slides",
      "tag": "#slides",
      "type": "collection",
      "label": "Slides",
      "allowedBlockKeys": ["reading_card"],
      "minItems": 0,
      "maxItems": 20 }
  ]
}

A wrapper may hold any number of ordinary scalar fields alongside its collection fields, and a collection may list several allowed keys, so a feed can mix article_card and promotion_card.

2 · The wrapper stores instance ids

Collection references live in the wrapper's existing value map, under the same key every other field uses: the field id, with the tag accepted as a fallback. The stored value is exactly an ordered array of instance id strings. It is never an array of objects and it never snapshots the referenced content.

{
  "heading": "Recommended for you",
  "slides": [ "card-a12f…", "card-b34c…", "card-c56d…" ]
}

• Editing a card changes every wrapper that references it. That is the point of a reference, and it is why the sync validator is a digest of the whole resolved response rather than of the wrapper's own version.
• Order lives only on the wrapper. Moving a card in one carousel does not move it in another.
• Identity is the card's instanceId. Array position is never identity: a card moved from slot 2 to slot 5 keeps its id, and replacing a card produces a new one.
• A locale overlay may not touch the list. References are structural source locale data, so a collection key inside an i18n overlay is rejected rather than silently applied. Translators still translate each card's own scalar values, on the card.

What delivery returns

Eligible cards are inlined under the collection's tag, each as the full delivered block shape: key, name, screen, instanceId, segment, numeric version, resolved values, and schema only fields. No second round trip, and no card model to learn. A card is a block.

{
  "key": "reading_carousel",
  "name": "Reading carousel",
  "screen": "Home screen",
  "instanceId": "carousel-7df3…",
  "segment": "All users",
  "version": 4,
  "values": {
    "#heading": "Recommended for you",
    "#slides": [
      {
        "key": "reading_card",
        "name": "Reading card",
        "screen": "Home screen",
        "instanceId": "card-a12f…",
        "segment": "All users",
        "version": 6,
        "values": {
          "#title": "First article",
          "#image": "https://cdn.example.com/first.jpg",
          "#body":  "First article body"
        },
        "fields": [
          { "tag": "#title", "type": "text" },
          { "tag": "#image", "type": "image" },
          { "tag": "#body",  "type": "textarea" }
        ]
      }
      // card-b34c… is absent: it did not pass delivery eligibility for this device
    ]
  },
  "fields": [
    { "tag": "#heading", "type": "text" },
    { "tag": "#slides",  "type": "collection",
      "allowedBlockKeys": ["reading_card"], "minItems": 0, "maxItems": 20 }
  ]
}

A card that was inlined is suppressed from the top level

A card delivered inside a wrapper is removed from the top level blocks array, so you never render the same content twice and no client needs to know which blocks it already drew inside a carousel.

The suppression set is computed from what was actually emitted, never from the reference graph, and the difference matters to you:

• A card whose wrapper was filtered out by targeting, paused, disabled, scheduled out, or omitted because it resolved to zero cards still appears at the top level. Content never silently vanishes because of a wrapper you never received.
• A card referenced by two delivered wrappers appears in both. That duplication is intended: position and rendering context belong to each wrapper, and the card carries the same instanceId in both places.

Which cards you get, and in what order

Reading a collection in your app

The values map holds whole blocks, so the card loop is the same loop you already write for a top level block. Key it on instanceId.

const carousel = data.blocks.find(b => b.key === 'reading_carousel')
if (!carousel) return null   // no eligible slides, render nothing

const slides = carousel.values['#slides'] || []

slides.forEach(card => {
  // a card IS a block: same values map, same fields schema
  render({
    key:   card.instanceId,                 // identity, never the index
    title: card.values['#title'],
    image: card.values['#image']
  })
})

Using the JavaScript SDK, block.getCollection('#slides') returns the same cards as parsed CFBlock objects and never throws. The native SDKs expose the same idea: Swift collection(_:) and Kotlin collection(tag).

Analytics need no extra work

A card's events are owned by the card's own instanceId, with the wrapper as a dimension. Send engagement for a card the way you send it for any block, and per card performance is available immediately. The metric owner is never rewritten to the wrapper, so a card used in three carousels reports against itself in all three and can still be broken down by placement.

Rules, limits, and the errors you will meet

Deleting or archiving something a collection points at

Referential integrity is enforced, and the refusal names every referrer so it is actionable instead of a bare conflict.

{
  "success": false,
  "code": "instance_referenced",
  "error": "Instance card-a12f… is referenced by 3 collections.",
  "references": [
    { "wrapperInstanceId": "carousel-7df3…", "fieldTag": "#slides" },
    { "wrapperInstanceId": "carousel-921a…", "fieldTag": "#slides" },
    { "wrapperInstanceId": "home-feed-184b…", "fieldTag": "#cards" }
  ]
}

• Deleting a referenced instance answers 409 instance_referenced with a references array of { wrapperInstanceId, fieldTag }.
• Archiving a referenced block definition answers 409 instance_referenced too, with a references array of { wrapperBlockKey, fieldTag }, because archiving it would make every wrapper pointing at its instances resolve to nothing.
• Pausing and disabling stay available while referenced. They are reversible delivery controls, and ContentFlow already treats a paused card as simply absent, so nothing is orphaned.

Payload size fails at publication, not at delivery

A wrapper inlines every card in full, schema included, so it is the one shape whose payload can grow without an obvious authoring signal. The guard therefore runs when content is published, where a human is present to be told why.

• A publish that would push a wrapper over the sync payload limit is rejected with 400 and code: "collection_payload_too_large". The limit defaults to 512 KiB per delivered wrapper.
• Size is measured at its worst case: every stored reference inlined whether or not that card is live right now, and every locale on the wrapper or on any of its cards measured with the largest winning. Uncompressed, matching the bytes the validator is taken over. Gzip and Brotli on the wire are headroom, not budget.
• Editing or publishing a card, or renaming a card definition, is measured too, because each of those grows every wrapper that inlines it without touching a wrapper document.
• If one write would force re-verifying more than 200 wrappers or 2000 referenced cards, it is rejected with code: "collection_remeasure_scope_exceeded" rather than skipping the check.
• There is a runtime backstop: should an oversized wrapper reach ContentFlow's delivery path anyway, trailing cards are dropped until it fits, in authored order, and the truncation is logged at error level. It exists so imports, restores and migrations cannot hand a device an unbounded body. It is not a mode to design against.

Repeater fields were withdrawn, and replaced by collections

The withdrawn design stored a list's items as nested values inside a single block instance. That made every item a value rather than an entity, so an individual card could not carry its own segment targeting, its own schedule, its own approval state, its own A/B variants, or its own analytics. This platform is instance centric and all of that machinery already exists at the instance level, so a list built out of values sat outside it.

A collection is that same list expressed as a wrapper holding an ordered set of real block instances, so every card inherits targeting, scheduling, approval, experiments and per card analytics for free. If you were waiting on the replacement, it is here and it is shipped.

Nothing carries over from the old shape at the wire level. A collection field declares allowedBlockKeys instead of a sub schema, an instance stores instance ids instead of nested item objects, and ContentFlow inlines whole blocks instead of { id, values } items.

Troubleshooting

My registration call returns 401

Wrong credential. POST /cards/register and POST /cards/sync need the workspace write key in X-CF-Write-Key. Your SDK (publishable) key authenticates delivery reads only and will never register a block type. See Which credential to use.

My workspace has no image field anywhere

Expected on a fresh workspace. It is seeded with only welcome_banner and its three text style fields. Register a block type with an image field and the dashboard renders an upload control for it immediately.

The block registered but /sdk/v1/sync returns nothing

Delivery returns live instances only, and the definition alone is not content. Create and publish an instance, or seed one through the manifest and publish it. A definition with zero live instances correctly delivers nothing.

The block was live and then disappeared

Check three things. The instance's enabled toggle, since an instance whose on or enabled toggle is false is not delivered. The instance's segment, since ContentFlow scopes what it returns to the segments the device belongs to. And your last manifest sync, since any active block type absent from a landed manifest is archived.

My image renders as a broken image

Guard on an empty string. An image field with no usable value is delivered as "" on purpose, so your app can render no image instead of a broken one. Also confirm you stored a stable URL rather than a short lived presigned one. See Content Library assets.

How do I build a carousel or a multi card row

Declare a collection. Register a card block type, register a wrapper whose collection field lists that key in allowedBlockKeys, then let a marketer add card instances to the wrapper in the order they want. ContentFlow inlines the eligible cards under the collection's tag as whole blocks. Key your list on each card's instanceId, never on array position.

Placing several independent instances of one block type on a screen still works and is still ordered by ContentFlow, but it gives you no per list ordering and no wrapper level chrome. Reach for a collection when the list is a list.

My carousel disappeared entirely

A wrapper whose collections resolve to zero eligible cards is omitted from the response on purpose, so no client draws chrome around an empty list. Check each card the way you would check any instance: status, the on or enabled toggle, schedule, and the segment it targets. Remember targeting is an intersection, so a card targeted at a segment the wrapper's audience never contains can never appear. See how targeting works for how a trait becomes a segment and how an instance is targeted at one.

I cannot delete or archive a card

Something still references it. The 409 body carries a references array naming every wrapper and field tag, so remove it from those collections first. Pausing the card is available immediately and is reversible: ContentFlow treats a paused card as simply absent.

My publish was rejected with collection_payload_too_large

The wrapper would deliver more than the sync payload limit, measured at its worst case: every stored reference inlined and the largest locale. Remove references or shorten card content. See Rules, limits, and errors.