Base URL

Every endpoint on this page is relative to a single base:

https://app.contentflow.click/api/v1

All request and response bodies are JSON. Send Content-Type: application/json on every request that has a body.

Telling the two apart

The retired host is not gone, so pointing at it does not produce a clean failure. What it does instead depends on which key you send, and only one of the three outcomes looks like an error:

// app.contentflow.click/api/v1  →  correct: enveloped
{ "success": true, "data": { "blocks": [ … ], "version": "W/\"sync-…\"" } }

// api.contentflow.click/v1      →  RETIRED: bare, no success, no data, no version
{ "blocks": [ … ] }

In code, the check is one line at the top of your response parser: if the body has no success member, you are talking to the retired host. Fail loudly there, in your own client, rather than shipping a build that quietly renders frozen content.

Authentication

There are four credential classes on the platform, and any one call takes exactly one of them. Every /sdk/* delivery call carries up to three headers, and only one of those is actually required. There is no OAuth flow, no token exchange, and no session to keep alive.

The dashboard's management API is the fifth thing you may meet and it is not an SDK credential at all: it takes Authorization: Bearer <portal JWT> together with X-Tenant-Id, and role gates on top. Where that token comes from, how long it lasts, and why there is no service account for it are in where a portal JWT comes from. The response-shape differences are in Portal API differences.

Find the SDK key and the workspace id in Dashboard, Developers, "Your keys". The read key and the write key are rows in that same panel, labelled "Read key" and "Write key", and both are visible to the admin and editor roles only.

X-API-Key and ?key=, the two aliases nobody documented

Both are named in live error bodies, both are supported today, and neither is deprecated. They are narrow, and the narrowness is the point.

{
  "code": "SDK_KEY_IN_QUERY",
  "message": "A ?key= query parameter is only accepted on GET /sdk/stream (SSE). Send the SDK key as the X-CF-Key or X-API-Key header."
}

When more than one key is present, the first one wins

The gateway looks for the SDK key in three places, in this fixed order, and stops at the first one that carries a value:

1. The X-CF-Key request header.
2. Otherwise the X-API-Key request header.
3. Otherwise the ?key= query parameter, which is only accepted on GET /sdk/stream.

The precedence is positional, not quality-based. Nothing compares the candidates, and nothing warns you when they disagree. Send both headers naming different workspaces and X-CF-Key wins silently: the X-API-Key value is never looked at, and no part of the response mentions that a second key was present. Send a malformed X-CF-Key alongside a well-formed X-API-Key and the request fails on the malformed one with 401 INVALID_SDK_KEY. There is no fallback to the second header, because the second header was never a candidate once the first had a value.

The same rule runs downward: when either header carries a value, a stray ?key= in the URL is silently ignored rather than refused.

// both headers, two different invented workspaces: X-CF-Key wins, X-API-Key is ignored
$ curl -i https://app.contentflow.click/api/v1/sdk/sync \
     -H "X-CF-Key: ws_alpha9_app" \
     -H "X-API-Key: ws_beta7_app"

HTTP/1.1 404 Not Found
{ "success": false, "error": { "message": "Tenant not found: ws_alpha9",
                     "code": "TENANT_NOT_FOUND" } }
// the answer names ws_alpha9. Nothing anywhere mentions ws_beta7.

// a malformed X-CF-Key does NOT fall back to a well-formed X-API-Key
$ curl -i https://app.contentflow.click/api/v1/sdk/sync \
     -H "X-CF-Key: nounderscore" \
     -H "X-API-Key: ws_beta7_app"

HTTP/1.1 401 Unauthorized
{ "success": false, "error": { "message": "SDK key is not in the expected <tenantId>_app or <tenantId>_test form",
                     "code": "INVALID_SDK_KEY" } }

Environment comes from the key suffix

A key ending in _test resolves to the test / UAT environment. Anything else resolves to live. That is the only environment signal: a request body can never claim an environment, and no header can flip a live install into test.

How a key resolves to a workspace, and when it is a 401

The workspace id is parsed out of the key by the gateway before any lookup happens, in three steps:

1. A trailing _app is stripped, provided there is at least one character in front of it.
2. Otherwise a trailing _test is stripped, provided there is at least one character in front of it.
3. Otherwise everything before the last underscore is taken, provided that underscore is not the very first character of the key.

Exactly one suffix is stripped, never two, and none of this touches the database. 401 INVALID_SDK_KEY is returned only when all three steps fail to produce a name, which is precisely the case where the key holds no underscore at any position after the first character: either it has no underscore anywhere, or its only underscore is the leading one. Any other key parses into some name, and the answer then turns on whether a workspace by that name exists, which is a 404 TENANT_NOT_FOUND when it does not.

{
  "success": false,
  "error": {
    "message": "SDK key is not in the expected <tenantId>_app or <tenantId>_test form",
    "code": "INVALID_SDK_KEY"
  }
}

The discriminating cases, measured against the live gateway on 16 August 2026. Every key in this table is invented, so you can send any of them yourself without holding a key of your own:

$ curl -i https://app.contentflow.click/api/v1/sdk/sync \
     -H "X-CF-Key: _app"

HTTP/1.1 401 Unauthorized
{ "success": false, "error": { "code": "INVALID_SDK_KEY", … } }

$ curl -i https://app.contentflow.click/api/v1/sdk/sync \
     -H "X-CF-Key: d5a_d5b_d5c"

HTTP/1.1 404 Not Found
{ "success": false, "error": { "message": "Tenant not found: d5a_d5b",
                     "code": "TENANT_NOT_FOUND" } }

Where a portal JWT comes from

The portal JWT is named all over this site as the credential for management routes, so here is where it is issued and what it costs to keep one alive. It is the credential the dashboard itself uses. It is not an SDK key, and it is not interchangeable with one.

The login response is flat, not enveloped

Every other route on this page wraps its payload. This one does not, and a parser that reaches for data will find nothing:

{
  "message": "Login successful",
  "token":   "<JWT>",
  "user": {
    "userId":    "…",
    "tenantId":  "…",
    "roles":     ["…"],
    "email":     "…",
    "name":      "…",
    "workspace": "…"
  }
}

Take the token from token and the workspace id from user.tenantId, and send those two together on every portal call. If X-Tenant-Id disagrees with the token, the request fails with 401 INVALID_CREDENTIALS, which reads like a bad password and is not one.

Logging in, then using the token

// step 1: log in and keep the answer
$ curl -s https://app.contentflow.click/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email": "you@example.com", "password": "<your password>"}' > login.json

$ TOKEN=$(jq -r '.token'          login.json)
$ TENANT=$(jq -r '.user.tenantId' login.json)

// step 2: send both on the portal route
$ curl -s https://app.contentflow.click/api/v1/blocks \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-Id: $TENANT"

// login.json holds a live token for a day. Delete it when you are done.

There is no refresh

Two-step verification, when the account has it enabled

If the account uses two-step verification, POST /auth/login answers 200 with no token. The body carries requires2fa: true, an opaque challenge string, and the list of methods available on that account. A script that reads token without checking requires2fa will silently proceed with an empty credential.

Complete it by posting the challenge and the code to POST /api/v1/auth/2fa/verify:

{
  "challenge": "<the opaque string from the login response>",
  "code":      "<the code from the authenticator>",
  "method":    "totp"
}

The token comes back from that call. The challenge is opaque: pass it back exactly as you received it, do not parse it, and do not construct one. It expires 5 minutes after it is issued, so a script that pauses for human input has to finish inside that window or start again from login.

Refusals a script has to handle

There is no service account for this surface

Anonymous, content-only mode

This is a first-class, supported way to use ContentFlow, and for a long time it was undocumented, which is why it is here near the top rather than buried in a guide. If all you want is to change copy and imagery without shipping an app release, you can have exactly that and collect nothing about anybody.

The three reads are reads. They resolve content for a workspace, not for a person:

$ curl "https://app.contentflow.click/api/v1/sdk/sync?locale=ar" \
     -H "X-CF-Key: ws_a1b2c3d4_app"

HTTP/1.1 200 OK
ETag: W/"sync-ws_a1b2c3d4-3f9c1ab2"

{ "success": true, "data": { "blocks": [ … ], "version": "W/\"sync-…\"" } }

One header. No identify, no device id, no traits, no user id. ETag caching, locale negotiation, collections and the block payload shape all behave exactly as documented everywhere else on this page.

What you give up, and what you get

Upgrading later

Nothing about anonymous mode is a dead end. Adding identify later is additive: the same key keeps working, the same blocks keep arriving, and you begin receiving segment-targeted instances on top. You are not migrating, you are turning something on.

Response envelope

Every endpoint answers with the same two shapes. Parse the envelope once, in one place, and reuse it everywhere.

// success
{ "success": true,  "data": { /* endpoint payload */ } }

