Umbraco Heartcore is a headless Software As A Service (SAAS) offered by Umbraco. The service enables you to create and manage content and media in the Umbraco backoffice and make it available to any platforms, devices, channels and so forth.

All Umbraco Heartcore projects include a Content Delivery Network (CDN) using CloudFlare. This CDN is used for caching content and media fetched through the Content Delivery API. Additionally, the media CDN (media.umbraco.io) allows for resizing and cropping options, which improves both performance and stability.

You can read more about all the features and benefits on the . You can also look at the pricing, plans, and features on the page.

There are 3 ways to get your hands on an Umbraco Heartcore project:

Umbraco Heartcore is a software as a service (SaaS) offering, that eliminates upgrade concerns. All maintenance related to the CMS, its features, and APIs is handled by Umbraco HQ.

Umbraco HQ will regularly be adding new features to the CMS and new capabilities to the REST APIs. Each time new endpoints are added to the REST API the api-version will be updated to reflect the changes. API releases and versioning is handled following the .

We follow semver in terms of versioning, which means you can be sure that existing APIs will continue to work as expected without breaking. If a breaking change is required then the major version will be incremented, but the previous major version will continue to work.

When using our , the api-version is handled as part of the library and generally not something you need to worry about.

With the built-in API browser that ships with all Umbraco Heartcore projects, you are able to test how your data is outputted and formatted before connecting to your website or application. You can test the API endpoints and see which JSON is outputted with each call.

This article will cover how to use the API Browser in order to reap all the benefits of the feature. The API Browser can be used for both the Content Delivery API and the Content Management API.

The API Browser is located in the Settings section of the Umbraco backoffice. Expand the Headless dashboard in the Settings tree, and select "API Browser".

Using the API Browser you can browse through the output for the various API endpoints. This is done from a UI, where on the left side you are able to explore the endpoints and on the right side you are able to inspect the output.

In the top-right corner you can switch between browsing in the Content Delivery or the Content Management API.

In this article, you can learn more about how to work with environments on your Umbraco Heartcore project.

Having multiple environments means that you have a place to test both your content and the content structure before deploying it to the production environments, from where the content is served to your application.

An environment on a Heartcore project can be defined as a workspace and is at the same time a Git repository. When you have more than one environment on your project, these environments will act as branches of the main repository.

Umbraco Heartcore uses a deployment model that relies on Git and other core technology, which gives you the option to move both content and structure files from one environment to another.

Learn more about the deployment model in the.

How many environments you can work with depends on the

Having multiple environments on your Umbraco Heartcore project can be a great asset for testing and having a place where your content editors can work without interfering with anything on the Live environment.

When working with multiple environments, it is important to follow the correct workflow. In this article, you can learn more about the workflow and the best practices for using it.

The workflow uses a classic "left to right" deployment model, meaning that changes are first made on the Development environment and then deployed to the Staging or Live environment. The workflow depends on whether you have a Staging environment which further depends on the plan your project is on.

We recommend that you do not work with Document Types directly on the Live environment. This should, as a rule of thumb always be done on the "lowest most" environment: the Development environment.

The deployment approach is divided into two steps:

While structure changes are deployed between environments using the Cloud Portal, content and media transfers and restores are handled through the Umbraco Backoffice.

Another difference between the two steps, is that content and media can be restored against the left-to-right flow. This means that when you have a lot of content on a Live environment, it is possible to restore all this content on a Development and/or Staging environment.

The screenshot above is from the Content section on a Development environment. Right-click the Content tree to open the menu as shown in the screenshot.

Queue for transfer gives you the option to queue all content in the Content tree for transfer to the next environment (Staging or Live). It is also possible to right-click single nodes in the content structure in order to only queue some of it for transfer.

Restore gives you the option to restore all content from environments right of the current environment. In some cases you might not want to restore all content as once, in which case you should use the Partial restore option instead. Partial restore can be found by right-clicking a node in the content tree.

Structure changes like new and/or updated Document Types need to be deployed through environments using the Project View in the Cloud Portal.

In the screenshot above, changes made on a Development environment are ready to be deployed to the Live environment, as indicated by the blue button: "Deploy changes to Live". Had there been a Staging environment on the project, the changes would first be sent to the Staging and then opened up for the option to deploy from Staging to Live.

A deployment from one environment (source) to another (target) goes through the following steps:

1. The target environment is checked for changes

2. If changes are found, these are pulled down and merged into the source environment

3. The changes in the source environment are then pushed to the target environment

This process might take a few minutes, depending on the amount of changes being deployed.

Once your structure has been deployed, it will be possible to transfer your content and media as well. This is done from the Umbraco Backoffice - read more about this in the .

This is the read-only API for delivering published content and media to any app, website, device or platform.

It’s worth noting that the JSON output for both Content and Media vary depending on how a given ContentType or MediaType is defined.

Cultures

Specific to Content in the Content Delivery API.

To request content in a specific language, a culture parameter can be specified. When no culture is specified its treated as invariant and the default language will be returned.

Access via an Accept-Language header

GET https://cdn.umbraco.io/content
Accept-Language: en-US

Acces via a Query String parameter

GET https://cdn.umbraco.io/content?culture=en-US

Content endpoints for retrieving specific content by ID or URL. It is also possible to retrieve children, descendants and ancestors structured according to the Content tree structure.

Media endpoints for retrieving specific media by id. It is also possible getting children of a media folder structured according to the Media tree structure.

Umbraco Heartcore is subject to soft rate limits for requests to the delivery APIs. These limits are based upon the plan tier of the project, as follows:

