Change Feed Endpoint

Beyond a valid token, the calling account must:

1. Belong to the API User group — otherwise 403.

2. Hold an assigned Data Feed license (kahua_DataFeed) — a purchased add-on, checked per caller, so every integration account needs its own seat. Otherwise 403.

This endpoint accepts Bearer, Basic, or Session authentication.

1
2
3
4
POST https://{envName}service.kahua.com/v1/domains/{domainKey}/changefeed
    Authorization: Bearer <token>
    Content-Type:  application/json
    Accept-Encoding: gzip, br      (optional; honored if present)

Path Parameters

Query Parameters

None

This endpoint uses POST because it takes a structured JSON query in the request body. It makes no changes to your Kahua data.

Header-only by default. If you omit attributes — or omit a key for a particular entity type — entries for that type come back with no data. This keeps payloads small and forces integrations to be explicit about what they consume. Most integrations should supply attributes.

The field names in attributes are the name values from /schemas.

Example request

1
2
3
4
5
6
7
8
9
10
11
{
    "lastMarker": 10247,
    "pageSize": 500,
    "projectId": 5001,
    "entityDefNames": ["kahua_AEC_RFI.RFI", "kahua_AEC_DailyReport.DailyReport"],
    "attributes": {
        "kahua_AEC_RFI.RFI": ["Number", "Subject", "Status", "DueDate"],
        "kahua_AEC_DailyReport.DailyReport": ["Number", "Date", "Shift", "StatusWorkflow"]
    },
    "consolidateChanges": true
}

Status 200 OK.

There is no data payload for an entry when:

• the action is Delete;

• the record no longer exists at the time of your request;

• you supplied no attribute projection for that entity type.

Treat a missing data key and a data value of null as equivalent — check for "absent or null" rather than requiring the key.

Null values are omitted from the JSON, not written as "field": null. This applies to envelope fields such as recommendedPageSize, and to data when there is none.

The exception is inside the data map: a field that exists on the record but has no value is serialized as "Field": null.

Never detect end-of-data by inspecting changes or a null field. Use hasMore.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
    "marker": 10251,
    "currentMarker": 10420,
    "hasMore": true,
    "count": 3,
    "changes": [{
            "action": "Add",
            "entityDef": "kahua_AEC_RFI.RFI",
            "entityId": 88012,
            "entityInstanceId": 1,
            "partitionId": 5001,
            "markerTime": "2026-04-20T14:22:03Z",
            "markerId": 10249,
            "data": {
                "Number": "0042",
                "Subject": "Foundation waterproofing detail",
                "Status": "Open",
                "DueDate": "2026-05-15T00:00:00Z"
            }
        }, {
            "action": "Edit",
            "entityDef": "kahua_AEC_RFI.RFI",
            "entityId": 88010,
            "entityInstanceId": 3,
            "partitionId": 5001,
            "markerTime": "2026-04-20T15:05:11Z",
            "markerId": 10250,
            "data": {
                "Number": "0040",
                "Subject": "Structural steel spec clarification",
                "Status": "Answered",
                "DueDate": null
            }
        }, {
            "action": "Delete",
            "entityDef": "kahua_AEC_DailyReport.DailyReport",
            "entityId": 77501,
            "entityInstanceId": 2,
            "partitionId": 5001,
            "markerTime": "2026-04-20T16:12:30Z",
            "markerId": 10251
        }
    ]
}

The Delete entry carries no data key — that is the expected shape. "DueDate": null on the Edit entry is a real value: the field exists and is empty.

data is the state now, not the state at the time of the change

This is the single most important semantic on this endpoint.

data is read when you make the request, not captured when the change happened. So:

• An Edit entry's data is the record's current state — which may reflect later edits that you have not yet received as their own entries.

• If a record was changed and then deleted before you polled, its earlier Add / Edit entries in this page come back with no data.

The Change Feed is therefore an upsert stream, not a historical audit log. It reliably tells you which records changed and in what order; it does not let you reconstruct each intermediate version. If your warehouse needs point-in-time history, derive it from the sequence of markers you receive — do not expect the API to replay old field values.

Paging and the cursor

• The cursor is exclusive: a request returns markers strictly greater than lastMarker.

• Marker IDs are domain-wide and always increasing. As long as your cursor advances, you never skip or duplicate entries.

• Persist marker after every page, not just at the end of a run. If your process dies mid-page-run, you resume from the last persisted marker and lose nothing.

