Learn more about which versions of the API is available as well as what version each endpoint uses in the Umbraco Heartcore API Documentation.

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

Be aware that the client library releases will have certain features available. The Forms API is unavailable in the initial release (1.0) of the .NET Core client library, for instance. This was made available in the 1.1 version of the client library.

In this section, you will find documentation on how to work with Umbraco Heartcore.

It includes REST API documentation, the basics of how to get started, and how to work with the available Client Libraries. Please note that Umbraco Heartcore is a specific type of project only available via Umbraco Cloud.

API Documentation for the Umbraco Heartcore REST API endpoints

Reference documentation for the APIs available, as well as details about common HTTP headers, versioning, REST Standard, and how to work with authentication and authorization.

• Authentication and Authorization

• Content Delivery API

• Content Management API

GraphQL

Reference documentation and tutorials for the GraphQL API.

• GraphQL API Documentation

• GraphQL Filter and Ordering Documentation

Versions and updates

Learn more about how we handle versioning and updates of Heartcore projects.

Frequently asked questions

Do you have questions that are not covered by this documentation? Please create an issue on our Documentation Issue Tracker or get in touch with Umbraco Support using the chat in the portal or write a mail to [email protected].

Access via an Accept-Language header

Acces via a Query String parameter

Content endpoints

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

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.

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.

Enabling preview for editors

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.

Here you'll get an overview of the preview urls created.

Right now the list is empty, so go ahead and click on Add Preview Url

This will open up a dialog on the right side of the backoffice, from where you can select which Root Content the preview url should be assigned to, and for which language it should be available for.

The Name field is used when there are multiple Preview Urls for a Content item.

Path Type controls how the path should be appended to the url, there are 3 different options.

• Append path to url: this will append the path of the Content item to the end of url.

• Path in querystring: this will add a querystring parameter to the url containing the path of the Content item.

• Id in querystring: this will add a querystring parameter to the url containing the id of the Content item.

Default controls whether this url is the default one when clicking the Preview button.

After you click save you'll return to the overview where the configured urls is shown. From here, you can edit or delete them.

Now if you go back to the Content section and click on the node you selected as the Root node or one of its child items, you should now have a Preview button in the bottom right section of the screen.

If multiple urls have been added for the Content item, there will be an arrow next to the button. When clicked, it will show all the Preview Urls available.

Accessing the Preview API

Now that we have setup the backoffice, we need to update our site to use the Preview API.

The Preview API is available on https://preview.umbraco.io and its endpoints are identical to the Content Delivery API, meaning that you can swap the url out if you don't use one of our Client Libraries.

If you are using the GraphQL API a preview argument can be passed to the root query fields.

If you are using the Node JS Client you set preview: true, set an apiKey as shown below, this switches all of the client.delivery functions to use the Preview API instead of the Content Delivery API.

For the .NET Client you'll create a new instance of the Umbraco.Headless.Client.Net.Delivery.ContentPreviewService. It's based on the IContentDeliveryService interface, which the ContentDeliveryService also implements.

To test that you get draft content back try changing the name of a Content item in the backoffice and click on Save, the change should now show up on your preview site but not on the live site.

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

1. Go to the Settings section.

2. Expand the Headless folder in the Settings tree.

3. Select Webhooks.

4. Click Create Webhook.

5. The Add webhook menu opens on the right side.

6. Enter the URL that the webhook should call.

7. Select the Event for which the webhook should be triggered.

8. Choose a Content Type you wish the webhook to be triggered on.

1. Click Create.

Once the webhook has been created you can manage it from the dashboard.

To temporarily pause/disable the webhook, click on Edit and toggle the Enabled field.

Webhook Configuraiton

Below is an overview of the webhook configuration options.

• Url

  The URL that Heartcore will send a POST request to when conditions are met.

• Events

  Backoffice or Management API action(s) that will cause the webhook request to be sent.

• Content Type (optional)

  Restrict the webhook to firing only if one of these content or media types were affected by one of the selected events.

• Enabled

  Toggle the webhook on or off. While disabled, no requests will be sent.

• Headers

  Configure custom HTTP headers to be sent with the request. May be useful for e.g. identifying the source of a request or for authorization.

Webhook behaviour specifics

Retries

