Umbraco Heartcore is a cloud-hosted headless CMS built on top of the Umbraco CMS platform. It exposes content via RESTful and GraphQL APIs, enabling frontend developers to build applications independently of the CMS backend. Unlike the traditional self-hosted Umbraco CMS, Heartcore is hosted by Umbraco Cloud and optimized specifically for decoupled architectures.

Core Architecture and Content Modeling

Umbraco Heartcore is built on the same foundation as Umbraco CMS but abstracts infrastructure and backend hosting. Content is managed through the Umbraco backoffice, which supports tree-based hierarchical structures and custom content types. Each content type can be composed using property editors like Textstring, Rich Text, Media Picker, and Nested Content.

Example: Defining a BlogPost Content Type with Fields

  • title (Textstring)
  • content (Rich Text Editor)
  • authorName (Textstring)
  • tags (Tags picker)

Each node created from this type will inherit this schema, and its data will be made available through the API.

Authentication and Security Model

Access to Umbraco Heartcore"s APIs is secured using API keys, which must be included in the Authorization header. There are two types of APIs:

  • Content Delivery API (Read-only): Uses the Content API key to retrieve structured content and media.
  • Management API (Read/Write): Requires a Management API key for creating, updating, and publishing content nodes.

Example for Content API:

code
Authorization: Bearer CONTENT_API_KEY

Example for Management API (Write Access):

code
POST /umbraco/management/api/v1/content/item Authorization: Bearer MGMT_API_KEY Content-Type: application/json{"name": "New Post","parentId": "123","contentType": "blogPost"}

Role-based permissions are managed inside the Umbraco backoffice and apply to CMS users only, not public API calls.

Video CDN

API Access: REST and GraphQL

Umbraco Heartcore provides two primary API options:

REST API: The default REST API returns content nodes, media, and data structured in JSON format. Content can be queried using node IDs, paths, or by filtering root-level children.

code
GET https://yourproject.umbraco.io/umbraco/rest/v1/content Authorization: Bearer YOUR_API_KEY

This fetches root-level content. To query by ID:

code
GET /umbraco/rest/v1/content/{id}

GraphQL API: The GraphQL endpoint enables structured and efficient data retrieval. It supports field filtering, nested traversal, and advanced fragments.

Advanced Query Patterns:

code
query {content(url: "/blog") {children {edges {node {name properties(alias: "content") {value}}}}}}

This query fetches all child content nodes under the /blog path, accessing the content property of each.

Content Delivery and Media Handling

Media files uploaded via the Umbraco backoffice (e.g., images, documents) are served via a CDN-backed media library. URLs are returned as part of the content API response and can be used directly in the frontend.

Example JSON Response for a Media Property:

code
{"alias": "coverImage","value": "https://cdn.umbraco.io/media/abcd1234/sample.jpg"}

Explanation:

  • alias specifies the name of the media property (coverImage) as defined in the content schema.
  • value provides the CDN-hosted URL of the uploaded media file, ready for use in the frontend.

No transformation options (e.g., resizing or cropping) are available directly in the URL. Developers must perform media optimization externally or prior to upload.

Multilingual and Hierarchical Content

Heartcore natively supports multilingual content. Each language is represented as a variant under the same content node. This enables localized content delivery with the same structure and ID, simplifying frontend integration.

Hierarchical content structures are maintained via the content tree. For instance, a Blog node can have Post children, allowing URL-based content traversal and nested navigation.

Webhook Support and Headless Workflows

Umbraco Heartcore allows configuration of webhooks to automate external actions on specific content events such as publish, unpublish, or delete. These webhooks are commonly used to:

  • Trigger Site Rebuilds (e.g., Netlify, Vercel).
  • Sync with External APIs or CRMs.
  • Notify Other Services of Content Updates.

Webhook payloads include the content type alias, node ID, and state, enabling fine-grained control in downstream systems.

Limitations to Consider

  • No Custom Webhooks Headers: Webhook configurations are limited to fixed payload structures; custom headers are not supported.
  • No Write API: Heartcore is read-only; content can"t be modified from the frontend or third-party apps.
  • No Asset Transformations: Media URLs point to static files without built-in support for resizing, cropping, or CDN-based transformations.
  • Tight Coupling to Umbraco Backoffice Schema: APIs reflect the internal CMS structure; deep customization requires aligning with Umbraco's property types.