Schema Discovery Endpoint

Authenticate with an OAuth 2.0 bearer token — refer to Kahua API Authentication for provisioning credentials and requesting a token.

/schemas then has two authorization requirements beyond a valid token:

1. API User group membership. The calling account must belong to the API User group. On this endpoint a non-member receives 401, not 403 — the group is checked earlier in the pipeline here than on the feeds.

2. Data Feed license. The calling account must hold an assigned, valid kahua_DataFeed license. This is a purchased add-on and is checked per caller — every integration account needs its own seat. Missing it returns 403.

Troubleshooting a 401 from /schemas. Because "not in the API User group" also surfaces as 401 on this endpoint, a 401 here is not reliable evidence that your token is invalid. Confirm the account is in the API User group before troubleshooting the token itself.

1
2
3
4
GET https://{envName}service.kahua.com/api/v1/projects/{projectId}/apps/schemas
    Authorization: Bearer <token>
    Accept-Encoding: gzip, br      (optional; honored if present)
    If-None-Match: "<etag>"        (optional; enables 304 Not Modified)

Path Parameters

Query Parameters

No paging. Schema metadata for a domain is small and bounded, so the full document comes back in one response. entityDefNames is a convenience filter, not a pagination mechanism.

This endpoint's URL differs from the two feeds: it is scoped by projectId and lives under /api/v1/..., whereas the feeds are scoped by domainKey and live under /v1/....

Save the ETag and send it back as If-None-Match on later calls. An unchanged schema returns 304 Not Modified with no body, which is the cheap and correct way to poll for schema drift.

/schemas is not subject to the shared rate window that governs /entityfeed and /changefeed.

Status 200 OK.

EntityDefSchema

FieldInfo

dataType reports Kahua's internal field-type names, emitted as-is. Expect values such as Text, Number, Boolean, Date, AutoNumber, Selector, and Entity.

These are internal type names, not a normalized or standardized type vocabulary, and the set is open-ended — new apps may introduce type names not listed here. Map them to your warehouse's types with a lookup table that has a sensible default for unrecognized values, rather than assuming a fixed, closed enumeration.

The one value with structural meaning is Entity: it marks a reference to another record. The feeds return such a field as the referenced record's numeric entity ID, and linkedEntityDefName tells you which entityDef that ID belongs to — so you can model it as a foreign key and load the target entityDef separately.

Property names are camelCase, and null values are left out of the JSON entirely rather than written as "field": null. In practice this means templateName and linkedEntityDefName simply will not appear when they have no value. Write your parser to treat a missing key as null.

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
45
46
47
48
49
{
    "projectId": 1001,
    "schemas": [{
            "entityDefName": "kahua_AEC_RFI.RFI",
            "appName": "kahua_AEC_RFI",
            "schemaName": "RFI",
            "label": "RFI",
            "templateName": "kahua_AEC_RFI",
            "fields": [{
                    "name": "Subject",
                    "label": "Subject",
                    "dataType": "Text",
                    "isRequired": true,
                    "isReadOnly": false,
                    "isIdentity": false
                }, {
                    "name": "Number",
                    "label": "Number",
                    "dataType": "AutoNumber",
                    "isRequired": false,
                    "isReadOnly": true,
                    "isIdentity": false
                }, {
                    "name": "Status",
                    "label": "Status",
                    "dataType": "Selector",
                    "isRequired": false,
                    "isReadOnly": false,
                    "isIdentity": false
                }, {
                    "name": "DueDate",
                    "label": "Due Date",
                    "dataType": "Date",
                    "isRequired": false,
                    "isReadOnly": false,
                    "isIdentity": false
                }, {
                    "name": "Originator",
                    "label": "Originator",
                    "dataType": "Entity",
                    "isRequired": false,
                    "isReadOnly": false,
                    "isIdentity": false,
                    "linkedEntityDefName": "kahua_PeopleManager.kahua_Contact"
                }
            ]
        }
    ]
}

Note that templateName and linkedEntityDefName are absent from the entries where they have no value — that is the expected shape, not a truncated example.

/schemas lists exactly the entityDefs and fields that an /entityfeed or /changefeed payload could contain — the same exclusion rules apply to all three, so discovery never promises data the feeds cannot deliver.

Not listed as entityDefs: Kahua infrastructure record types, which carry no business data, and record types belonging to internal Kahua apps.

Not listed as fields: encrypted fields, entity lock state, file attachments, image attachments, GUIDs, and raw XML — none of which carry consumer-usable values in a feed.

Not represented at all: parent/child ownership. schemas[] is a flat list. A child record type appears as its own top-level entry exactly like any other entityDef, and a parent carries no list of its children. The parent→child ownership relationship is not expressed anywhere in this response and cannot be reconstructed from it. If your warehouse model needs that hierarchy, derive it from your own knowledge of the apps involved.

Apps you cannot access are omitted. An app you cannot open at the given projectId is left out of the full-domain response, and returns 404 if you name it explicitly — so this endpoint cannot be used to enumerate apps you have no rights to.

Response Body

Codes

Full domain schema

1
2
3
curl -X GET 'https://service.kahua.com/api/v1/projects/1001/apps/schemas' \
    -H 'Authorization: Bearer <token>' \
    -H 'Accept-Encoding: gzip, br'

Only specific entityDefs

1
2
curl -X GET 'https://service.kahua.com/api/v1/projects/1001/apps/schemas?entityDefNames=kahua_AEC_RFI.RFI,kahua_AEC_DailyReport.DailyReport' \
    -H 'Authorization: Bearer <token>'

Conditional revalidation — check for schema drift cheaply

1
2
3
4
5
curl -X GET 'https://service.kahua.com/api/v1/projects/1001/apps/schemas' \
    -H 'Authorization: Bearer <token>' \
    -H 'If-None-Match: "b3Jpb2xl…="'

# → 304 Not Modified   (schema unchanged; no body returned)

1. From the response, pick the entityDefName values your warehouse needs.

2. For each, pick the name values from its fields[] — that list becomes your attribute projection.

3. Note any linkedEntityDefName targets: if you want details of a referenced record rather than just its ID, add that entityDef to your load list too.

4. Proceed to /entityfeed for the initial load.

Save the ETag. Re-checking it with If-None-Match after an app upgrade is the supported way to detect that your projections need revisiting.

• Data Feed — Overview and Getting Started

• Entity Feed — /entityfeed

• Change Feed — /changefeed