When a webhook is triggered, if it fails to be processed by the endpoint Heartcore attempts to re-deliver it up to 9 more times.

• The endpoint returned a non HTTP-compliant response

• The endpoint returned an HTTP response with any status code other than a successful one (HTTP 200 - 299)

• The endpoint failed to respond within a timeout period

Redelivery

Webhooks are guaranteed to be delivered at least once. I.e. even for a webhook that is delivered successfully, in some situations that hook may be re-delivered.

Your webhook endpoints should thus be capable of handling multiple deliveries. Ideally they are idempotent.

Unresponsive endpoints

If an endpoint is slow or unresponsive, then webhook delivery may be briefly paused to that endpoint. No messages will be dropped (unless the retry count has been exceeded), but messages will be rescheduled for delivery a short time later. This gives the endpoint room to recover from traffic spikes.

Outgoing IP addresses

Webhooks will be fired from either of the two static IP addresses listed below.

When your endpoint refers to a service behind a firewall, you may need some additional firewall configuration. You should ensure that HTTP traffic from these addresses is allowed to pass through the firewall:

Or if your firewall needs a Classless Inter-Domain Routing (CIDR) Range: 20.86.53.156/31

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

1. Using Visual Studio

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.

2. Using the Command Line

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

Walkthrough of the Application

In order to use this application to its fullest, you will need a Heartcore Project on Umbraco Cloud. If you do not have a project yet, you can create a trial. It is recommended that you have a project with both content and media items.

If you do not have a project or trial you can also connect to demo-headless.

Once you have entered the alias of the project, you are presented with the following options

Option A - E uses the Content Delivery API and can be used for any Heartcore Project, which has public content.

Option F uses the Content Management API.. This means that an API Key is required to run this part of the sample. This is because it will create a new folder in the Media Library and upload an image to a new Media item.

Examples of the fetched data

Fetching the data looks like the following.

In the example above we have fetched the Content Tree. Is shows all the Parent and Child Nodes. The Child Node is shown by an indentation.

In the next example, we have fetched the Root media.

It is showing the name of the Media items and a direct link to each of the Media items.

Step 1: Create Content and Media in Your Heartcore Project

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.

5. Upload an image.

6. Note the content’s URL and media ID for fetching via the Node.js client.

Step 2: Initialize a Node.js Project

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:

Step 3: Install the Client Library

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

• Clone or download the Umbraco.Headless.Client.NodeJs client library from GitHub, or

• Run the following command in your terminal:

Step 4: Write the code to Fetch Content and Media

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:

Step 5: Run the Script

1. Open a terminal.

2. Navigate to your project folder.

3. Run the following command:

Exploring API Methods

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.

Content Delivery API

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 Content Delivery API sample repository on GitHub.

Content Management API

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 Content Management API sample repository on GitHub.

References

• Node.js Documentation

• Umbraco Heartcore API Documentation

• Create an Umbraco Heartcore project

Access via a Query String parameter

Common Headers

Errors

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 redirects

Get all redirect URLs.

The key is the URL of the content and the values are the URLs redirecting to the content.

URL: /redirect

Method: GET

Query Strings

Success Response

Code: 200

Content Example:

Get content by redirect URL

Get the destination URL and redirect URLs for a given path.

URL: /redirect/redirecturl?url={url}

Method: GET

Success Response

Code: 200

Content Example:

The umbracoUrlName property type alias works correctly in Umbraco Heartcore.

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.

Nodes

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

Dashboard

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.

Content

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

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.

Settings

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 type

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.

Media Types

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

Member Types

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.

Data Type

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.

Relation Types

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

Log Viewer

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.

Languages

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.

Headless

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 assigned API key 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 API Browser article.

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

Users

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 Backoffice users and API keys article.

Members

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.

Forms

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

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.

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 input event.

Using external libraries

External libraries can be imported by using the import statement.

For example, if you want to use Lit 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

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

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.

JSON Schema

A JSON Schema 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 UDI 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.\

Limitations and best practices

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 headless backoffice bridge.

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

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

Related articles

• Creating a Custom Grid Editor

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.

API Keys

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.

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.

Overview of tutorial

In this tutorial we will cover the following topic:

• Creating a basic Document Type

• Adding and defining properties

• Creating a Document Type Collection