// failure
{ "success": false, "error": { /* description of what went wrong */ } }

There is exactly one level of wrapping on every endpoint. Read your payload from data. Treat unknown fields inside data as additive and ignore them, so a future field never breaks your client.

Caching and versioning

The read endpoints (/sdk/sync, /sdk/blocks/:key, /sdk/strings) are conditional-request aware. Honouring that is the difference between a polite client and one that re-downloads your whole catalog every launch.

1. Every read returns an ETag response header holding a weak validator, in the W/"…" form.
2. The same value is repeated as the version field inside the response body, so you can persist it alongside the cached payload without reading headers.
3. Send it back as If-None-Match on the next read. If nothing changed you get 304 Not Modified with an empty body. Keep using your cached copy.

The three read endpoints emit three different validators. They share the weak-ETag form and nothing else. Cache each one against its own endpoint, and never send the validator you got from one read to a different one.

$ curl -i https://app.contentflow.click/api/v1/sdk/sync \
     -H "X-CF-Key: ws_a1b2c3d4_app" \
     -H "X-Tenant-Id: ws_a1b2c3d4" \
     -H "X-CF-Device: dev_9f2c41" \
     -H 'If-None-Match: W/"sync-ws_a1b2c3d4-3f9c1ab2"'

HTTP/1.1 304 Not Modified
ETag: W/"sync-ws_a1b2c3d4-3f9c1ab2"