Requests to the Content Management API are not limited.

Rate limits are individual for each of the GraphQL, Content Delivery, and Preview APIs. For example, a Standard Heartcore project may make up to 50 requests per second each of GraphQL and Content Delivery without being in violation.

When a request is made to the Content Delivery or GraphQL APIs, the result is cached. Subsequent requests to the same endpoint with the same parameters will return the cached result. Cached results expire after a variable period or after publishing relevant content. Requests served from the cache do not count toward the rate limit.

Rate limits to Heartcore APIs are currently soft limits. That is, whenever a given environment receives requests above the limit, it will continue to serve responses normally. Umbraco may contact the owner of projects that exceed their allowed rate limit.

In this article you will learn how to add Users to the backoffice and how to manage the API Keys.

The Backoffice User

A Backoffice user can be added in two ways.

• Added from the portal from the Team Management section, or

• From the Users Section in the Backoffice

A feature that is unique for Umbraco Heartcore is the option to create an API Key for specific users. The API Key can be created from the API Key section of the User page. This page can be found under the Users Section in the top-left navigation of the backoffice.

By default, the Content Delivery API is public, if you would like to protect it you can do so in the "Settings" section and "Headless" tree.

If your Content Delivery API is protected or you want to use Content Management APIs, your user will need to have an API Key assigned. When you have navigated to the Users section mentioned above you can create the API Key by clicking the "Create API Key" button.

A modal will pop up where you enter the name of the key and set a date for when it should expire. If there is no expire data, the API Key will be valid until you delete it manually.

Once the API Key has been created you will see the actual key and two examples on how to use the key with the Authorization header and an API-Key header.

You are able to see a list of all your created API Keys and all relevant information. You are also able to revoke a generated key.

With the GraphQL query language, you will be able to limit the amount of data transferred to and from your Heartcore instance and the client by specifying exactly what kind of information you would like to get in your API calls.

You can test and build GraphQL queries directly in the backoffice-integrated GraphQL Playground.

In the Settings section in the Umbraco Backoffice, you will find the Headless tree. From there you can use the GraphQL Playground to test your queries against your project's schema.

The Playground comes with basic features such as real-time error highlighting, syntax highlighting, formatting, query history and more.

In this article you will get an overview of the Preview functionality in Umbraco Heartcore and how to use it with our.

The Preview API is always protected, this means it requires an API Key with Browse Node permission to be able to access it. If you don't already have an API Key ready, head over to to learn how to create one.

You will also need a client consuming the Content Delivery API. If you don't already have one you can use one of the samples included with the Client Libraries.

To make it easier for your editors to access the preview version of you website, you can add a Preview button to content nodes in the backoffice.

This can be done by going to the Settings section, expanding the Headless item and clicking on Preview.

In this article you will get an introduction to the different sections in the Umbraco Backoffice.

Login screen

When you go to the backoffice of your Umbraco Heartcore project you will be asked to log in.

From here you are able to log in with the credentials used when the project was created.

Sections

The backoffice is divided into specific sections for example Content, Media and Settings. This will allow you to do work related to a specific section of your project.

The sections menu is located in the top-left corner of the screen.

Section Tree

Every section has a section tree that gives you an overview of the content you have in each section.

Folders and nested content can be expanded by clicking the arrow next to the node. This can also be done by double-clicking on the node.

Every item you have is considered a node. It could be a media item or content in the content section.

Every section in the Umbraco backoffice has one or more dashboard associated with them. The first thing you will see when accessing the backoffice on your Umbraco Heartcore project is the "Getting Started" dashboard. Here you can find links to news and resources useful to your project.

In this section you will find all the content you have on your page. Each item in the tree is called a Content Node. Every node is made up by different fields. Each field is defined by a property.

The content tree holds all the content nodes you have created.

The left holds the content tree that will automatically nest your content if you have created nodes with parent-child relationships.

On the left you can see what properties the highlighted Content Node has. In the above example there is a group called Main which holds a few properties. By clicking on the Info tap you will be able to see some useful information for the specific Content Node.

At the top you can see the automatically generated URL to the specific Content Node. Below you also get a handy history overview that shows who has done what at what time. Lastly you can see some general information such as Status, Creation Date and a direct link to the Document Type. You can edit it without leaving the current view.

Lastly you can either Save, Save and publish, Schedule a publication or unpublish the Content Node. You can change the action by clicking the small up arrow next in the green button in the lower right corner.

Media items are used to store images and videos in the Media section. These items can be referenced from your content. You are also able to create folders in the Media section to keep all your Media Items sorted.

A handy feature is that if you have a Media Picker in your Content Node and you upload an image. This image will automatically be added in the Media Section.

In the settings section you find the before mentioned Document Types, Data Types and Media Types among other settings that will be covered below.

Document Types defines the content nodes the editors can create in the Content section. A Document Type has a set of properties that is made up of specific Data Types like text or a numbers. A property is the fields that holds the content in a content node that can be edited by the content editor.

What differs from Document Types is that Media Types are specifically made for media items in the Media section.

When you have a website with a login you might want to create Member Types. Umbraco comes with a standard Member Type. You can extend of this, but you can also create your own type for more customized members.

Each Document Type property consists of a Data Type which defines what kind of input the property holds. Each Data Type references a Property Editor and can be configured in the Settings section of the Backoffice. A Property Editor can be anything from a basic number to something more complex like an image-cropper. It is possible to have multiple Data Types with different settings that still uses the same Property Editor.

In this section, you can establish two-way relationships for querying both parent-to-children and children-to-parent connections.

