Find the insights and best practices about our product.
Public API Overview

The Cranium Public REST API provides programmatic access to your AI inventory, with read access across the API and write access for users, Bill of Materials scans, vendors, and vulnerability status. The API is designed for data engineering and security teams integrating Cranium data with data warehouses, IT service management platforms, internal reporting pipelines, and other downstream systems.

Audience

This documentation assumes familiarity with REST APIs, OAuth 2.0 authentication, and JSON. The API is intended for developers and integrators rather than business users. If you are looking to view your AI inventory directly, use the Cranium platform.

Available Endpoints

The API includes the following endpoints:

  • Bill of Materials: list and retrieve BOMs across your tenant
  • Bill of Materials Feeds: list the technologies, models, datasets, infrastructure, and agentic systems in your BOMs, across your tenant or for one BOM
  • Technology Vulnerabilities: list and retrieve technology vulnerabilities (CVEs) detected in your BOMs, and set a vulnerability's status
  • Arena Models: list models discovered and tested in your tenant
  • Arena Model Vulnerabilities: list model vulnerabilities (attack categories) detected through Arena testing
  • Arena All Models: list and retrieve entries in the Arena All Models catalog, which covers every model Cranium tracks (requires the All Models license)
  • AI Systems: list AI Systems registered in your tenant
  • AI Cards: list the AI Cards your tenant has published
  • Received AI Cards: list and retrieve the AI Cards your vendors have sent you, and their artifacts
  • Received Bills of Materials: list the BOMs in a received AI Card, and the technologies, models, datasets, and infrastructure in them, for one card or across all received cards
  • Received Vulnerabilities: retrieve a vulnerability summary and list the technology and model vulnerabilities your vendors have shared, for one card or across all received cards
  • Compliance Frameworks: list compliance framework responses for your tenant
  • Documents: list documents uploaded to your tenant
  • Users: list, retrieve, and create tenant users
  • Roles: list and retrieve tenant roles and their assigned permissions
  • Permissions: list the permissions that can be assigned to roles
  • Authentication Settings: retrieve your tenant's SSO configuration and MFA policy
  • API Clients: list API client metadata for your tenant
  • Vendors: list, retrieve, create, update, and retire vendors

Most endpoints are read-only. The write operations are:

  • POST /api/public/users, which creates a user.
  • POST /api/public/billofmaterials/{billOfMaterialsId}/scan, which triggers a CodeSensor scan.
  • POST /api/public/vendors, PUT /api/public/vendors/{vendorId}, and DELETE /api/public/vendors/{vendorId}, which create, update, and retire vendors.
  • PUT /api/public/vulnerabilities/{uniqueId}/status, which sets a vulnerability's status to Resolved, Ignored, or Unresolved. It needs the Api_Vulnerabilities_Update permission, which is not on the Default API Role. An administrator adds it through a custom API role.

Regional Base URLs

The Public API is available in three regions. Use the base URL that matches your tenant's region.

RegionBase URL
United Stateshttps://api.cranium.ai
European Unionhttps://api.eu.cranium.ai
Australiahttps://api.au.cranium.ai

If you are not sure which region your tenant is in, contact your Customer Success Manager.

API Conventions

REST and JSON

All endpoints use standard HTTP methods. Request and response bodies are JSON.

Authentication

All requests require a bearer token obtained through OAuth 2.0 client credentials. See the Authentication & Generating Credentials article for details.

Pagination

All list endpoints use cursor-based pagination. See the Pagination & Incremental Sync article for the full pattern, including how to perform full and incremental syncs.

Rate Limits

Requests are subject to per-customer rate limits. See the Rate Limits & Error Handling article for limits, headers, and the 429 response format.

Status Codes

401 means the token is missing, invalid, or expired. Request a new token and retry. 403 means the API client's role lacks a permission, or your tenant is not licensed for the feature. The response names the permission in requiredPermission. A new token does not fix a 403. 503 means permissions could not be verified. Retry after a short wait. See the Rate Limits & Error Handling article for the full list of codes.

Sorting

Sort order is fixed per endpoint and is not configurable through query parameters.

Read and Write Operations

Most endpoints support read operations only. Write operations are limited to the endpoints listed under Available Endpoints. Bulk export operations are not available.

Licensing

The Public API is a licensed feature. To enable the API for your tenant, contact your Customer Success Manager. Once enabled, the API Management section becomes available under Settings, where authorized users can generate credentials.

The Arena All Models endpoints also require the All Models license. Tenants without it receive a 403 response from these endpoints. To add the All Models license, contact your Customer Success Manager.

Getting Started

To begin using the API:

  1. Confirm your tenant has the API license enabled. If the API Management section does not appear under Settings, contact your Customer Success Manager.
  2. Generate API credentials by following the steps in Authentication & Generating Credentials.
  3. Request a bearer token from the token endpoint using your Client ID, Client Secret, and Scope.
  4. Make authenticated requests to the endpoints relevant to your use case.
Did this answer your question?