One thing to know about /sdk/strings: it previously returned a bare sha with no W/"" wrapper, which broke naive validator comparisons. That is being unified to the weak-ETag form documented here. If your client stores whatever it received last and echoes it back verbatim, the change is invisible to you. If your client string-matched on the bare sha, move to verbatim echo.

Locale negotiation

This has caused a real defect in a customer integration, so it is worth thirty seconds of your attention. Two mechanisms are read, two commonly-guessed ones are not.

An ignored mechanism does not fail the request. If you send only ?lang= or only X-CF-Locale, and no supported mechanism at all, the response carries an X-CF-Warning header naming exactly what was ignored, so the mistake is visible instead of silently serving you the base locale with a clean 200.

$ curl -i "https://app.contentflow.click/api/v1/sdk/strings?lang=ar" \
     -H "X-CF-Key: ws_a1b2c3d4_app" \
     -H "X-Tenant-Id: ws_a1b2c3d4" \
     -H "X-CF-Device: dev_9f2c41"

HTTP/1.1 200 OK
X-CF-Warning: unsupported locale parameter "lang" ignored; use ?locale= or the Accept-Language header

When a field has no translation in the requested locale, it falls back to the tenant's source locale rather than returning blank. You never render an empty string because a translator has not finished.

Error behaviour

Failures use the standard failure envelope with a real HTTP status. The status is not always the one you would guess, and that is deliberate.

HTTP/1.1 404 Not Found

{
  "success": false,
  "error": "unknown block"
}

Identify a device or user

It upserts the device behind X-CF-Device, records the consent decision, stores traits, optionally links the device to one of your user ids, and returns the segments the device now resolves to. Those segments decide which targeted blocks sync will hand you.

Request headers

X-CF-Key required, X-CF-Device required here because this call is about a device, Content-Type: application/json required because there is a body. X-Tenant-Id is optional and redundant, exactly as in the auth table: send it and it must agree with the key, omit it and nothing changes.

Request body

Example

$ 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": "user_8812",
       "consent": true,
       "platform": "ios",
       "traits": { "region": "riyadh", "salary": 7200, "signupDaysAgo": 12 }
     }'

{
  "success": true,
  "data": {
    "deviceId": "dev_9f2c41",
    "segments": ["All users", "Riyadh region", "New users (< 30 days)"],
    "consent": true
  }
}

Erase everything stored for one device

The erasure route. It removes the device named by X-CF-Device and the records that hang off it, then reports part by part what it managed to erase. This is the call behind a "delete my data" control in your app. Its answer has to be read rather than glanced at: a 200 is not the only success-looking status it returns, and one field in the body decides what your client is allowed to do next.

Request

Example

$ curl -i -X DELETE https://app.contentflow.click/api/v1/sdk/identify \
     -H "X-CF-Key: <your key>" \
     -H "X-CF-Device: <the device id to erase>"

The success response

{
  "success": true,
  "data": {
    "deviceId":      "…",
    "status":        "deleted",
    "localWipeSafe": true,
    "parts": {
      "device":          { "store": "…", "applied": true, "deleted": 1 },
      "profile":         { "store": "…", "applied": true, "deleted": 1 },
      "kyc":             { … },
      "locationHistory": { … },
      "geofenceEvents":  { … },
      "enrichment":      { … },
      "events":          { "store": "…", "applied": true, "deleted": 42 }
    },
    "remaining": []
  },
  "metadata": { "timestamp": "…" }
}