The log viewer is a view where you can browse all log entries for your project. You can filter on warnings, errors or critical Log Types to name a few.

In the Languages section you can manage your language variants. Depending on what plan you have chosen you will be able to setup multiple languages on your Heartcore project.

The headless dashboard has some information about your Heartcore project. Depending on what plan you are on, you will have access to more languages and user groups.

The dashboard shows you:

• What plan you are on

• How many available languages you have

• How many user groups you have

In addition you are able to set the Content Delivery API to either Public or Private. If the API is private, you must have an to fetch content from it.

From the Headless tree you can browse and explore the REST API endpoints as well as create and manage your Webhooks.

• API Browser: In the API Browser you can test your API endpoints. Learn more about this in the .

• Webhooks: You can create and manage Webhooks for content actions. Learn more about how this is setup in the.

In this section you can manage all the users that are currently working on the project. Users are not to be confused with Members. Members are people who have a login to your website's frontend. Users can be developers, content creators, and so on, who have access to the backoffice.

You can segment your users into different User Groups. You can add Users to existing Groups or create your own custom User Groups. How many of these groups you can create depends on the plan your project is on.

For each user on your project you can generate a unique API key. This key will be used to access the Content Management API, and can be revoked at any time. Learn more about the API Keys in the

The Members section is where you manage your members who are able to log into your projects frontend. You can create Member Groups for management if you have multiple types of memberships.

In this section you can create and manage your Umbraco Forms.

Persisted queries allow you to store GraphQL queries on the server. This enables clients to execute them by referencing an alias rather than sending the full query each time. this approach streamlines client-server communication and enhances security.

• Reducing the payload size

  • You minimize the data transmitted over the network by sending only the alias and necessary variables. This reduction in payload size leads to faster request times and is particularly beneficial for mobile applications or environments with limited bandwidth.

In this article you can learn more about the .NET client library that you can clone and use with your Umbraco Heartcore projects.

It is a library for .NET Core and is based on .NET Standard 2.0. This means that it can be used on the most .NET frameworks, for example UWP, Xamarin.Android, Xamarin.Mac and Desktop .NET 4.6.1.

The .NET library can be found on GitHub: .

You can also install it through NuGet:

You will receive a Visual Studio solution file that references the client library (Umbraco.Headless.Client.Net). Additionally, there is a test project (Umbraco.Headless.Client.Net.Tests) utilizing xUnit for unit and integration tests.

Along with the client library you will also find two samples based on the library. We have built an MVC sample and a console sample.

The following changes have been released to all Heartcore sites.

For a long time, the only way to get redirect information from Heartcore was a single endpoint on the Delivery API. This endpoint returned paginated redirect information for all content items in the tree. If you needed to find the canonical URL for a given path, then this endpoint was your only option. You would need to find your path in the returned items - especially challenging if it was not on the first page of results!

In order to save you the trouble, a brand new endpoint has been added to the Delivery API. It allows you to fetch the canonical URL (and any other redirects) for a given path. For more information, check out the .

There are some differences between Heartcore and Umbraco CMS.

The following changes have been released to all Heartcore sites.

Grid Disabled By Default

With the grid property editor becoming deprecated, it has been decided to hide related functionality in the backoffice for sites that are not using it yet. The modern alternative to Grid Editor is the Block Grid Editor. The migration between Grid and Block Grid won't be fully automated, so this decision was made to encourage use of the most future-proof Data Type.

Sites that already have Grid Data Types in use will continue to offer the full range of grid support. Grid content can also be imported from a zip package, which will also fully enable support for it across the environment.

Management API Property Type Configuration

The Content Management API now exposes additional configuration data about properties via the content type endpoints. This will allow you to do things like retrieve information about possible prevalues for a dropdown field or radio button list, for example.

Notable Bugfixes

Fixes for commonly-reported issues this month include:

• The root endpoint of the management API now correctly returns links to other endpoints.

• The API explorer in the backoffice is no longer prevented from returning responses from the management API due to a Cross-Origin Resource Sharing (CORS) error.

• The alias for dev & staging environments should no longer point at the live content APIs.

• The webhook log viewer will now correctly load information about attempted runs.

• When previewing content in a multilingual setup, the preview window will no longer indefinitely hang until you save the selected variant.

This page contains documentation for the available API endpoints for Umbraco Heartcore. It includes endpoints for the GraphQL API as well as for the REST API which is divided into two main areas: Content Delivery and Content Management.

The GraphQL API can be used to query the read-only Content that you would normally retrieve to show the published content in your apps, websites, or other platforms. The API is available on https://graphql.umbraco.io. This API is available on Trial projects as well as Starter and Professional Plans.

The Content Delivery API is a read-only Content and Media API that you would normally retrieve to show the published content in your apps, websites or other platforms. The API is available on https://cdn.umbraco.io.

The Content Management API can be used to Create, Read, Update and Delete Content, Media, Languages, Relations, Members, and the associated types using Umbraco Backoffice user credentials or API Keys. The API is available on https://api.umbraco.io.

The Preview API is the read-only Content and Media that you would retrieve to show the draft content in your apps, websites, or other platforms. The API is available on https://preview.umbraco.io. The Preview API is always protected and requires an Api-Key. The endpoints are the same as the Content Delivery API.

The REST APIs are based on the .

The properties in the REST API, which starts with an underscore, are system level properties. That means that they are standard Umbraco properties, which cannot be changed via the API. This includes properties like _id, _url, _createDate, _updateDate, _creatorName, _writerName, _level and _hasChildren. These are all defined by Umbraco when Content is created or updated.

