Concepts

Blocks vs. instances

A block type is a UI shape defined in code (a hero, a card, a carousel). A block instance is that shape filled with content, a specific hero on your home screen. Types are defined by developers and registered over the REST API, the CLI that will version them from git is not published yet; instances are managed by anyone in the dashboard. Field types and tag addressing are covered in Blocks & fields.

A list is not a special case of either. A collection field holds an ordered list of references to other instances, so a carousel is an ordinary instance whose slides are ordinary instances. Every card therefore has its own targeting, schedule, approval state, A/B variants and analytics, and delivery inlines the eligible ones in full under the field's tag.

Channels

A channel is where a block is delivered: push, whatsapp, sms, popup, or in-app. Popup and in-app render as block-style image cards; SMS and WhatsApp run through configured Twilio channels.

Segments & targeting

A segment is an audience. Blocks and campaigns target a segment, a locale, or a single user. The special "All users" segment requires contacts to have phone + consent before SMS/WhatsApp can reach them. For the whole chain, sending a trait through to proving the targeting landed, see Traits & targeting.

Architecture

ContentFlow runs as a small set of services behind an API gateway. Your app only ever talks to the gateway, directly over the REST API or through an SDK that wraps it. There is no other entry point.

Your app
   │  REST API (X-CF-Key, the only required header on /sdk/*)
   ▼
API Gateway  /api/v1
   ├──► auth-service     workspaces, members, keys
   ├──► content-service  blocks, instances, sync
   ├──► strings-service  extract, translate, deliver
   └──► campaign-service segments, dispatch
             │
             ▼
        MongoDB  (per-tenant data)

Content lifecycle

1. Define, a developer adds a block type in code and registers it with POST /blocks. The cf push CLI that will do this from git is not published yet.
2. Fill, someone creates an instance in the dashboard (or seeds it via /cards/sync).
3. Target, pick a segment, locale, and channel.
4. Publish, the block goes live; content.published fires.
5. Sync, apps pull it on their next GET /sdk/sync, no redeploy.
6. Roll back, revert instantly if needed; content.rolledback fires.

Traits & targeting

A trait is a fact your app tells us about a device or a person. A segment is a named audience defined by rules over those facts. An instance is targeted at one segment by name. This section walks the whole chain in the order you build it: send a trait → write a rule over it → create the segment → point an instance at it → prove it landed.

Read the warn notes even if you skim the rest. Four of them cover failures that return a success status and then reach nobody: an invalid trait key, a trait sent without consent, a typo in seg, and a renamed segment.

1. Send a trait

Traits are sent on POST /api/v1/sdk/identify, authenticated with your SDK key in X-CF-Key. On /sdk/* the key is the only required credential, and this call also needs X-CF-Device because it is about a device. The X-Tenant-Id in the example below is optional and redundant, since the key already names the workspace; send it and it must agree with the key, or the call is refused with 403 TENANT_KEY_MISMATCH. The traits body field is optional, and its keys are flat: nesting goes inside a value, never in a key.

$ curl -X POST https://app.contentflow.click/api/v1/sdk/identify \
     -H "Content-Type: application/json" \
     -H "X-CF-Key: ws_a1b2c3d4_app" \
     -H "X-Tenant-Id: ws_a1b2c3d4" \
     -H "X-CF-Device: dev_9f2c41" \
     -d '{
       "userId": "u_8812",
       "consent": true,
       "traits": { "region": "riyadh", "salary": 7200, "signupDaysAgo": 12 }
     }'

No declaration step exists. You do not register a trait before sending it, the first identify call that carries it is enough.

What the traits field does when you send a real set, leave it out, or send something odd:

2. Build a rule from the trait

Inside a segment rule a trait is addressed as customAttributes.<traitKey>. A trait called plan is matched with the field customAttributes.plan.

A rule is either a leaf or a group. Groups nest.

// leaf
{ "field": "customAttributes.plan", "operator": "equals", "value": "gold" }

// group, logicalOperator is "AND" or "OR"
{
  "logicalOperator": "OR",
  "conditions": [
    { "field": "customAttributes.plan", "operator": "equals", "value": "gold" },
    { "field": "customAttributes.salary", "operator": "greater_than", "value": 3000 }
  ]
}

Fields that are not traits carry their own prefix: demographic.*, behavioral.*, device.*, consent.*, location.*, metadata.* and enrichment.*. Note that POST /sdk/identify does not populate demographic.*: identify sets traits, name, email, phone and the device id only.

3. Create the segment

Over HTTP a segment is created with POST /api/v1/segments, using a portal JWT plus X-Tenant-Id, and an admin or editor role. name is 1 to 100 characters and rules needs at least one entry.

$ curl -X POST https://app.contentflow.click/api/v1/segments \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $CF_PORTAL_JWT" \
     -H "X-Tenant-Id: ws_a1b2c3d4" \
     -d '{
       "name": "Riyadh gold",
       "logicalOperator": "AND",
       "rules": [
         { "field": "customAttributes.region", "operator": "equals", "value": "riyadh" },
         { "field": "customAttributes.plan",   "operator": "equals", "value": "gold" }
       ]
     }'

In the dashboard the same thing lives under Audience, Segments.

Five built in trait predicates

Independently of any segment you create, delivery evaluates five fixed predicates against the traits on the device. They are compiled in and are not workspace configurable. You can put these names straight into an instance's seg with no segment created.

4. Target an instance at the segment

The instance field is seg. It holds one segment name as a string. It is not an id, and it is not an array, so an instance targets at most one segment. Set it with a partial update, which means a body carrying only seg changes only the targeting.

$ curl -X PUT https://app.contentflow.click/api/v1/blocks/home_hero/instances/inst_4412 \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $CF_PORTAL_JWT" \
     -H "X-Tenant-Id: ws_a1b2c3d4" \
     -d '{ "seg": "Riyadh region" }'

Requires a portal JWT plus X-Tenant-Id and an admin or editor role. Use title, not name: a body containing name is rejected with a 400. In the dashboard this is the block editor's target dropdown, and new instances default to All users.

How it resolves at delivery

An instance reaches a device when any one of these is true:

• Its seg is one of the device's segment names.
• seg is absent.
• seg is the empty string.
• seg is exactly All users.

The last three all mean untargeted. Matching is byte exact and case sensitive, so VIP and vip are different segments. A device with no segments sees only untargeted instances, which is a valid answer and not an error. A device gets no segments if it never called identify, or if its identify calls never reached granted consent. Delivery also filters on status and on schedule windows, independently of targeting.

Timing

Segment membership is recomputed when a trait value the write proposes actually differs from what is stored, so re-sending identical traits does not trigger a recomputation. A device's segment snapshot then refreshes at most once every 60 seconds. Expect roughly a minute for a targeting change to reach a device, not instant.

5. Prove it landed

Ask the platform which segments an identifier is in, rather than eyeballing a block that happened to render.

$ curl https://app.contentflow.click/api/v1/read/users/u_8812/segments \
     -H "X-CF-Read-Key: rk_live_4f2ab91c77d0e35b8a61c204"

{
  "userId": "u_8812",
  "segmentNames": ["All users", "Riyadh region"]
}

It answers with names, the same strings an instance's seg holds, so your assertion compares like with like and needs no id lookup. The {userId} slot accepts whatever the profile is keyed on, so a device id works there too. The full contract is on the REST API reference.

Glossary

FAQ

Do I need to redeploy my app to change content?

No. Publishing an instance makes it live on the next GET /api/v1/sdk/sync your app performs, with no app release, no store review and nothing to redeploy. That's the whole point. The quickstart shows the call.

Which SDK can I actually use today?

None of them from a package registry. The Web and React Native packages are written and tested but unpublished (npm 404). The Swift package builds and passes its tests but has no public Git URL or SPM tag, so it is a local package only. The Kotlin package is source that has never been compiled. Hand-writing a REST client against the REST API is the intended and supported path on every platform today, not a workaround.

Why is my block empty, or stuck on old content?

Two usual causes. A mismatched key or environment, confirm the key prefix matches the environment you expect. Or a wrong base URL: the retired api.contentflow.click/v1 host still answers 200 with frozen content instead of failing, so an app pointed at it looks healthy while never receiving anything you publish. The only supported base URL is https://app.contentflow.click/api/v1. See Base URL.

Why didn't my SMS / WhatsApp campaign deliver?

The audience likely had zero contacts with phone + consent, or the tenant has no configured Twilio channel. See Campaigns.

Can non-developers manage content?

Yes. Developers define block types in code; anyone can create and edit instances in the dashboard.