Single wrap, exactly as on the rest of /sdk/*. Read the outcome from data.

Status codes

Idempotency

The route is fully idempotent, and deliberately does not use 404 to signal anything.

What it erases

One entry in parts per class of data:

What survives, and what that means for a compliance answer

If you are answering a data subject's erasure request, this is the part to read to the end. Everything below is true after a clean 200 with status: "deleted".

• Sibling devices keep their own records. Erasing one device also deletes the shared person-level profile, so traits and segment membership contributed by that person's other devices go with it. The other devices themselves are not deleted: only the device you named is removed, and each sibling keeps its own traits, its own consent state, its own push token and its own link to a user id. To erase a person across their devices, list them with GET /read/users/{userId}/devices and call this route once per device.
• Notification records are not swept by this route. They carry contact details, including recipient email, phone and device token. They are not deleted here; they age out on their own retention window of 30 days.
• Notification preference records and journey enrolment records are not swept by this route either.
• Marketer-level objects are untouched on purpose. Geofence definitions and the like are configuration rather than personal data, so an erasure does not disturb them.
• An erasure record is kept on purpose, after the data is gone. It holds a one-way keyed pseudonym rather than the raw device id, so the fact that an erasure happened survives without the identifier surviving with it.

Operational notes

• The deletes are hard deletes. There is no soft-delete flag, no undo, and no grace period. Once a part reports applied: true, that data is gone.
• The route is opened by the same publishable SDK key your app already ships with, the one used for content delivery, so any code path that can reach the network with your key can reach this route. Gate the call behind your own verified-user flow, and pass it a device id you resolved yourself rather than one taken from arbitrary input.
• A 207 is not a dead end. Keep the device id, retry, and use pendingSince to see how long the outstanding parts have been outstanding.

Consent and the two separate consent decisions are covered in Consent and PDPL.

Register a push token

Files the OS push token against the device, and against the linked user profile when there is one. Call it every launch once the OS hands you a token: tokens rotate, and the last one you registered is the one campaigns will use.

Request body

Example

$ curl -X POST https://app.contentflow.click/api/v1/sdk/register-push \
     -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 '{
       "token": "e9f1c0a2b7d4…",
       "platform": "ios",
       "provider": "apns",
       "userId": "user_8812"
     }'

{
  "success": true,
  "data": {
    "deviceId": "dev_9f2c41",
    "userId": "user_8812",
    "registered": true,
    "provider": "apns"
  }
}

Sync every live block

The main read. Returns every live block instance visible to this device, already filtered by the device's segments and resolved into the locale you asked for. One call per launch, plus a refresh when the stream tells you something changed.

Query parameters

Conditional request

Send If-None-Match with the last version you stored. A 304 Not Modified with an empty body means your cache is current.

Example

$ curl "https://app.contentflow.click/api/v1/sdk/sync?locale=ar" \
     -H "X-CF-Key: ws_a1b2c3d4_app" \
     -H "X-Tenant-Id: ws_a1b2c3d4" \
     -H "X-CF-Device: dev_9f2c41"

ETag: W/"sync-ws_a1b2c3d4-3f9c1ab2"

{
  "success": true,
  "data": {
    "blocks": [
      {
        "key": "discovery_card",
        "name": "Discovery card",
        "screen": "Home screen",
        "instanceId": "inst_7c31",
        "segment": "high_value",
        "version": 7,
        "values": {
          "#header_image": "https://cdn.example.com/hero.png",
          "#title_main": "أهلاً بك"
        },
        "fields": [
          { "tag": "#header_image", "type": "image" },
          { "tag": "#title_main",   "type": "text" }
        ]
      }
    ],
    "version": "W/\"sync-ws_a1b2c3d4-3f9c1ab2\""
  }
}

See block payload shape for how the values and fields members fit together, and why you must address fields by tag.

Resolve one block by key

Same resolution rules as sync, scoped to a single block type key. Useful when one screen needs one block and you do not want to hold the whole catalog in memory. It is conditional-request aware in exactly the same way.

Path and query

Example

$ curl https://app.contentflow.click/api/v1/sdk/blocks/home_hero \
     -H "X-CF-Key: ws_a1b2c3d4_app" \
     -H "X-Tenant-Id: ws_a1b2c3d4" \
     -H "X-CF-Device: dev_9f2c41"

An unknown key is a 404 with the standard failure envelope. It is not an empty 200, so a typo in a block key fails loudly.

{ "success": false, "error": "unknown block" }

Fetch approved translations

Returns the tenant's translation catalog for one locale as a flat key to string map. Only review-approved translations ship. Anything still in draft or machine-translated falls back to the tenant's source locale, so your UI never renders a half-translated screen.

Query parameters

Example

$ curl "https://app.contentflow.click/api/v1/sdk/strings?locale=ar" \
     -H "X-CF-Key: ws_a1b2c3d4_app" \
     -H "X-Tenant-Id: ws_a1b2c3d4" \
     -H "X-CF-Device: dev_9f2c41"

ETag: W/"strings-ws_a1b2c3d4-b71e04d9"

{
  "success": true,
  "data": {
    "locale": "ar",
    "strings": {
      "checkout.title": "إتمام الشراء",
      "checkout.cta":   "تأكيد"
    },
    "smartKeys": ["checkout.title"],
    "version": "W/\"strings-ws_a1b2c3d4-b71e04d9\""
  }
}

Send engagement events

Batch your engagement signals and post them together. This is the endpoint that makes the dashboard's numbers real. Batch on a timer or on backgrounding, not one request per tap.

Event types

Request body

Example

$ curl -X POST https://app.contentflow.click/api/v1/sdk/events \
     -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 '{
       "events": [
         { "type": "impression", "instanceId": "inst_7c31" },
         { "type": "cta_click",  "instanceId": "inst_7c31" }
       ],
       "context": { "sessionId": "sess_4d20", "platform": "ios" }
     }'

{
  "success": true,
  "data": { "accepted": 2, "dropped": 0 }
}

Send identity events

Where /sdk/events records what happened to a block, this records what happened to a person. It links the device to a user, upserts the profile behind that user, and is what makes the account show up in Audience.

Request body

Example

$ curl -X POST https://app.contentflow.click/api/v1/sdk/track-event \
     -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 '{
       "username": "user_8812",
       "eventType": "sign_up",
       "fullName": "Sara A.",
       "email": "sara@example.com",
       "device": { "model": "iPhone15,2", "osType": "ios", "appVersion": "3.4.1" }
     }'

{
  "success": true,
  "data": {
    "deviceId": "dev_9f2c41",
    "segments": ["All users", "Riyadh region"],
    "consent": true
  }
}

Set per-channel consent

Records what the user actually agreed to, channel by channel. This is the endpoint behind your notification-preferences screen. It is deliberately independent of the device-level consent flag on identify, see consent and PDPL for why.

Request body

Example

$ curl -X POST https://app.contentflow.click/api/v1/sdk/consent \
     -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 '{
       "username": "user_8812",
       "channels": {
         "push": true,
         "sms": false,
         "whatsapp": false,
         "email": true,
         "locationTracking": false,
         "marketing": true
       }
     }'

{
  "success": true,
  "data": {
    "deviceId": "dev_9f2c41",
    "username": "user_8812",
    "channels": { "push": true, "sms": false, "email": true, "marketing": true }
  }
}

Live updates over SSE

A long-lived text/event-stream connection that tells you when content changed. It is a signal, not a delivery channel: when an event arrives, call /sdk/sync again. Do not try to patch your local state from the event payload.

Example

$ curl -N https://app.contentflow.click/api/v1/sdk/stream \
     -H "Accept: text/event-stream" \
     -H "X-CF-Key: ws_a1b2c3d4_app" \
     -H "X-Tenant-Id: ws_a1b2c3d4" \
     -H "X-CF-Device: dev_9f2c41"

: connected

id: 41
event: block.published
data: {"key":"home_hero"}

: ping

Lines beginning with : are comments: one on connect, then a periodic keep-alive. Ignore them, but do use them to detect a dead connection.

Resuming

Track the id of the last frame you processed. On reconnect send it back as the standard Last-Event-ID header, or as ?lastEventId= if your HTTP client cannot set headers on an event source. Buffered events after that id are replayed, so a dropped connection does not mean missed changes.

Event names

Block-changing events are named block.updated, block.published, block.paused, and block.targeted. Treat any block.* event as a single instruction to re-sync, debounce a burst of them into one call, and ignore names you do not recognise so new event types cannot break your client.

The read surface: ask what a device actually resolved to

Delivery answers "what should this device see". The read surface answers the question you need in a test, a support ticket, or a CI gate: what did the platform actually decide about this identifier. It is a separate surface with its own credential, and it is live today.

There are exactly three. No fourth route exists under this prefix, and nothing here is paginated, filtered, or searchable.

The credential

One header, X-CF-Read-Key. No portal JWT and no X-Tenant-Id: the workspace is resolved from the read key itself, so neither of those headers has anything to contribute on this surface.

Every other path under the prefix is a 404, and that is correct

Only the three paths above are routes. /api/v1/read, /api/v1/read/users/{id}, /api/v1/read/segments and everything else under the prefix are not routes: they answer 404 NOT_FOUND with a Cannot GET … message, the framework's own reply to an unmatched path.

The envelope is the standard one

{
  "success": true,
  "data": { /* endpoint payload */ },
  "metadata": { "timestamp": "2026-08-14T09:12:44.108Z" }
}

