Find the insights and best practices about our product.
Endpoint Reference: Received AI Cards

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.

FieldTypeRules
dataarray or objectThe records on this page, or the single record.
pagination.nextCursorstringCursor to send as cursor on the next call.
pagination.hasMorebooleantrue when more records are waiting. false at the end of the list.
pagination.limitintegerThe page size you requested. Present only when limit was sent.
errorobject or nullNull on success. On failure, holds code, message and traceId.
metaobjectrequestId 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 receivedAiCardId rather 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 vendorId and status filters it was issued under.
  • To start from a known time, send updatedAfter instead 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

  • vendorId is 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.
  • publishedAt is when the card was delivered to your tenant.
  • A withdrawn card stays on the list with status Withdrawn, zero artifact counts, version null and vulnerabilitySharing Withdrawn.
  • A card shared through the older AI Card flow, rather than from an AI system, carries no artifacts. Its artifact counts are zero and vulnerabilitySharing is Off.
  • isOutOfDate can change without the card moving on the list, because a vendor editing its own data does not move the card. A sync by cursor or updatedAfter keeps 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

ParameterTypeValue
vendorIdGUIDOptional. 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.
statusstringOptional. One of Active, Accepted, ChangesRequested, Declined, Deactivated or Withdrawn. Matched without regard to case.
limitintegerResults per page. Default 100. Maximum 200. A higher value is rejected, not reduced to 200.
cursorstringSync cursor. Omit on the first call. Pass nextCursor from the previous response on later calls. Works only with the filters it was issued under.
updatedAfterISO 8601 timestampReturn 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

FieldTypeRules
receivedAiCardIdGUIDIdentifier for the received card in your tenant. Use it as the upsert key and in the other routes in this article.
vendorIdGUID or nullThe vendor in your tenant linked to the publisher. Null when no single active vendor is linked, or when vendor attribution was unavailable.
publisherNamestringName of the organization that shared the card.
aiSystemNamestringName of the AI system the card documents.
publishNamestringName the publisher gave this shared version of the card.
statusstringYour tenant's state for the card. One of Active, Accepted, ChangesRequested, Declined, Deactivated or Withdrawn.
versioninteger or nullNull until the vendor's first republish, then 1, 2 and so on.
isOutOfDatebooleantrue when the vendor has changed the underlying data since sharing this version. Current only on Get a Received AI Card.
publishedAttimestampWhen the card was delivered to your tenant.
updatedAttimestampThe field the sync cursor and updatedAfter track.
artifactCountsobjectNumber 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.
vulnerabilitySharingstringWhether 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

FieldTypeRules
artifactIdGUIDIdentifier for the artifact. For a Bill of Materials, this is its billOfMaterialsId on the received Bill of Materials routes.
typestringOne of BillOfMaterials, ComplianceFramework, Document or VulnerabilityReport.
namestring or nullThe artifact's name, or its file name when it has none. Can be null.
formatstringMedia 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 include Api_AiCards_Read. The response body names the missing permission in requiredPermission. 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.