The properties _links and _embedded are both part of the HAL specification and are implemented in the REST API accordingly.

In the Settings section in the Umbraco Backoffice, there is a Headless tree. From there you can use the API Browser to interact with both the Content Delivery and Content Management APIs.

It is recommended to use this browser to explore the JSON output for all the different endpoints documented under the Content Delivery and Content Management API sections.

Both the Content Delivery and the Content Management APIs share common points of configuration for access, versioning, culture and authentication/authorization, which are highlighted below.

In order to access the data for your Umbraco Heartcore project you need to provide a project identifier (Project Alias) via a HTTP Header or a Querystring parameter.

The Project Alias is a HTTP friendly version of the Project Name under your Umbraco Cloud account.

API versioning is handled by .

All API requests need to specify the API version they target. If no version is specified, the latest version of the API is used, which will break clients when a new version of the API is released.

By default the Content Delivery API is not protected, it can be enabled through the backoffice. The Content Management API is always protected and requires either an API key or a bearer token.

Since both API keys and bearer tokens are created for a specific user their permissions can be set on that user in the backoffice.

API keys can be managed for a user through the backoffice.

When using the Authorization header the API key must be passed in as the username and the password must be left empty. The value must be base64 encoded e.g. base64(api-key:)

The endpoints implement OAuth 2.0.

A bearer token can be created by posting to https://api.umbraco.io/oauth/token and supplying a username and password for a backoffice user. This corresponds to a user logging into the backoffice and is thus only meant to be used for the Content Management API.

It can be used by passing it to the Authorization header.

A member login can be used to access the Content Delivery API if it's protected. Members will only have access to Content Delivery Network (CDN) endpoints and cannot be used to access the Content Management API.

Content can be restricted further by using the Public Access feature in Umbraco to only allow access for specific Members or Member Groups.

The endpoints implements OAuth 2.0.

A bearer token can be created by posting to https://cdn.umbraco.io/member/oauth/token and supplying a username and password for a member.

It can be used by passing it to the Authorization header.

This is the management API for creating, updating and deleting content, media, languages, relations, members and member groups. It also allows you to retrieve content drafts as well as Content Types, Media Types and Member Types.

Common for the Content Management API is that you must be authenticated and authorized when performing any action against the endpoints listed below. This means that you must supply a Bearer Token via an Authorization header or an API Key via an Authorization or Api-Key header.

Content endpoints for retrieving, creating, updating and deleting.

Content Type endpoints for retrieving all available and specific content types. We also expose endpoints for publishing and unpublishing content.

Media endpoints for retrieving, creating, updating and deleting.

Media Type endpoints for retrieving all available and specific media types.

Language endpoints for retrieving, creating, updating and deleting.

Member endpoints for retrieving, creating, updating and deleting. We also expose endpoints for adding a member to member group and removing a member group from a member.

Member Group endpoints for retrieving, creating and deleting.

Member Type endpoints for retrieving all available and specific member types.

Relation endpoints for retrieving, creating and deleting.

Relation Type endpoints for retrieving specific relation types.

Umbraco Forms endpoints for retrieving and submitting forms.

The following changes have been released to all Heartcore sites.

Webhook Enhancements

With the core CMS adding webhook support, the same functionality has been adapted into Heartcore to use the same user interface. You will now get the same consistent editing experience in both Umbraco CMS and Umbraco Heartcore, and it also comes with new features.

• You may now select multiple event types (for example, publish / unpublish) or content types for a webhook. No more needing to create dozens of hooks to achieve what can now be done with only one.

• You may now specify custom HTTP headers to send to your endpoint whenever the webhook fires.

Aside from the interface, all other aspects of webhooks in Heartcore are unchanged. Webhooks are still fired from the delivery platform with the same IP address range, retry policy, and payload that you are used to.

For more information about webhook functionality, both new and old, check out the .

A recent roll-out has added additional firewall rules for all Heartcore services. While efforts have been made to tune these, there is always a small possibility of false positives. If you believe your legitimate traffic is affected, raise a support ticket through the portal.

In order for you to get started with Umbraco Heartcore we have created a set of client libraries for you to use for testing and for getting a seamless start with the product.

The client libraries provide you with a starting point where you do not need to worry about implementing the use of each API endpoint, as these have already been setup. All you need to do is connect the client library to your Umbraco Heartcore project. How this connection is made depends on the client library, but usually requires configuring a couple of parameters.

We recommend testing with these libraries if you are looking to explore the potential of Umbraco Heartcore.

Both client libraries include samples that you can connect to your Heartcore project and start testing in no time.

tip Our client libraries are open source and free to use.

Found a bug? Please let us know by using the Issue Tracker on the GitHub repositories:

A .NET client library based on .NET Standard 2.0 to support application development including Xamarin/UWP applications.

This client library includes three samples:

• An sample site, with custom routing and controller hijacking.

• A, with options using the Content Delivery and the Content Management API.

• A showing how to use the .NET library to present your Umbraco Heartcore content in a Blazor application.

A Node.js client library including a Koa sample that you can hook up to your Umbraco Heartcore project for testing.

Webhooks give you the ability to send information about events in Heartcore to external systems. They work by sending an HTTP POST request to a configured endpoint, with information about the event in the request body.

Webhooks can keep other systems in-sync with content from Heartcore without having to poll it for changes.

One common use case is building static websites. By adding a webhook, you can inform your chosen static site builder when content changes so that it can re-generate static assets on demand.

Webhooks are managed from a dashboard in the settings section of the backoffice.