Single wrap, exactly as on /sdk/*. Read your payload from data, and treat metadata as informational.

What goes in the {userId} slot

{userId} accepts whatever the profile is keyed on. That is normally your own stable user id, the one you sent to identify. A device id works in that slot too, because an anonymous consented device gets a profile keyed on its device id. So a support script that only has a device id is not stuck.

List every device behind one identifier

Answers "how many devices has this person actually got, and is the one I am debugging among them". This is the call that catches a fragmented identity: a client regenerating its device id per launch shows up here as a pile of near-identical devices under one user.

Request

Response

Example

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

{
  "success": true,
  "data": {
    "userId": "user_8812",
    "devices": [ /* one device record each, tokens stripped */ ]
  },
  "metadata": { "timestamp": "2026-08-14T09:12:44.108Z" }
}

Errors

Fetch one device and its profile

The single-device view. Use it when you have a device id from a crash report, a support ticket, or your own logs, and you want to know whether the platform has ever heard of it and what it knows.

Request

Response

Example

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

{
  "success": true,
  "data": {
    "device": { /* device record, tokens stripped */ },
    "profile": {
      "customAttributes": { "region": "riyadh" },
      "consent": true,
      "appVersionSnapshot": "3.4.1"
    }
  },
  "metadata": { "timestamp": "2026-08-14T09:12:44.108Z" }
}

