The Cranium Public REST API uses cursor-based pagination on most list endpoints. For these endpoints, the cursor encodes "all records updated after this point," which is exactly the semantic needed for incremental sync. On most list endpoints, storing the cursor between runs and replaying it on the next poll returns only what has changed since the last successful sync, with no gaps and no duplicates. The Bill of Materials feeds, the received AI Card feeds and Arena All Models do not report every change. See Keeping Feed, Received and All Models Data Complete below. A few endpoints return their full result in a single response instead. See Endpoints Without Pagination below.
This article covers how pagination works, how to perform an initial full sync, how to perform incremental syncs on subsequent runs, how to keep feed, received and All Models data complete, and how to recover from a lost cursor.
Response Format
All list endpoints return responses in the following envelope.
{"data": [...],"pagination": {"limit": 100,"nextCursor": "eyJ1cGRhdGVkQXQi...","hasMore": true},"meta": {"requestId": "3fa85f64-...","timestamp": "2026-04-15T10:00:00Z"},"error": null}
The data array contains the records for the current page. The pagination object describes the page returned and how to request the next page. The meta object includes a request identifier and server timestamp. The error field is null on successful responses. Endpoints that do not paginate return this same envelope with pagination: null and the full result in data.
Query Parameters
Most list endpoints accept the same three query parameters.
Parameter | Type | Value |
|---|---|---|
| integer | Results per page. The default and maximum depend on the endpoint. See the limits below the table. |
| string | Sync cursor. Omit on the first call to begin from the beginning. Pass
from the previous response on subsequent calls. |
| ISO 8601 timestamp | Return only records updated at or after this timestamp. Use to recover a lost cursor or reset to a known point in time. |
Most list endpoints accept up to 200 results per page. The Bill of Materials feeds (GET /api/public/billofmaterials/technologies, /models, /datasets, /infrastructure and /agenticsystems) default to 100 results and accept up to 1,000. Arena All Models (GET /api/public/arena/allmodels) defaults to 20 results and accepts up to 100.
The received AI Card feeds return the AI Cards, Bills of Materials and vulnerability data that vendors share with your tenant. Their limits are:
- The received AI Cards feed (
GET /api/public/aicards/received) defaults to 100 results and accepts up to 200. - The received Bill of Materials item feeds default to 100 results and accept up to 1,000. These are the technologies, models, datasets and infrastructure feeds for one card (
GET /api/public/aicards/received/{receivedAiCardId}/billofmaterials/technologiesand so on) and across all received cards (GET /api/public/aicards/received/billofmaterials/technologiesand so on). - The received vulnerability feeds default to 100 results and accept up to 200. These are the technology and model findings feeds for one card (
GET /api/public/aicards/received/{receivedAiCardId}/vulnerabilities/technologiesand.../vulnerabilities/models) and across all received cards (GET /api/public/aicards/received/vulnerabilities/technologiesand.../vulnerabilities/models).
A limit above the maximum fails with a 400 error. It is not reduced to the maximum. On All Models the message is limit must be 100 or less.
The Bill of Materials feeds and the received AI Card feeds validate each request strictly. Each request below fails with a 400 error, error code BAD_REQUEST, and the message shown.
Request | Message |
|---|---|
above 1,000 on the Bill of Materials feeds and the received Bill of Materials item feeds |
|
above 200 on the received AI Cards feed and the received vulnerability feeds |
|
Both
and
, on the feeds that accept
|
|
Any
parameter, on the Bill of Materials feeds, the received AI Cards feed and the received Bill of Materials item feeds |
|
A malformed cursor, or a cursor issued for another feed, card or set of filters |
|
outside 1753-01-01 to 9999-12-31 on the received AI Cards feed |
|
Some endpoints differ. GET /api/public/api-clients uses pageSize instead of limit and does not accept updatedAfter. GET /api/public/users accepts updatedAfter, but only as a signal to restart from the first page rather than a data filter (see Recovering from a Lost Cursor below). The received vulnerability feeds do not accept updatedAfter. Page them with cursor only.
Endpoints Without Pagination
The following endpoints return their complete result in a single response and do not accept cursor, limit, or updatedAfter. The response uses the same envelope, with pagination: null.
GET /api/public/users/{id}GET /api/public/rolesGET /api/public/roles/{id}GET /api/public/permissionsGET /api/public/authentication-settingsGET /api/public/aicards/received/{receivedAiCardId}GET /api/public/aicards/received/{receivedAiCardId}/artifactsGET /api/public/aicards/received/{receivedAiCardId}/billofmaterialsGET /api/public/aicards/received/{receivedAiCardId}/vulnerabilities
Sync Workflow
Omit the cursor parameter (or pass an empty string) on the first call to begin from the beginning. Store the returned nextCursor and pass it on every subsequent call. When hasMore is false, you have reached the end. Store the final cursor for the next run. On the next poll, only records that were created or changed since that cursor are returned. On the Bill of Materials feeds, the received AI Card feeds and Arena All Models, some changes are not returned. See Keeping Feed, Received and All Models Data Complete below.
Example Pagination Loop (pseudocode)
cursor = stored_cursor_or_emptywhile true:response = GET /endpoint?limit=200&cursor={cursor}process(response.data)cursor = response.pagination.nextCursorif not response.pagination.hasMore:breakstore(cursor)
This same loop handles both initial full sync and incremental sync. On the first run, the stored cursor is empty and the API returns all records. On subsequent runs, the stored cursor causes the API to return only what has changed.
Keeping Feed, Received and All Models Data Complete
On the Bill of Materials feeds, the received AI Card feeds and Arena All Models, incremental sync does not return every change. A copy built only from incremental polls drifts from the platform over time. Each gap below has a step that closes it.
- Removed items. The Bill of Materials feeds and the received Bill of Materials item feeds do not report items removed from a Bill of Materials. Run a periodic full read of each feed without a cursor. Treat any item your copy holds that the full read does not return as removed.
- Replaced agentic systems. A rescan that changes an agentic system replaces it under a new
agenticSystemId. The old id is not reported as removed. Add the new record when it arrives, and remove the old id when a full read no longer returns it. - Late records. A scan or a vendor's publish can save records after a cursor was returned, with
updatedAtvalues earlier than that cursor. A sync that relies only on the cursor skips them. For a complete incremental sync, sendupdatedAfterinstead of the cursor and set it a few minutes before the lastupdatedAtyou received. Records you already hold come back in the overlap, so match them on their id (billOfMaterialsItemId, oragenticSystemIdon the agentic systems feed). On the received Bill of Materials item feeds,billOfMaterialsItemIdstays the same across a vendor's republishes, and a republish delivers every item of each Bill of Materials it rewrites again, changed or not. - Updated received cards. A card the vendor republishes, a card you review again and a card the vendor withdraws all come back at a new place on the received AI Cards feed. Match on
receivedAiCardIdand replace the record you hold. A withdrawn card stays on the feed with the statusWithdrawn. - Cards that arrive after your cursor. On the all-cards Bill of Materials and vulnerability routes, a card that reaches you after your cursor has moved on (newly shared, newly accepted, or its vendor newly linked) is not delivered by a cursor walk. When the received AI Cards feed shows you a new card, walk that card's own feeds from an empty cursor.
- Vulnerability snapshots. Vulnerability data is a snapshot the vendor publishes. Each republish replaces a card's snapshot whole, and the findings feeds serve only the latest snapshot. The vulnerability feeds have no
updatedAfter. Watch the received AI Cards feed withupdatedAfterand read the findings of each card it returns again. A republish moves the card on that feed on a best-effort basis, so also read the findings of each card whosevulnerabilitySharingisSharedagain on a schedule, for example daily. While you walk a findings feed, if a finding'scapturedAtdiffers from the page before, discard what you hold for that card and keep only findings with the newcapturedAt. - Matching findings. Match technology findings on
receivedAiCardIdandfindingIdtogether, because a vendor that publishes one AI system on several cards repeats the samefindingIdon each. A model finding'sfindingIdis new each time the vendor runs a new Arena test of the model. The new finding replaces the old one in the vendor's next snapshot. - Systems shared on more than one card. A vendor system shared with you on more than one card is served once on the all-cards routes, under one of those cards'
receivedAiCardId. An item can carry a differentreceivedAiCardIdthere than on another card's own feed. - isOutOfDate. This value on a received card can change without the card moving on the feed, so a sync by cursor or
updatedAftercan hold an earlier value. Read the single card (GET /api/public/aicards/received/{receivedAiCardId}) for a current value. - vendorId.
vendorIdon a received card or finding isnullwhen no single active vendor in your tenant is linked to the publisher, or when vendor attribution was unavailable. Treatnullas unknown, and do not overwrite a vendor you already hold for the card. - Arena All Models. All Models pages with
cursorlike other list endpoints, butupdatedAfterreturns only models added since that time. Changes to status, severity and counts on an existing model do not move it in the feed. Read the full catalog again periodically to refresh those values.
Recovering from a Lost Cursor
If a cursor is lost or you need to reset to a known point in time, omit the cursor parameter and pass updatedAfter. Set it a few minutes before the updatedAt value of the last record you received, so records that landed late are not skipped. On the Bill of Materials feeds and Arena All Models, updatedAt values have no Z suffix but are in UTC, so treat them as UTC when you set updatedAfter. On Arena All Models and the received AI Cards feed, updatedAfter must fall between 1753-01-01 and 9999-12-31. The response includes a new cursor you can use to continue incrementally from there.
updatedAfter can also be combined with limit (no cursor) for a simple date-bounded one-off query.
This does not apply to GET /api/public/users: passing updatedAfter there restarts the feed at the first page but does not filter by date.
The received vulnerability feeds do not accept updatedAfter. To recover there, walk the feed again from an empty cursor.
Notes
- Cursors are opaque. Do not parse, modify, or generate them yourself.
- The cursor encodes the position in the result set for an endpoint. Cursors from one endpoint cannot be used on a different endpoint. On the Bill of Materials feeds, a cursor also belongs to the
billOfMaterialsIdit was issued with. Use it only with the same feed and the samebillOfMaterialsId. On the received AI Card feeds, a cursor belongs to the feed, the card and the filters it was issued with (for examplevendorId,status,minSeverityorbillOfMaterialsId). Send it only with the same feed, card and filters. - The
meta.requestIdvalue can be useful for support requests. Include it when reporting issues to your Cranium support. - A malformed or invalid cursor is handled differently by endpoint:
GET /api/public/users, the Bill of Materials feeds and the received AI Card feeds reject it with a 400 error (the feeds returnBAD_REQUESTwith the messageInvalid cursor value.), whileGET /api/public/api-clientsignores it and returns the first page. Do not assume the same behavior across endpoints. - On the Bill of Materials feeds,
pagination.limitappears in the response only when the request sendslimit. - On the Bill of Materials feeds, an unknown
billOfMaterialsId, or one from another tenant, returns an empty page rather than a 404 error. - On the received AI Card feeds, a
billOfMaterialsIdthat is not a Bill of Materials of the cards the feed covers returns an empty page. A filter by a vendor that is unknown, retired or not yet linked to the publisher also returns an empty page. On a route for one card, an unknown card, or one shared with another tenant, returns a 404 error with the codeNOT_FOUND. - The findings feeds for one card return a 409 error with the code
VULNERABILITIES_NOT_SHAREDwhen the card'svulnerabilitySharingisPending,OfforWithdrawn. The all-cards findings feeds skip those cards and never return this error.