1. Go to the Settings section.

In this article, you will learn more about the Umbraco Cloud Portal and what options are available to you.

After you have logged into the , you are presented with the project list overview.

From here you can see a list of all your projects. If you have multiple projects, you can sort specific projects into groups.

Clicking on a project will take you to the project page where you will get an overview of your environment(s).

From here, you can create multiple environments, so that you can have a Development and eventually also a Staging environment. Depending on what plan you have chosen, you will have access to one or more environments on your project.

The following changes have been released to all Heartcore sites.

The Block Grid Editor from core Umbraco is now available in Heartcore. A modern alternative to the Grid Editor, this type is particularly useful for allowing content authors to build page-like structures.

See the for more information about how to get started with the Block Grid.

A lot of work has been put into increasing the performance of the backoffice in this release. Content authors can expect to see a speed improvement across the board to most backoffice operations.

Previously, deleting a content or media item that was linked to from another item may have resulted in broken links. Now, content authors will be warned when attempting to delete an item which other items are dependent upon. They are also informed which items linked to the deleted one, so that they can change those items if desired.

The GraphQL API can be accessed on https://graphql.umbraco.io, it accepts POST requests with the content type application/json. The body must be JSON and contain a query field with the query as a string and an optional variables field containing the variables.

{
  "query": "query($url: String) { content(url: $url) { name } }",
  "variables": {
    "url": "/"
  }
}

API Access

In order to access the data for your Umbraco Heartcore project you need to provide a project identifier (Project Alias) via an HTTP Header or a Querystring parameter.

The Project Alias is an HTTP friendly version of the Project Name under your Umbraco Cloud account.

Access via Umb-Project-Alias header

POST https://graphql.umbraco.io/
Umb-Project-Alias: {project-alias}

Authorization

By default the GraphQL API is not protected. This can be enabled through the Backoffice, where API keys for each user in the Backoffice is also managed.

To access the GraphQL API the user must have access to the Content section and have the Browse Node permission.

The GraphQL API supports fetching draft content, this can be done by passing a preview argument to the root query fields.

The GraphQL API supports , running a persisted query can be done using the following payload in the Graphql request:

The persisted queries also support variables

Information on how the GraphQL schema is generated, reserved names and built-in custom types.

A list of all the built-in Umbraco Property Editors and their GraphQL types.

Documentation on how to filter and order collections with the GraphQL API.

In this article, you can read more about the .NET Core Console Application.

We will go through the process of setting the application up and exploring what you can do with the application. We will also discuss how you can connect to your Heartcore project on Umbraco Cloud.

Once you have cloned down the , there are two ways of running the application.

Open up the Umbraco.Headless.Client.Samples.Console.sln file located at Umbraco.Headless.Client.Net\samples\Umbraco.Headless.Client.Samples.Console and press F5. This will launch the Console application.

By using the command line, you will need to run the following commands from the Umbraco.Headless.Client.Samples.Console

In this article you can learn more about how to use the Forms API for retrieving form definitions and submitting form entries.

We recommend that you have a look at the Forms API reference documentation along side this article if you haven't already seen it. The API reference has useful content around field types and possible errors.

Using the Forms API requires the use of a Bearer Token or an API-Key. A bearer token makes sense when working server side or in some kind of middleware whereas on the client side an API-Key might be a better fit. When using an API-Key on the client side we recommend that you create a "Forms-only" usergroup, so you do not expose any Content Management capabilities on the client side where not intentional.

Usage

In the Forms section of the Umbraco backoffice you will find the Forms Builder, which allows you to create forms by adding Fields, Placeholder texts, Validation and Conditions.

The purpose of this article is not to describe the Forms functionality itself, but to show how to use the APIs which are available for Umbraco Heartcore projects.

If you want to learn the basics of 'Creating a form' before going further we recommend that you start with the .

Before you continue with the rest of this article we recommend that you have at least one Form available that can be used for examples below. Here we will use a form with a Name field, an Email field and the Data Consent field, which is standard for all new Forms.

The API for Forms lives under the Content Management API, so a Bearer token or an API-Key is required to call all the Forms related endpoints.

For this example we will call https://api.umbraco.io/forms which lists all available forms. From here you can find a specific form to retrieve in order to get the definition for that form. This is useful when you want to expose a specific form in a specific part of your presentation layer.

Getting a specific form is done by issuing a GET request to https://api.umbraco.io/forms/{id:guid}

Required headers include umb-project-alias and Api-Key or a Bearer Token via an Authorization header.

The JSON output for one specific form would look something like this:

Notice that the layout of properties correspond to the Forms builder in the backoffice. The various properties available for the form itself and for each of the fields is something you can use to build up the look and feel of the form in your presentation layer.

If you are a C# developer and work with .NET you can use the in your own codebase to retrieve form definitions.

First step is to install it through NuGet:

When using the library you need the Content Management part in order to work with Forms. Create a new instance of the ContentManagementService and pass in the name of your Umbraco Heartcore project and either username + password of a backoffice user or an API-Key. In the example below we use an API-Key when retrieving all available form definitions:

If you want to retrieve a specific form you can use the GetById method along with a GUID ID as shown below:

If you are a JavaScript developer and work with NodeJS you can use the in your own codebase to retrieve form definitions.

First step is to install it through npm:

First we need to import and create a new instance of the Client, to use the forms api you need to pass in the project alias and set an API-Key.

To retrieve all forms we need to use the forms service on the management API as shown below.

To retrieve a single form by ID you can use the byId method with the form ID.

When a form is filled out we need to post the entered values to the entries endpoint of the Forms API.