Errors and the one state that looks like an error

Read the segments an identifier resolves to

The one call that turns "did my targeting work" from an argument into an assertion. It returns the segment names the platform currently resolves for that identifier.

Request

Response

Example

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

{
  "success": true,
  "data": {
    "userId": "user_8812",
    "segmentNames": ["All users", "Riyadh region"]
  },
  "metadata": { "timestamp": "2026-08-14T09:12:44.108Z" }
}

Two answers that look the same and are not

Verify that targeting actually worked

After you call identify, call GET /api/v1/read/users/{id}/segments and assert the segment name you expected is in segmentNames. That is the CI-checkable proof that targeting landed, and it is a real assertion rather than a screenshot of a block that happened to render.

1. Call /sdk/identify with the device id, consent, and the traits your segment targets on.
2. Call GET /api/v1/read/users/{id}/segments with your read key.
3. Assert the expected name is present, for example "Riyadh region". Compare on the name string, and compare it exactly.

Block payload shape

Every block, whether it came from sync or blocks/:key, has the same shape. Content and schema arrive as two separate members, values and fields. Understanding that split is the single most useful thing on this page.

{
  "key":        "discovery_card",
  "name":       "Discovery card",
  "screen":     "Home screen",
  "instanceId": "inst_7c31",
  "segment":    "high_value",
  "version":    7,

  // the content, keyed by tag
  "values": {
    "#header_image": "https://cdn.example.com/hero.png",
    "#title_main":   "Hello"
  },

  // the declared schema, one entry per field
  "fields": [
    { "tag": "#header_image", "type": "image" },
    { "tag": "#title_main",   "type": "text" }
  ]
}

values and fields, and why they are separate

values is a map from tag to content. fields is the block type's declared schema, one entry per field, carrying that field's type. They are joined by the tag.

The reason for the split is that it lets you render by declared type instead of guessing from the tag name. A tag called #header_image is a naming convention, and a marketer is free to rename it. Its type of image is a contract. Look the tag up in fields, switch on the type you find, then pull the content out of values. Do not infer that a field is an image because its tag ends in _image, and do not assume every value is a string.

Field types

The type comes from the matching entry in fields. The value it describes lives in values under the same tag.

Collections: a field whose value is a list of blocks

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. Delivery resolves the references and inlines each eligible card in full under the collection's tag, so there is no second request and no card model to learn.

A card is a block. It carries its own instanceId, its own segment, its own numeric version, its own values and its own fields, which is exactly why this shape exists: every card gets targeting, scheduling, approval, A/B variants and analytics because those already belong to an instance.

{
  "key":        "reading_carousel",
  "name":       "Reading carousel",
  "screen":     "Home screen",
  "instanceId": "carousel-7df3",
  "segment":    "All users",
  "version":    4,

  "values": {
    "#heading": "Recommended for you",

    // a collection value is an array of WHOLE BLOCKS
    "#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" },
        "fields": [ { "tag": "#title", "type": "text" },
                    { "tag": "#image", "type": "image" } ]
      }
    ]
  },

  "fields": [
    { "tag": "#heading", "type": "text" },
    { "tag": "#slides",  "type": "collection",
      "allowedBlockKeys": ["reading_card"], "minItems": 0, "maxItems": 20 }
  ]
}

A card is parsed by the same code that parses a top-level block, in every ContentFlow SDK and, we would suggest, in yours. Recursing your existing block parser one level is the whole integration.

Detecting a collection