• Setting permissions on Document Types

• Creating content

Creating a basic Document Type

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.

3. Give the new Document Type a name like Home Page.

4. Save the Document Type by selecting the green Save button in the bottom-right corner.

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.

Adding and defining properties

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

4. Select Add Editor

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.

Creating a Document Type Collection

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:

Setting permissions on Document Types

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.

4. Next to Allowed child node types select Add child, and in the dialog select our Blog Area Document Type.

   • Doing this, will allow us to create content of the Blog Area type under our Home Page.

5. Save the Document Type.

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

Creating content

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.

4. To choose an image for the PromoImage property, select the plus-sign.

5. In the dialog, you can do either of the following the choose an image:

   • Select the Upload button to choose an image from your file explorer or

   • Drag an image directly into the dialog.

6. Once you've chosen an image, select it from the dialog and select the green Select button at the bottom of the dialog.

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.

3. Give it a name: Blog.

4. (Optional) Add some text to the BlogDescription property.

5. To start adding blog posts to our Blog, right-click the Blog node in the Content tree.

6. Choose to Create... a new item based on the Blog Post Document Type.

7. Give the blog post a name and add some text to the Subtitle and MainContent properties.

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.

What now?

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.

Test with the provided samples

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

Testing with the API Browser

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 API Browser article.

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.

Errors

If an error occours 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 relation types

Get a list of all available relation types.

URL: /relation/type

Method: GET

Permissions required : Access to Settings section of the Umbraco Backoffice

Success Response

Code: 200

Content Example:

Get by alias

Get a specific Relation Type by its alias.

URL: /relation/type/{alias}

Method: GET

Permissions required : Access to Settings section of the Umbraco Backoffice

Success Response

Code: 200

Content Example:

Other editors and configuration: true GraphQL Type: String Can be used for filtering: true

Node type: Media Maximum number of items: 1 GraphQL Type: Media Can be used for filtering: true

Node type: Media Maximum number of items: not 1 GraphQL Type: [Media] Can be used for filtering: true

Node type: Member

Note: The Member editor configuration is not supported in the Multinode Treeepicker and will not be present in the generated schema.

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 Umbraco Forms documentation section.

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.

Retrieving a Form

Retrieving a Form using the REST API

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.

Retrieving a Form using the .NET Core Client Library

If you are a C# developer and work with .NET you can use the .NET Core Client Library 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:

Retrieving a Form using the NodeJS Client Library

If you are a JavaScript developer and work with NodeJS you can use the NodeJS Client Library 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.

Posting a Form entry

Posting a Form entry using the REST API

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.

Posting a Form entry using the .NET Core Client Library

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.

Posting a Form entry using the NodeJS Client Library

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.

Filters can be combined with AND and OR, e.g. if we want to find all content on level 2 or 3 that is updated after 2020-03-13 we write the following query.

Or if we want to get all of type person which names does not start with t we can write the following query.

We can combine AND, OR and NOT in a single query e.g. if we wan't to get all content on level 1 or 2 that does not start with b or j we can write the following query.

Filtering can also be applied to types returning Content and Media, e.g. if we want all content of type Post where the author name is Rasmus, we can write the following query.

Previewing

The collection can also return draft content by passing the preview argument with a boolean to the query. Draft content is always protected and requires an Api-Key.

Lets say we want to show all our products that haven't been published, we can write the following query.

Ordering

The collection can also be sorted by passing the orderBy argument to the query.

If orderBy is not specified the collections are ordered by path which is the order they appear in, in the Umbraco Backoffice tree.

Lets say we want to show all our products ordered by price in ascending order, we can write the following query.

We can even add multiple values to the orderBy argument to order by multiple fields. E.g. if we want to order products by price and then by name, we write the following query.

Paging

We can also limit the number of results returned by paging. To achieve this one can use first and after to do forward paging and last and before to do backward paging.

The cursor can be obtained by including the cursor field on an edge e.g. to get the first 50 products we can write the following query.

We can then use the cursor from the last item to get items that appear after that one. We can also request the PageInfo object which holds information on the start and end cursors and if there are more pages.

Combining filter, order, and paging

Everything shown up until now can be combined in a single query, the following query will get the first 50 products where the price is greater than 100 and order the result in ascending order by price and then by name.