In order to submit the entered values you send a POST request to https://api.umbraco.io/forms/{id:guid}/entries where the ID represents the specific form to post the entry to.

Required headers include umb-project-alias and Api-Key or a Bearer Token via an Authorization header. The payload is a key value object with the alias of the fields and the values entered in the form.

Below is an example of the payload body when sending an entry back to the form retrieved in the previous section.

Please keep in mind that the dataConsent property is required to have the value on or true when present on a form - anything else will result in validation error.

If you added validation on the email field to ensure that the entered value is in fact a valid email address, then this validation will also be enforced through the API. Try to send the payload above with a value that is not a valid email address to see the validation response you get back.

Continuing on the previous .NET Core example we can also post entries to a form using the library.

Given that the form contains a Name, Email and Data Content field we can submit a form entry as follows:

Please note that if validation fails an exception is thrown. The validation configured for each of the fields is validated by Umbraco Forms on the server side.

Continuing on the previous NodeJS example we can also post entries to a form using the library.

Given that the form contains a Name, Email and Data Content field we can submit a form entry as follows:

Please note that if validation fails an error is thrown. The validation configured for each of the fields is validated by Umbraco Forms on the server side.

This article showcases how to fetch content and media from your Umbraco Heartcore project using the official Node.js Client Library. If you are not familiar with Node.js you can take a look at the official Node.js Documentation.

Prerequisites

• Node.js (version 10 or above) installed on your machine. You can verify the version by running node -v in your terminal.

• Access to an Umbraco Heartcore project.

• An API key generated from your Heartcore project. For more information, see the article.

• Basic familiarity with terminal commands and Node.js.

1. Log into your Heartcore project on the Umbraco Cloud Portal.

2. Navigate to the Content section.

3. Create a new content item, such as a "Home Page." Fill in the necessary fields and publish it.

4. Go to the Media section.

1. Open a terminal or command prompt.

2. Navigate to the directory where you want your project to reside.

3. Run the following command to create a package.json file:

There are two ways to install the Umbraco Headless Client Library:

• Clone or download the client library from GitHub, or

• Run the following command in your terminal:

1. Create a new file called app.js using a text editor (such as Notepad++ or Visual Studio Code) in your project directory.

2. Open the app.js file.

3. Use the following code template:

1. Open a terminal.

2. Navigate to your project folder.

3. Run the following command:

The Node.js library provides a variety of methods to fetch and manage data from your Umbraco Heartcore project. These methods allow you to interact with both the Content Delivery API and the Content Management API, depending on your requirements.

To fetch content or media, use the following convention:

In the above examples:

• Use root() to fetch all content or media from the root level.

• Use children() or ancestors() to navigate the hierarchy and retrieve related content or media items. You can also fetch specific items directly by their ID or URL.

For a full list of available methods, visit the .

To manage content, media, and other types, use the following convention:

In the above examples:

• Use create() to add new content.

• Use all() to fetch all available content types.

For a full list of available methods, visit the .

In this article you can learn how to get started with your Umbraco Heartcore project.

It will cover everything you need to know, in order to create your first piece of content in the Umbraco backoffice.

Introduction

When you log in to the Umbraco Backoffice, the first thing you will see is the Content section. This is where you will be creating content for your Umbraco Heartcore project. However, it will not be possible to create any content yet, as we will first need to define the content we are going to be creating.

Content in Umbraco is based on Document Types which will define what type of data we can put into our content. A Document Type consists of a set of Properties - also called fields. A Property is made up of a Data Type which is a custom configuration of a Property Editor. Umbraco comes with a set of Property Editors, including a Text Area, a Date Picker, a picker for media items and many more.

As we go through this tutorial and start building the content for our Umbraco Heartcore project, you will learn more about each of these concepts and how they all work together.

In this tutorial we will cover the following topic:

• Creating a basic Document Type

• Adding and defining properties

• Creating a Document Type Collection

Document Types are managed from the Settings section in the Umbraco backoffice.

In order to get started with our first Document Type, follow these steps:

1. Right-click on the Document Types folder and choose + Create....

   • Or select the three ellipses on the right, when hovering the folder.

2. Choose the first option: Document Type.

We have now created our first Document Type. It's currently a blank slate, and in the next section, we will start adding groups and properties. This way we are able to add different types of data to our content.

Before we can start adding properties to the Document Type, we need to add a Group.

1. Select Add Group in the middle of the Document Type editor area.

2. Give the group a name like Content.

Now, let's add our first property to the Document Type.

1. Select Add Property.

2. In the Property Settings dialog, we'll start by giving the Property a name: Heading.

3. (Optional) Give the Property a description

1. Use the search field to find and select the pre-defined Textstring Data Type.

2. Submit the Property settings

We have now added the first Property to our Document Type.

Following the same steps, let's add a few more properties to the Content group:

With these properties added our Document Type now looks something like this:

Remember to save the Document Type by selecting the green Save button in the bottom-right corner.

This is a very simplified version of a Document Type, and you are welcome to add more groups and properties.

So far, we've created a single Document Type with some text fields and a media picker. Before we start creating the actual content, we are going to add a few more Document Types, to allow for more variation in our Content section.

We will now expand on our site by adding a Document Type Collection.

1. Right-click on the Document Types folder and choose + Create....

   • Or select the three ellipses on the right, when hovering the folder.

2. Choose the second option: Document Type Collection....

For our Umbraco Heartcore project, we will want it to be possible to create blog posts under a blog area.

1. Name the Parent Document Type Blog Area.