Look the tag up in fields and check for type: "collection". Do not infer it from the value being an array, unless you are handling a payload with no schema at all: an absent or partial fields array is the only case where "an array carrying block-shaped entries" is a reasonable fallback, and that is precisely what the ContentFlow SDKs do.

allowedBlockKeys, minItems and maxItems on the schema entry are authoring constraints the server validates writes against. They are not a filter you are expected to apply, and the SDKs deliberately ignore them when decoding. An unrecognised card key should still decode as an ordinary block.

Which cards arrive, and in what order

Caching

The /sdk/sync validator is a SHA-256 digest over the entire delivered block array, computed recursively after resolution, so it already covers every inlined card's instanceId, numeric version, localized values and field schema, and the collection order that survived filtering. Editing a card, reordering slides, or a card becoming eligible or ineligible therefore moves the validator even though no wrapper was edited. Nothing changes for your client: store the validator, echo it back on If-None-Match, treat it as opaque. See Caching and versioning.

Events

Track a card exactly as you track any block: send the card's own instanceId to /sdk/events. The metric owner is the card, never the wrapper, so a card reused in three carousels reports against itself in all three. Send the wrapper's instance id, the collection tag and the card's position as extra dimensions if you want a placement breakdown, but they are context, not ownership.

Authoring constraints, for the write side