A page can be empty while more data follows

Excluded record types are filtered out after the page is cut, and the cursor always advances to the highest raw marker in the page. In a domain with a lot of internal system activity, a page can therefore return fewer entries than pageSize, or none at all, while hasMore is still true.

Never stop paging because changes is empty. Continue until hasMore is false. You are fully caught up when hasMore is false and marker == currentMarker.

How internal operations map to actions

Note that a move between projects arrives as an Edit — check partitionId on every entry, not just on Add.

Reference fields

Fields holding references to other records are returned as the referenced record's numeric entity ID:

1
{ "Originator": 48291035, "Vendor": 77203841 }

Collections of references are returned as an array of IDs:

1
{ "Items": [12345, 12346, 12347] }

Rules:

• An unset reference is null.

• A reference to a deleted record still returns the stored ID — the reference is not cleared. Your warehouse may hold a foreign key to a row you have deleted; handle it.

• Dot-path traversal is not supported. You cannot request Vendor.Company. Projections cover only the direct fields of the changed record. To get referenced records' details, sync their entityDef too and join in your warehouse.

With consolidateChanges: true, multiple changes to the same record within a single page collapse into one net-change entry. This reduces the volume your warehouse processes when records are edited repeatedly.

Key behaviors:

• Add → Delete: the record was created and destroyed inside the page. It is omitted entirely — your warehouse never learns it existed, which is correct.

• Delete → Add/Edit: the record was restored or re-created. Delivered as Edit.

• The consolidated entry carries the highest markerId, markerTime and partitionId of the group, and the highest entityInstanceId.

• Consolidation is page-scoped. A record changed across a page boundary appears in both pages, once each. Your writes must be idempotent regardless.

• count reflects the post-consolidation entry count; marker is still the highest raw marker ID.

Consolidation is recommended for most warehouse integrations. Leave it off only if you need every individual change event.

Kahua infrastructure record types, which carry no business data, and record types belonging to internal Kahua apps are automatically excluded from unfiltered responses. Refer to /schemas as the authoritative list of what is available to you.

Escape hatch: naming an entity type explicitly in entityDefNames bypasses exclusion for that type. Use this only when you have a specific, confirmed need for an internal record type.

• Always filter when you can. Pass entityDefNames and/or projectId — unfiltered domain-wide calls are the most expensive shape and should be rare.

• Rate limit: by default 60 requests per minute, per calling account, per domain — shared with /entityfeed. A background initial load draws on the same budget as your polling.

• Compression: send Accept-Encoding: gzip, br. On pageSize=1000 responses this typically gives 5–10× size reduction.

• Honor recommendedPageSize. When the server returns it, your request took long enough that a smaller page will be more reliable.

• Delete entries are cheap — they require no record lookup.

Response Body

Error codes 410 and 429 include additional properties described in the error codes table.

Codes

Recovering from 410 MarkerExpired

Your stored cursor is older than the retention window. You have three options, and only one of them leaves you with correct data:

The way to avoid 410 entirely is to poll on a schedule comfortably inside the retention window and to alert on your integration falling behind.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
1. Start from your initial load's marker
POST /v1/domains/MagsevenBuilders/changefeed
{ "lastMarker": <asOfMarker from /entityfeed>, "pageSize": 1000,
"entityDefNames": [...], "attributes": {...}, "consolidateChanges": true }

2. Drain
→ Apply changes as upserts / deletes
→ Persist the returned `marker` after EVERY page
→ Keep calling while hasMore == true, even if a page returned zero entries
→ Caught up when hasMore == false AND marker == currentMarker

3. Poll on your interval (e.g. every 24 hours)
→ Same request, with your stored marker as lastMarker
→ Repeat step 2

4. On 410 MarkerExpired
→ Re-run /entityfeed, then resume from its asOfMarker

5. On 429 RateLimited
→ Sleep retryAfterSeconds, then retry the same request

6. If recommendedPageSize is returned
→ Use it as pageSize on the next call

Requirements for a correct consumer:

• Writes must be idempotent — the same change can legitimately arrive twice.

• Order matters: apply entries in markerId order, and never process a later page before an earlier one.

• Persist the marker transactionally with the data you applied, so a crash cannot advance the cursor past unwritten rows.

• Data Feed — Overview and Getting Started

• Schema Discovery — /schemas

• Entity Feed — /entityfeed