2. Name the Child Document Type Blog Post.

3. Select Create to setup the two Document Types.

Once the Document Types have been created you will be redirected to the Item Document Type - in our case the Blog Post.

Following the steps outlined earlier in this tutorial, add a Content group and the following properties to both the Blog Post and the Blog Area Document Types.

Blog Post

Blog Area

We should now have the three following Document Types in our Document Types tree:

The final thing we need to do before we start creating content is to check that our Document Types have the correct permissions.

1. Select the Home Page Document Type in the tree.

2. Navigate to the Permissions tab in the top-right corner.

3. We will want to allow that Home Page Document Type can be used to create content at root level, so make sure the Allow as root is checked.

With the permissions set, we are now ready to start working on the content for the Umbraco Heartcore project.

In this next step of the tutorial, we will start creating content. The content we're going to create will be defined by the Document Types we've created, and you will see how the choices we've made impact the editing experience one we start working with the content.

1. Go to the Content section.

2. Right-click on the Content tree and choose + Create....

   • Or select the three ellipses on the right, when hovering the Content tree.

We now have the option to create a content item based on our Home Page Document Type.

1. Select the Home Page.

2. Give the content item a name: Welcome to Umbraco Heartcore.

3. Add some text to both the Heading and the Intro text properties.

1. When you're happy with the content in the properties, select the Save and publish button in the bottom right.

So far, our Content section should look like this:

1. Right-click the root node, Welcome to Umbraco Heartcore, and choose Create...

   • Or select the three ellipses next to the node when hovering.

2. Select to create a Blog Area.

1. Once you're happy with how your blog post looks, select Save and publish.

2. To go back to the Blog Area, select the arrow next to the title of the blog post

You will now get an overview of the blog posts you've created. So far we've only created one, and creating more is done by selecting the Create Blog Post button in the top-left corner.

We have now covered the very basics of how to create content in the Umbraco backoffice.

Now you have some content in your Umbraco Heartcore project that you can start using.

You can use the Umbraco Heartcore REST API endpoints to fetch this content to where you need it.

We've built a few client libraries with samples that you can use for testing. You can find them in the

In order to test how the content you've created will be formatted, when fetched through the Umbraco Heartcore REST API endpoints, you can use the API Browser in the Settings section of the backoffice.

You can learn more about the API Browser and how to use it in the.

BASE URL: https://api.umbraco.io

Table of Contents

• Common Headers

• Authentication

Auth is required for this API meaning that you must supply a Bearer Token via an Authorization header or an API Key via an Authorization or Api-Key header.

If an error occurs you will receive a HTTP status code along with an API error code and an error message in the response body.

JSON example:

Get a list of all available relation types.

URL: /relation/type

Method: GET

Permissions required : Access to Settings section of the Umbraco Backoffice

Code: 200

Content Example:

Get a specific Relation Type by its alias.

URL: /relation/type/{alias}

Method: GET

Permissions required : Access to Settings section of the Umbraco Backoffice

Code: 200

Content Example:

A custom Grid Editor in Heartcore is built using custom elements.

Custom Grid Editors can be created under the Grid Editors tree in the Settings section.

The Grid Editor must export a default class inheriting from HTMLElement

export default class extends HTMLElement {
}

For the Grid to be able to save the value the editor must contain a set value(value) function and for the editor to be able to show the stored value, it must also contain a get value() function.