These apply to the management API rather than to /sdk/*, but they explain what you will and will not see on the wire.

• A collection stores an ordered array of instance id strings. Duplicates and self-references are rejected. allowedBlockKeys is required and is matched against immutable definition keys, never display names.
• 50 references per collection is the platform hard limit, applied even when maxItems is omitted. A stricter maxItems wins.
• minItems bounds what an author may save. It is not a promise about how many cards a device receives after filtering.
• Deleting a referenced instance answers 409 with code: "instance_referenced" and a references array of { wrapperInstanceId, fieldTag }. Archiving a referenced block definition answers 409 with the same code and a references array of { wrapperBlockKey, fieldTag }. Pausing and disabling stay available, because delivery already treats a paused card as absent.
• A definition change that would strand live references, such as dropping a key from allowedBlockKeys or re-keying a collection field, is rejected with 400 rather than orphaning them.
• Payload size is enforced at publication, not at delivery: a wrapper that would exceed the sync payload limit, measured at its worst case across every stored reference and every locale, is rejected with 400 and code: "collection_payload_too_large". A runtime backstop truncates trailing cards if an oversized wrapper reaches delivery anyway, so a device is never handed an unbounded body.

The block-type side of this, including how to register a wrapper and a card, is on Blocks & fields.

Portal API differences

Everything else on this page is the delivery API, the /sdk/* surface your app calls with a publishable key. The portal API is the management surface the dashboard itself uses: JWT-authenticated, and where content is created and edited rather than read. Most integrators never touch it. If you are seeding content from a CMS, a build script, or a migration, you will.

They share a base URL and share almost nothing else. Three differences have each cost somebody a debugging session.

1. The portal API double-wraps its envelope

/sdk/* wraps once: your payload is at data. The portal API wraps twice: the gateway envelope carries the downstream service's envelope, so your payload is at data.data.

// GET /api/v1/sdk/sync            single wrap
{ "success": true, "data": { "blocks": [ … ] } }

// GET /api/v1/blocks              DOUBLE wrap
{ "success": true, "data": { "success": true, "data": [ … ] } }

Nothing in the URL warns you which one you are about to get. Do not share one response parser between the two surfaces without a deliberate unwrap step. A read of the form (body.data.data ?? body.data) is correct against both, and is what we would write ourselves.

2. Updating an instance is PUT. PATCH returns 404

There is no PATCH route for a block instance. PATCH /api/v1/blocks/:key/instances/:id is not a rejected update, it is a route that does not exist, so it answers 404, which reads exactly like a wrong instance id and sends you looking in the wrong place. Use PUT.

3. Values are written by field id and read back by tag

This asymmetry is real, it is not going to be papered over silently, and an integrator that both writes and reads has to hold a mapping.

An id is not derived from the tag, and it is not guessable when you did not choose it: register a block type without supplying an id for a field and the server generates a UUID for it. So fetch the block definition, build a tag → id map from its fields, and key your writes with that. Re-read the definition when a marketer may have added a field, because a new field brings a new id.

The block definition shape, including where fields[].id appears, is on Blocks & fields.

Consent and PDPL

Consent is enforced on our servers, not in the client, and it defaults to false. You do not have to trust an SDK to behave, and you do not have to build the enforcement yourself.

• Consent defaults to false. A device that has never granted consent is treated as unconsented, and nothing you send changes that except an explicit grant.
• Content still syncs while consent is false. Your app is not broken for a user who declined analytics. Blocks, strings, and locales are all delivered normally.
• Only analytics events are dropped, and they are dropped server side. A client that keeps sending events while unconsented cannot cause a recording.

Two different consents, on purpose, in two different places

They are independent because they answer different questions. A user can be happy to be measured but refuse SMS, or accept push notifications while declining analytics. Collapsing the two into one switch would make one of those users impossible to represent honestly.

Erasure is a separate obligation, and a separate route

Consent answers what you may collect. It says nothing about deleting what you already have. That is DELETE /sdk/identify, which erases one device and the person-level records behind it, and reports part by part what it managed to remove.

Three things about it belong in a compliance answer rather than in an integration guide, so read the full section before you write one:

• It erases the device you name and the shared profile, but not that person's other devices. Erasing a person means listing their devices on the read surface and calling the route once per device.
• Some records are not swept by it, including notification records carrying contact details, which age out on a 30 day retention window instead. The full list of what survives is in that section.
• The erasure is recorded, not enforced. A later identify or track-event with the same identifier creates a fresh profile. Nothing suppresses the identifier afterwards, so staying erased is something your own client has to do by not sending it again.

The route map: every route, and the credential that opens it

The endpoints with a full section on this page cover what an app normally needs, but they are not the whole delivery surface: /sdk/* holds eighteen routes. A full integration usually also touches a route or two from the lists below, so here they all are in one place. Paths are relative to https://app.contentflow.click/api/v1.

Delivery, credential X-CF-Key

Eighteen routes. Ten have a full request and response contract on this page, linked below. The other eight are listed here with their method, path and credential, and nothing more, because their shapes are not documented on this page yet: listing them without inventing a contract is the honest version.

Write, credential X-CF-Write-Key

The write key opens exactly three routes and no others. All three authenticate on the key alone: no portal JWT, no X-Tenant-Id, because the workspace comes from the key.

Which cards route to use, and the one that archives

Read, credential X-CF-Read-Key

Management, credential portal JWT

These take Authorization: Bearer <portal JWT> together with X-Tenant-Id, and every one of them is gated to the admin or editor role, with a 403 FORBIDDEN_ROLE otherwise. They double-wrap their envelope, so read from data.data. See Portal API differences for the envelope, and where a portal JWT comes from for how to obtain one, how long it lasts, and why there is no service account for this surface.

Setting an instance's targeting

PUT /api/v1/blocks/:key/instances/:id takes a partial update, and the field that sets targeting is seg: a single segment name string, the same name the read surface returns.

// aim this instance at one segment, by name
{ "seg": "Riyadh region" }

// make it untargeted again: either of these
{ "seg": null }
{ "seg": "" }

The full targeting rules, including how a name is matched and what happens when several instances compete, are in the targeting reference.

Writing your own client

One required header, one envelope, plus a separate write surface on X-CF-Write-Key and a separate read surface on X-CF-Read-Key that an app never calls. A normal app touches a handful of the eighteen /sdk/* routes and nothing else; all eighteen, and every other route this page knows about, are in the route map. Before you write anything, decide which of two clients you are building, because the answer changes what you collect and what you have to declare.

Decide first: content-only, or personalized

Content-only is not a degraded mode or a trial tier, and you are not locked into it: identify can be added later without changing anything else. Choose it if it covers what you need, and read the tradeoffs before you decide it does not.

Order of operations, personalized client

1. Generate and persist a device id, once, on first launch. See below. A content-only client skips this step and every step that depends on it.
2. Identify. Call /sdk/identify with the device id, the user's consent decision, and any traits you target on. This is what resolves the device's segments.
3. Then sync. Call /sdk/sync and store both the payload and its version. Syncing before identify is legal and returns real content, but it returns the untargeted view, so if you meant to target, do this in order rather than debugging an unexpectedly plain screen later.
4. Then send events. Post engagement to /sdk/events in batches, using the instanceId from the blocks you rendered.
5. Optionally, subscribe. Open /sdk/stream and re-sync when a block.* event arrives. Polling with If-None-Match is a valid alternative.

Persisting the device id

This section applies only to a personalized client. If you are building content-only, there is no device id to persist, which is the point.

The device id is the identity everything else hangs off: segments, consent state, and the push token are all keyed to it. Getting this wrong is the most expensive mistake available on this page, because it silently fragments one user into many.

• Generate a UUID on first launch. Do not derive it from a hardware identifier, an advertising id, or anything the OS may rotate or refuse you.
• Store it where it survives app restarts and updates: Keychain on iOS, SharedPreferences or DataStore on Android, localStorage on web.
• Send the same value as X-CF-Device on every call, forever, including calls made before the user logs in.
• Never regenerate it per launch, per session, or on logout. A fresh id is a fresh anonymous device with no consent and no segments.

Checklist before you ship