These endpoints return the AI Cards that vendors share with your tenant and the artifacts attached to each card. Use them to bring received AI Cards into your own systems without the Application UI.
Reading Received AI Cards
All three routes in this article share the same authentication, permission and sync rules. This section states them once. The sections that follow give the request, fields and a sample response for each route.
Authentication
Bearer token, sent in the Authorization header.
Required Permission
Api_AiCards_Read. This is the same permission used by the AI Cards endpoint, and it is on the Default API Role. No new permission is needed for these routes.
Pagination
The List Received AI Cards route is cursor-paginated. The Get a Received AI Card and List a Received AI Card's Artifacts routes return one record or one list and are not paged.
Every response uses the same envelope.
| Field | Type | Rules |
|---|---|---|
| data | array or object | The records on this page, or the single record. |
| pagination.nextCursor | string | Cursor to send as cursor on the next call. |
| pagination.hasMore | boolean | true when more records are waiting. false at the end of the list. |
| pagination.limit | integer | The page size you requested. Present only when limit was sent. |
| error | object or null | Null on success. On failure, holds code, message and traceId. |
| meta | object | requestId and timestamp for the request. |
On routes that are not paged, pagination is null.
hasMore: false with a non-null nextCursor is the normal end-of-list state. Keep the last nextCursor and send it on your next sync. That call returns only cards that changed since.
Keeping a Complete Copy
The cursor returns new and changed cards. Keep these rules in mind.
- Upsert on
receivedAiCardIdrather than appending. A republished, re-reviewed or withdrawn card is delivered again at its new position in the list. - A cursor works only with the
vendorIdandstatusfilters it was issued under. - To start from a known time, send
updatedAfterinstead of a cursor. The two cannot be sent together. - Removed cards are not reported. Re-read the list periodically without a cursor and treat cards missing from that full read as removed.
Things to Know About Received AI Cards
vendorIdis null when no single active vendor in your tenant is linked to the publisher, or when vendor attribution was unavailable. Treat null as unknown. Do not overwrite a vendor you already hold for the card with it.publishedAtis when the card was delivered to your tenant.- A withdrawn card stays on the list with status
Withdrawn, zero artifact counts,versionnull andvulnerabilitySharingWithdrawn. - A card shared through the older AI Card flow, rather than from an AI system, carries no artifacts. Its artifact counts are zero and
vulnerabilitySharingisOff. isOutOfDatecan change without the card moving on the list, because a vendor editing its own data does not move the card. A sync by cursor orupdatedAfterkeeps the value it last read. Get a Received AI Card returns the current value.
List Received AI Cards
Returns the AI Cards that vendors have shared with your tenant.
Request
GET /api/public/aicards/received
Query Parameters
| Parameter | Type | Value |
|---|---|---|
| vendorId | GUID | Optional. Limits the list to one vendor, using a vendorId from the Vendors endpoint. A vendor that is unknown, retired or not yet linked to the publishing organization returns an empty page, not an error. |
| status | string | Optional. One of Active, Accepted, ChangesRequested, Declined, Deactivated or Withdrawn. Matched without regard to case. |
| limit | integer | Results per page. Default 100. Maximum 200. A higher value is rejected, not reduced to 200. |
| cursor | string | Sync cursor. Omit on the first call. Pass nextCursor from the previous response on later calls. Works only with the filters it was issued under. |
| updatedAfter | ISO 8601 timestamp | Return only cards updated at or after this time. Use it to recover a lost cursor or to start from a known point in time. Cannot be sent together with cursor. |
This route is cursor-paginated. The page parameter is not supported.
Response Fields
| Field | Type | Rules |
|---|---|---|
| receivedAiCardId | GUID | Identifier for the received card in your tenant. Use it as the upsert key and in the other routes in this article. |
| vendorId | GUID or null | The vendor in your tenant linked to the publisher. Null when no single active vendor is linked, or when vendor attribution was unavailable. |
| publisherName | string | Name of the organization that shared the card. |
| aiSystemName | string | Name of the AI system the card documents. |
| publishName | string | Name the publisher gave this shared version of the card. |
| status | string | Your tenant's state for the card. One of Active, Accepted, ChangesRequested, Declined, Deactivated or Withdrawn. |
| version | integer or null | Null until the vendor's first republish, then 1, 2 and so on. |
| isOutOfDate | boolean | true when the vendor has changed the underlying data since sharing this version. Current only on Get a Received AI Card. |
| publishedAt | timestamp | When the card was delivered to your tenant. |
| updatedAt | timestamp | The field the sync cursor and updatedAfter track. |
| artifactCounts | object | Number of artifacts of each type on the card: billOfMaterials, complianceFrameworks, documents and vulnerabilityReports. Zero for a withdrawn card or a card shared through the older AI Card flow. |
| vulnerabilitySharing | string | Whether the vendor shares vulnerability data on the card. Off (never shared), Pending (sharing is on but nothing has been captured yet), Shared or Withdrawn. |
Sample Request
GET /api/public/aicards/received?limit=2 HTTP/1.1
Host: api.cranium.ai
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json
Sample Response
{
"data": [
{
"receivedAiCardId": "8e40b1c7-6d2a-4c95-9f3e-0b7a5d1c2e84",
"vendorId": null,
"publisherName": "Contoso Labs",
"aiSystemName": "Document Summarizer",
"publishName": "Document Summarizer",
"status": "Withdrawn",
"version": null,
"isOutOfDate": false,
"publishedAt": "2026-09-18T16:02:11.903",
"updatedAt": "2026-11-03T11:27:45.06",
"artifactCounts": {
"billOfMaterials": 0,
"complianceFrameworks": 0,
"documents": 0,
"vulnerabilityReports": 0
},
"vulnerabilitySharing": "Withdrawn"
},
{
"receivedAiCardId": "5c1e7a92-3b4d-4f6e-8a10-2d9c4b7e1f03",
"vendorId": "7b2d4e61-0c9a-4f3b-b8e5-1a6c2d9f4e70",
"publisherName": "Northwind Analytics",
"aiSystemName": "Claims Triage Assistant",
"publishName": "Claims Triage Assistant (Q4 2026)",
"status": "Accepted",
"version": 2,
"isOutOfDate": false,
"publishedAt": "2026-10-02T13:15:44.21",
"updatedAt": "2026-11-12T09:41:03.587",
"artifactCounts": {
"billOfMaterials": 1,
"complianceFrameworks": 1,
"documents": 2,
"vulnerabilityReports": 1
},
"vulnerabilitySharing": "Shared"
}
],
"pagination": {
"limit": 2,
"nextCursor": "eyJ1cGRhdGVkQXQiOiIyMDI2LTExLTEyVDA5OjQxOjAzLjU4NyIsImlkIjoiNWMxZTdhOTIifQ",
"hasMore": false
},
"error": null,
"meta": {
"requestId": "2f7c9e14-6a3b-4d8e-b1f0-9c5a2e7d4b63",
"timestamp": "2026-11-16T18:30:12.4417263Z"
}
}
This sample was requested with limit=2. The first card was withdrawn, so its counts are zero and vendorId is null. The second card is accepted and shares vulnerability data.
Get a Received AI Card
Returns one AI Card a vendor has shared with your tenant, in the same shape as a record on List Received AI Cards. This is the only route that returns a current isOutOfDate. A withdrawn card is still returned, with status Withdrawn and zero artifact counts.
Request
GET /api/public/aicards/received/{receivedAiCardId}
Response Fields
The same fields as List Received AI Cards.
Sample Response
{
"data": {
"receivedAiCardId": "5c1e7a92-3b4d-4f6e-8a10-2d9c4b7e1f03",
"vendorId": "7b2d4e61-0c9a-4f3b-b8e5-1a6c2d9f4e70",
"publisherName": "Northwind Analytics",
"aiSystemName": "Claims Triage Assistant",
"publishName": "Claims Triage Assistant (Q4 2026)",
"status": "Accepted",
"version": 2,
"isOutOfDate": true,
"publishedAt": "2026-10-02T13:15:44.21",
"updatedAt": "2026-11-12T09:41:03.587",
"artifactCounts": {
"billOfMaterials": 1,
"complianceFrameworks": 1,
"documents": 2,
"vulnerabilityReports": 1
},
"vulnerabilitySharing": "Shared"
},
"pagination": null,
"error": null,
"meta": {
"requestId": "9a1d4f72-3c6e-4b8a-a5d0-7e2f1c9b6a34",
"timestamp": "2026-11-16T18:31:02.1186540Z"
}
}
Here isOutOfDate is true because the vendor changed the underlying data after sharing version 2. The list can still show false for the same card.
List a Received AI Card's Artifacts
Returns the artifacts on one AI Card a vendor has shared with your tenant. Artifacts are ordered by type, then name. Internal artifacts, such as the vulnerability assessment, are not listed. The number of each type matches the card's artifactCounts.
A withdrawn card, or one shared through the older AI Card flow, returns an empty data list.
Request
GET /api/public/aicards/received/{receivedAiCardId}/artifacts
Response Fields
| Field | Type | Rules |
|---|---|---|
| artifactId | GUID | Identifier for the artifact. For a Bill of Materials, this is its billOfMaterialsId on the received Bill of Materials routes. |
| type | string | One of BillOfMaterials, ComplianceFramework, Document or VulnerabilityReport. |
| name | string or null | The artifact's name, or its file name when it has none. Can be null. |
| format | string | Media type derived from the artifact's type, not declared by the vendor. application/json for a Bill of Materials or compliance framework. application/pdf for a vulnerability report. For a document, the media type its file extension implies, or application/octet-stream when there is none. |
Sample Response
{
"data": [
{
"artifactId": "a3f9c2d1-7e4b-4a60-b2d8-5c1e9f0a7b36",
"type": "BillOfMaterials",
"name": "claims-triage-service",
"format": "application/json"
},
{
"artifactId": "c7d2e9f4-1a3b-4c5d-8e6f-7a8b9c0d1e21",
"type": "ComplianceFramework",
"name": "NIST AI RMF 1.0",
"format": "application/json"
},
{
"artifactId": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a53",
"type": "Document",
"name": "Data Retention Policy.docx",
"format": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
},
{
"artifactId": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f72",
"type": "Document",
"name": "Model Card.pdf",
"format": "application/pdf"
},
{
"artifactId": "f9a8b7c6-d5e4-4f3a-a2b1-c0d9e8f7a614",
"type": "VulnerabilityReport",
"name": "Claims Triage Assistant vulnerability report",
"format": "application/pdf"
}
],
"pagination": null,
"error": null,
"meta": {
"requestId": "5b3e8d21-7f4a-4c6b-9e0d-2a1c8f5b7e46",
"timestamp": "2026-11-16T18:31:40.2875113Z"
}
}
Error Responses
400 BAD_REQUEST: the request was rejected. The message says why. List Received AI Cards returns these messages:status must be one of Active, Accepted, ChangesRequested, Declined, Deactivated, Withdrawn.limit must be 200 or less.updatedAfter must be between 1753-01-01 and 9999-12-31.cursor and updatedAfter are mutually exclusive.page is not supported; this feed is cursor-paginated.Invalid cursor value.The cursor is malformed, or it was issued under different filters.
401 UNAUTHORIZED: the token is missing, invalid or expired. Refresh the token and retry.403 Forbidden: the API client's role does not includeApi_AiCards_Read. The response body names the missing permission inrequiredPermission. Grant that permission to the API client's role, then retry. Retrying without the grant cannot succeed.404 NOT_FOUND: the card does not exist, has not been delivered yet, or was shared with another tenant. The three cases return the same response, so another tenant's id cannot be told apart from an unknown one.503 Service Unavailable: permissions could not be verified. The request did not fail on its merits. Retry it.500 INTERNAL_ERROR: an unexpected server error.
Most errors use the usual envelope.
{
"data": null,
"pagination": null,
"error": {
"code": "BAD_REQUEST",
"message": "status must be one of Active, Accepted, ChangesRequested, Declined, Deactivated, Withdrawn.",
"traceId": "0HNOVC2K1R7QD:00000001"
},
"meta": {
"requestId": "c2e7a1d4-8b3f-4e6a-9d0c-5f1b2a7e4c83",
"timestamp": "2026-11-16T18:30:15.0021498Z"
}
}
The 403 and 503 responses are different. They are written before the request reaches the endpoint, so they use a smaller application/problem+json body with no error, meta or requestId.
{
"title": "Forbidden",
"status": 403,
"detail": "You don't have the Api_AiCards_Read permission needed for this request. Ask an administrator to grant it.",
"requiredPermission": "Api_AiCards_Read"
}
The 503 body has the same shape, with title Service Unavailable, status 503 and no requiredPermission.
Responses in the usual envelope include error.traceId. Include it when reporting an issue to Cranium support.