#value // private field
get value() { return this.#value }
set value(value) { this.#value = value }

The set value() is called when the editor is loaded and when the value is changed outside of the editor.

The get value() is called when the grid is saving and when the editor raises an .

External libraries can be imported by using the statement.

For example, if you want to use to create your web component it can be done like this

When importing libraries that registers variables or functions on the global object or custom elements it's advised to create a Module Alias and import that instead. By using Module Alias when importing we can ensure that only one version of a library is imported.

A Module Alias can be configured under Headless -> Custom Editors Configuration in the Settings section.

Accessing backoffice components like the Media Picker must be done using the .

Using this library reduces breaking changes in the exposed API that would otherwise happen if the backoffice components were accessed directly.

Currently, the library is exposing only a few components but Feature Requests and Pull Requests are more than welcome.

A is used to describe how the value is stored and returned by the REST and GraphQL API.

This allows for advanced configurations where, for example, an is converted to a URL.

The default Schema looks like this:

Since it has "type": "string" the different APIs will return the stored value as a string.

If the editor stores an object we can use "type": "object" instead, now the APIs will return the value as a JSON object.

By also adding properties, the API will be more clever about how the data is returned.

For example, an image editor that stores an UDI in the url field and the alt text in the altText field like this

Could have a schema like:

Notice how there's a "format":·"uri-reference" to the url property in the schema. Combined with "type": "string" the APIs knows this is a URI and will try to parse the value stored as an UDI and if successful, return the URL of the referenced item.

Currently, the following combinations are supported:

type: string format: uri-reference value: Content or Media UDI returned: A URL to the item if exists.\

type: string format: rich-text value: Rich Text, for example from the TinyMCE editor returned: The value where all a tags with a locallink href and img tags with a data-udi attribute is replaced with the correct links to the items.\

Currently, some functionality and components that do not work well in the preview pane. This includes integrations with the backoffice like Pickers and the Rich Text Editor. However, they still work when inserted on a page.

To make your custom editors less likely to break with future updates, do not use any of the backoffice JavaScript directly. Always use the .

If the library is missing any functionality, raise an issue on the .

Try to avoid relying on backoffice CSS-classes. Instead, it's recommended creating isolated elements using .

BASE URL: https://cdn.umbraco.io

This is the read-only API for delivering redirects, caused by moving or renaming content in the Umbraco backoffice, to any app, website, device, or platform.

To request redirects in a specific language, a culture parameter can be specified. When no culture is specified it's treated as invariant and the default language will be returned.

If an error occurs, you will receive a HTTP status code along with an API error code and an error message in the response body.

In /samples/Umbraco.Headless.Client.Samples.Web/ you will find a .NET 6.0-based MVC website implementation. It presents one possible approach to creating a website using Umbraco Heartcore for Content Delivery.

The sample is built around a sample project with the alias demo-headless. You can choose to test the sample with the sample project or connect the sample to your own project.

Prerequisites

• .NET 6.0

Run the sample on your local machine

Before running the sample, you must define which Umbraco Heartcore project you want to fetch content from.

• Open the appsettings.json found in samples/Umbraco.Headless.Client.Samples.Web/Umbraco.Headless.Client.Samples.Web/

• Add your project alias or use the default alias of the sample project, demo-headless

The ApiKey can be left blank when using the demo-headless sample project. If you are testing with your project and have chosen to protect the content exposed via the Content Delivery API, you will need an API Key. It is an option that has to be actively turned on via the Umbraco Backoffice in the Headless tree in the Settings section. Read more about this feature in the .

The MVC sample can be run in one of two ways:

Using a command-line tool, run the following two commands in the Umbraco.Headless.Client.Samples.Web folder:

The first command will restore the packages and the second will run the site. Alternatively, you can use the new hot-reload functionality:

To run the project and hot reload or recompile the project whenever changes are detected.

Run the application in Visual Studio or Visual Studio Code by hitting F5.

For the following section, a Umbraco Heartcore project with the following content structure will be used:

When you have connected the client project to your Umbraco project and run the client project, you will be presented with a default page. The page shows the properties and the data from the content node at the root of your website. This is because no view or controller has yet been defined for your content structure.

We will need to define and build a view and/or an MVC controller for the content types (Document Types) in our client project in order for us to start rendering content.

There are two ways to do this:

• Define a view file using the Document Type alias or

• Build a controller using the already defined UmbracoController

Each approach is explained in more detail below.

1. Create a model class for the content type you want to render, e.g., Models/HomePage.cs. Make sure the model extends the abstract class Content and that the properties you want to render from the Umbraco content node are defined as public properties with PascalCasing. PascalCasing means that a content node property called personName will be mapped to the PersonName property in the model.

2. Create a homePage.cshtml

When you build the solution and start it up, this view file will now be used to populate the frontend.

1. Right-click the Controllers folder in Visual Studio and select Add > Controller...

2. Select MVC Controller - Empty

3. Use the alias of the Document Type used on the root content node for the name of the controller, e.g. HomePageController

The controller is now in place but to show our content we also need to define a view.

1. Create a folder in /Views using the alias of the Document Type, e.g. /HomePage.

2. Create an Index.cshtml file in the new folder.

To render the data from the properties on our content, we need to use the @Model.PropertyName approach, where the value is the Name of the property you want to display the data from.

An example could be a text string property with the alias heading. To render the data from this property on the frontend, we will need to use @Model.Heading.

note To render data from a property, the property must be defined in the view model (@model), and it must match an alias on the corresponding content node from your Umbraco project.

Below is a complete example of how a view for a root node could look.

HTML is used to build the general structure of the article, while we use Razor to render data from our Umbraco Heartcore project.

BASE URL: https://api.umbraco.io

Table of Contents

• Common Headers

• Authentication

Auth is required for this API meaning that you must supply a Bearer Token via an Authorization header or an API Key via an Authorization or Api-Key header.

If an error occurs you will receive a HTTP status code along with an API error code and an error message in the response body.

JSON example:

Get all Member Groups.

URL: /member/group

Method: GET

Permissions required : Access to Member section of the Umbraco Backoffice

Code: 200

Content Example:

Get a specific Member Group by its name.

URL: /member/group/{name}

Method: GET

Permissions required : Access to Member section of the Umbraco Backoffice

Code: 200

Content Example:

Create a new Member Group.

URL: /member/group

Method: POST

Permissions required : Access to Member section of the Umbraco Backoffice

Code: 201

Content Example:

Delete an existing Member Group.

URL: /member/group/{name}

Method: DELETE

Permissions required : Access to Member section of the Umbraco Backoffice

Code: 200

Content Example:

DELETE https://api.umbraco.io/member/group/Elite%20Shoppers%20Group

Supported Property Editors

Below is a list of all the supported built-in Umbraco Property Editors and their GraphQL types. The type may depend on the configuration of the specific Property Editor.

Unsupported Editors

Below is a list of property editors which is not supported in GraphQL and will not be present in the generated schema.

This sample guide will cover how you can access and work with the from the client library.

• .NET/.NET Core (2.0 or newer) or .NET Framework (4.6.1 or newer)

1. Add the Umbraco.Headless.Client.Net package to your project.

The following changes have been released to all Heartcore sites.

Umbraco Workflow is now included as part of the offering on Umbraco Heartcore.

This integration gives Heartcore users powerful content approval and publishing workflows right out of the box. It makes it even easier to manage content governance in headless SaaS projects.

The free version of Umbraco Workflow is now automatically available for all Heartcore projects, allowing for structured review and publishing processes. If you have more advanced needs, a licensed version of Umbraco Workflow is also available. This version includes additional features and customization options, which can be obtained by contacting the Sales Team.

Learn more about and explore the comprehensive to unlock its full potential.