1 of 60

Umbraco Heartcore

What is Umbraco Heartcore?

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.

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

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.

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.

GraphQL

Reference documentation and tutorials for the GraphQL API.

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

Compare with Umbraco CMS

Differences between Heartcore and Umbraco CMS

There are some differences between Heartcore and Umbraco CMS.

Managed Upgrades

With Umbraco Heartcore you won't need to worry about upgrading your project.

As Heartcore is a SasS product, we manage upgrades for your Heartcore project.

Template section

Umbraco Heartcore is a headless offering, meaning the frontend is decoupled from the backend. It is not possible to create templates in Umbraco Heartcore and the section is not available.

Custom Grid Editor

In Heartcore, the Grid editor is working a bit differently compared to the CMS. To see how to work with the Grid editor in Heartcore, have a look at the Creating a Custom Grid Editor Tutorial.

Getting Started

API Browser

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".

The user interface

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.

Explorer

The first thing you'll notice on the API browser, is an already defined URL. This is to define which area of the API you will be browsing; https://cdn.umbraco.io for the Content Delivery API and https://api.umbraco.io for the Content Management API.

You can also use the this field to manually add query strings to the URL and search the API endpoints that way.

The URL will be updated automatically as you browse the API using the links in the bottom of the Explorer section.

In the Custom Request Headers you can define which headers to use when browsing the API endpoints. The umb-project-alias header will have been added for you already, and in the content section the Accept-Language is also set by default.

The Properties will show you all the available properties on the object / piece of data that you are calling through the API.

Below the properties, is a section with a list of Links. These are links that you can use to make various GET requests from the endpoint you are already using.

The final section in the explorer is the Embedded resources. Here you can see the properties for each embedded resource on the endpoint you are calling, as well as links to continue browser the API based on each of those resources.

Inspector

In the right side, you'll find the inspector section. While exploring the API, you will see that information is being posted in the Response header and the Response Body boxes.

The first box, the Response Header, will show you the status of the API endpoint you are currently browsing and tell you which headers is included in the response.

In the Response Body box the raw JSON data will be output based on the API endpoint you're calling.

Backoffice Users and API Keys

Managing Umbraco Heartcore Users and API keys

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.

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.

Environments

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.

What is an environment?

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.

Manage environments

When you upgrade your Heartcore project from the Starter to the Standard plan, it will be possible to add a Development environment. Once you've upgraded to the Professional plan, you will be able to add the Staging environment as well.

You can add and remove the environments any time you want, as long as you have multiple environments enabled.

Adding and removing environments is done from the Project page in the Cloud Portal.

Please note you will need to restart environments after they have been set up or removed from your project. This is to ensure that the Umbraco Deploy configuration is updated.

Below is a screenshot of how the project page looks on the standard plan with only the Live environment. There's an option to add a Development environment. How this page looks is dependent on the plan your project is using.

GraphQL Playground

Documentation for Umbraco Heartcore GraphQL Playground.

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.

Accessing GraphQL Playground

Log into the project backoffice
Navigate to the Settings dashboard
Find the Headless tree near the bottom of the navigation list
Click on GraphQL

From there, you can start querying as soon as your content is published.

Features

Documentation & Schema

The GraphQL Playground's build-in documentation and schema browser can be found on the left toolbar

This button will open a panel that grants you a quick overview of how content is structured using the Document Types in your solution.

It also gives an idea of how to access specific properties on each Document Type, nested properties, and properties from compositions.

At the same time, it also explains relationships between specific objects and properties in your solution.

This will be updated automatically as you change the project's schema meaning Document Types, Data Types, Document Type Compositions, and Document Type Elements.

Running GraphQL queries

To run a query use the left side of the GraphQL Playground to type in your query - could be something as basic as getting the names of all your content pages:

{
  allContent {
    items {
      name
    }
  }
}

The Heartcore GraphQL endpoint only supports queries - other operation types, that is mutations and subscriptions, are not supported.

After that, press the "Play" button sitting in the center of the Playground. If the query is constructed correctly, the results will be loaded into the right section.

When you are satisfied with the result, you can copy the client URL (CURL) by clicking the COPY CURL button located in the top part of the Playground, next to the address bar.

Sending HTTP headers

GraphQL Playground supports requests with HTTP headers if an authorization token is needed. The HTTP HEADERS section can be accessed from the bottom-right corner of the Playground window. By default, it contains the umb-project-alias header, the alias of your Heartcore project. It is possible to add multiple headers.

Query variables

It is also possible to define variables for queries - such variables's values can be changed in the bottom-left corner of the Playground window, next to the HTTP HEADERS section.

History

If you happen to make an amazing query and afterward erase it by accident, you can re-use it by finding it in the History.

The History pane can be opened by clicking the history button in the toolbar to the left.

Prettify

The Playground gives you an option to "prettify" your query with a click of a button, which makes it easier for humans to read.

Persisted Queries

Create a new persisted query

Click the Create Persisted Query button
Enter a name for the query in the new query editor that appears
Write your query in the editor
Click the Save button

Update a persisted query

Find the query you want to update in the persisted queries list
Click on the name of the query
Make your changes in the editor that appears with the query
Click the Save button

Delete a persisted query

Find the query you want to delete in the persisted queries list
Click on the name of the query
Click the action menu in the top right corner of the editor with the query
Click the Delete button
Confirm the deletion

Preview

Prerequisites

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.

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 always protected and requires an API Key to be passed with the request.

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

query {
  allContent(
    preview: true
  ) {
    edges {
      node {
        name
      }
    }
  }
}

import {Client} from '@umbraco/headless-client'

const client = new Client({
  projectAlias: 'your-project-alias',
  apiKey: 'your-api-key',
  language: 'iso-code',
  preview: true,
})

using Umbraco.Headless.Client.Net.Delivery;

class Program
{
    static async Task Main(string[] args)
    {
        var previewService = new ContentPreviewService("your-project-alias", "your-api-key");
    }
}

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.

Tour of the Backoffice

Tour of Umbraco Heartcore backoffice

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

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.

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

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

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.

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.

Webhooks

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.

Uses

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.

Creating a webhook

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

Go to the Settings section.
Expand the Headless folder in the Settings tree.
Click Create Webhook.
The Add webhook menu opens on the right side.
Enter the URL that the webhook should call.
Select the Event for which the webhook should be triggered.

Selecting the Content Type is the initial step. This field is not mandatory.

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

Content and media transfer / restore

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

In order to be able to transfer/restore content and media, you need to make sure that the environments you're transferring between are in sync.

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.

API Documentation

Documentation for Umbraco Heartcore REST APIs

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

REST API Standard

System level properties

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.

API Browser

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.

Common API Features

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.

API Access

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.

Access via Umb-Project-Alias header

Access via Query String parameter

Versioning

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.

Access via an api-version header

Access via Query String parameter

Access via Content negotiation

Authentication and Authorization

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

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

Access via the Authorization header

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:)

Access via an Api-Key header

Bearer token

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.

Member authentication

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.

Do note that you will need an API key header if the Content Delivery API cdn.umbraco.io is set to protected via the backoffice.

Member Bearer token

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.

Content Delivery

Documentation for Heartcore Content Delivery APIs

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.

Redirect API

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.

Cultures

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.

Access via an Accept-Language header

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

Access via a Query String parameter

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

Common Headers

Accept-Language: {culture}
Api-Version: 2.3
Umb-Project-Alias: {project-alias}

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.

Status Code

Error Code

Message

400

AmbiguousCulture

The following cultures were requested: {cultures}. At most, only a single culture may be specified. Please update the intended culture and retry the request.

400

LanguageForCultureNotFound

Could not find a language for culture {culture}.

401

Unauthorized

Authorization has been denied for this request.

500

InternalServerError

Internal server error.

JSON example:

{
  "error": {
    "code": "LanguageForCultureNotFound",
    "message": "Could not find a language for culture en-GB."
  }
}

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

?page={integer=1}
?pageSize={integer=10}

The maximum page size is 1000.

Success Response

Code: 200

Content Example:

{
    "redirects": {
        "/root5/": [
            "/root4",
            "/root3",
            "/root2",
            "/root"
        ],
        "/root5/child/": [
            "/root4/child",
            "/root3/child",
            "/root2/child",
            "/root/child"
        ]
    },
    "_totalItems": 2,
    "_totalPages": 1,
    "_page": 1,
    "_pageSize": 10,
    "_links": {
        "self": {
            "href": "https://cdn.umbraco.io/redirect?page=1&pageSize=10"
        }
    }
}

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:

{
    "url": "/home",
    "redirectUrls": [
        "/home-redirect-example-1",
        "/home-redirect-example-2"
    ]
}

Content Management

Documentation for Heartcore Content Management APIs

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.

Umbraco Forms

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

API version: 2.1

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 occurs you will receive a HTTP status code along with an API error code and an error message in the response body.

JSON example:

Field types

The field types gets mapped to a more machine friendly name

Get forms

Gets all forms.

URL: /forms

Method: GET

Permissions required : Access to Forms section of the Umbraco Backoffice

Success Response

Code: 200

Content Example:

Get by ID

Get a specific form by its ID.

URL: /forms/{id}

Method: GET

Permissions required : Access to Forms section of the Umbraco Backoffice

Success Response

Code: 200

Content Example:

Submit entry

Submit form entries for a specific Form - this is what you would use when a form is submitted from your presentation layer.

URL: /forms/{id}/entries

Method: POST

Permissions required : Access to Forms section of the Umbraco Backoffice

Request

The JSON property names are the form field alias

Success Response

Code: 202

Content

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

Common Headers

Authentication

Authentication is required for this API. This means that you must supply a Bearer Token via an Authorization header. Alternatively, you can supply an API Key via an Authorization or Api-Key header.

Permissions

In addition to the specific permissions listed under each endpoint, all requests requires:

Access to the Content Section of the Umbraco Backoffice and
That the content being accessed is beneath the users start node configured in Umbraco

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 root content

Get all content at the root of the tree, which the authorized user has access to according to the 'Start node'-permissions.

URL: /content

Method: GET

Permissions required : Browse Node

Success Response

Code: 200

Content Example:

Get by id

Get specific content item by GUID ID. Includes all language variations.

URL: /content/{id}

Method: GET

Permissions required : Browse Node

Success Response

Code: 200

Content Example:

Get children

Get a list of children (content items) by parent GUID ID. Includes all language variations per content item.

URL: /content/{id}/children

Method: GET

Query Strings

Permissions required : Browse Node

Success Response

Code: 200

Content Example:

Create content

Create a new content item with one or more language variations.

All newly created content will be DRAFT by default. If you want to publish it you will need to issue a publish request as well.

URL: /content

Method: POST

Permissions required : Create

Request

In this example only one language exists, so the properties are marked with $invariant in the create request. If multiple languages exists the culture for each of the languages would be defined for each of the properties - example: "name": { "en-US": "Another one", "da-DK": "Endnu en" }.

Success Response

Code: 201

Content Example:

Create content with files

Create a new content item with one or more language variations and files.

When content contains an upload field it is possible to send a file along with the request to create new content. This is done by sending a multi-part request with the JSON body and the file.

If the content item doesn't include files then you can send a standard reqeust with a JSON payload to create a new content item.

All newly created content will be DRAFT by default. If you want to publish it you will need to issue a publish request as well.

URL: /content

Method: POST

Header: Content-Type: multipart/form-data; boundary=MultipartBoundry

Permissions required : Create

Request

The request must contain a field named content that contains the content JSON.

For the files being uploaded the field names must be in the format propertyName.culture. An example could be when the content has an upload property with the name fileUpload and the file is being uploaded to the en-US lanugage. In that case the field name should be fileUpload.en-US.

The property must also be includud in the content JSON and the value shoud be the filename.

Success Response

Code: 201

Content Example:

Update content

Updates an existing content item that has one or more language variations.

URL: /content/{id}

Method: PUT

Permissions required : Update

Request

In this example only one language exists, so the properties are marked with $invariant. If multiple languages existed the culture for each of the languages would be defined for each of the properties. Ie.: "name": { "en-US": "Another one", "da-DK": "Endnu en" }.

Success Response

Code: 200

Content Example:

Publish content

Publish specific content item with all language variations or for a specific language.

URL: /content/{id}/publish

Method: PUT

Query Strings

Permissions required : Publish

Success Response

Code: 200

Content Example:

Unpublish content

Unpublish specific content item with all language variations or for a specific language.

URL: /content/{id}/unpublish

Method: PUT

Query Strings

Permissions required : Unpublish

Success Response

Code: 200

Content Example:

Delete content

Delete a specific content item with all its language variations.

URL: /content/{id}

Method: DELETE

Permissions required : Delete

Success Response

Code: 200

Content Example:

DELETE https://api.umbraco.io/content/041067a0-74f5-4d03-92af-40c3c0aa13e7

Content Types

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

Common Headers

Authentication

Authentication is required for this API. You must supply a Bearer Token via an Authorization header or an API Key through 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 Content Types

Get a list of all available Content Types.

URL: /content/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 Content Type by its alias.

URL: /content/type/{alias}

Method: GET

Permissions required : Access to Settings section of the Umbraco Backoffice

Success Response

Code: 200

Content Example:

Media Types

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

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 Media Types

Get a list of all available Media Types.

URL: /media/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 Media Type by its alias.

URL: /media/type/{alias}

Method: GET

Permissions required : Access to Settings section of the Umbraco Backoffice

Success Response

Code: 200

Content Example:

Backoffice

Client Libraries

Tutorials

Release Notes

Content

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

Common Headers

Accept-Language: {culture}
Api-Version: 2
Umb-Project-Alias: {project-alias}

Depth

The depth querystring parameter controls how many levels of referenced Content or Media items that is included in the result.

Lets say a Content item have a Multi Node Tree Picker and one of the Content items that can be picked have a Media Picker. In this case, if the level is set to 1 the returned data will contain the referenced Content items, but their Media property will be null. To include the Media property (which is at level 2) the depth parameter should be 2 or higher.

The lowest supported depth value is 0 and the highest is 5.

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.

Status Code

Error Code

Message

400

AmbiguousCulture

The following cultures were requested: {cultures}. At most, only a single culture may be specified. Please update the intended culture and retry the request.

400

LanguageForCultureNotFound

Could not find a language for culture {culture}.

401

Unauthorized

Authorization has been denied for this request.

404

NotFound

Published content with id '{id}' and culture '{culture}' could not be found.

500

InternalServerError

Internal server error.

JSON example:

{
  "error": {
    "code": "LanguageForCultureNotFound",
    "message": "Could not find a language for culture en-GB."
  }
}

Get root content

Gets all published content at the root of the tree.

URL: /content

Method: GET

Query Strings

?hyperlinks={boolean=true}
?contentType={string}

Success Response

Code: 200

Content Example:

{
  "_links": {
    "self": {
      "href": "https://cdn.umbraco.io/content"
    },
    "content": [
      {
        "href": "https://cdn.umbraco.io/content/e8ad9b65-cff6-4952-ac5b-efe56a60db62"
      }
    ]
  },
  "_embedded": {
    "content": [
      {
        "_creatorName": "Rasmus",
        "_url": "/people/",
        "_urls": {
            "en-us": "/people/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": true,
        "_level": 1,
        "_createDate": "2019-06-17T13:46:24.543Z",
        "_id": "e8ad9b65-cff6-4952-ac5b-efe56a60db62",
        "_updateDate": "2019-06-17T13:46:54.97Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/e8ad9b65-cff6-4952-ac5b-efe56a60db62"
          }
        },
        "contentTypeAlias": "people",
        "name": "People",
        "sortOrder": 1,
        "seoMetaDescription": "",
        "keywords": [],
        "umbracoNavihide": false,
        "pageTitle": "Nice crazy people",
        "featuredPeople": null
      },
      {
        "_creatorName": "Rasmus",
        "_url": "/products/",
        "_urls": {
            "en-us": "/products/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": true,
        "_level": 1,
        "_createDate": "2019-06-17T13:46:24.093Z",
        "_id": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "_updateDate": "2019-09-17T14:43:14.827Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "products",
        "name": "Products",
        "sortOrder": 3,
        "seoMetaDescription": "",
        "keywords": [],
        "umbracoNavihide": false,
        "pageTitle": "Our Gorgeous Selection",
        "defaultCurrency": "€",
        "featuredProducts": [
          {
            "_creatorName": "Rasmus",
            "_url": "/products/biker-jacket/",
            "_writerName": "Rasmus",
            "_hasChildren": false,
            "_level": 2,
            "_createDate": "2019-06-17T13:46:24.497Z",
            "_id": "262beb70-53a6-49b8-9e98-cfde2e85a78e",
            "_updateDate": "2019-09-16T11:25:44.433Z",
            "_links": null,
            "contentTypeAlias": "product",
            "name": "Biker Jacket",
            "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
            "sortOrder": 7,
            "productName": "Biker Jacket",
            "price": 199.0,
            "description": "Donec rutrum congue leo eget malesuada. Vivamus suscipit tortor eget felis porttitor volutpat.",
            "sku": "UMB-BIKER-JACKET",
            "photos": null,
            "features": [
              {
                "contentTypeAlias": "feature",
                "featureName": "Free shipping",
                "featureDetails": "Isn't that awesome - you only pay for the product"
              },
              {
                "contentTypeAlias": "feature",
                "featureName": "1 Day return policy",
                "featureDetails": "You'll need to make up your mind fast"
              },
              {
                "contentTypeAlias": "feature",
                "featureName": "100 Years warranty",
                "featureDetails": "But if you're satisfied it'll last a lifetime"
              }
            ]
          },
          {
            "_creatorName": "Rasmus",
            "_url": "/products/tattoo/",
            "_urls": {
                "en-us": "/products/tattoo/"
            },
            "_writerName": "Rasmus",
            "_hasChildren": false,
            "_level": 2,
            "_createDate": "2019-06-17T13:46:24.14Z",
            "_id": "df1eb830-411b-4d41-a343-3917b76d533c",
            "_updateDate": "2019-06-26T22:11:05.727Z",
            "_links": null,
            "contentTypeAlias": "product",
            "name": "Tattoo",
            "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
            "sortOrder": 0,
            "productName": "Tattoo",
            "price": 499.0,
            "description": "Cras ultricies ligula sed magna dictum porta.",
            "sku": "UMB-TATTOO",
            "photos": null,
            "features": []
          },
          {
            "_creatorName": "Rasmus",
            "_url": "/products/unicorn/",
            "_urls": {
                "en-us": "/products/unicorn/"
            },
            "_writerName": "Rasmus",
            "_hasChildren": false,
            "_level": 2,
            "_createDate": "2019-06-17T13:46:24.187Z",
            "_id": "4e96411a-b8e1-435f-9322-2faee30ef5f2",
            "_updateDate": "2019-06-26T22:11:05.803Z",
            "_links": null,
            "contentTypeAlias": "product",
            "name": "Unicorn",
            "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
            "sortOrder": 1,
            "productName": "Unicorn",
            "price": 249.0,
            "description": "Quisque velit nisi, pretium ut lacinia in, elementum id enim. Vivamus magna justo, lacinia eget consectetur sed, convallis at tellus. Cras ultricies ligula sed magna dictum porta.",
            "sku": "UMB-UNICORN",
            "photos": null,
            "features": []
          }
        ]
      }
    ]
  }
}

Get by id

Get a single published content by its ID.

URL: /content/{id}

Method: GET

Query Strings

?hyperlinks={boolean=true}
?depth={integer=1}

Success Response

Code: 200

Content Example:

{
  "_creatorName": "Rasmus",
  "_url": "/products/",
  "_urls": {
    "en-us": "/products/"
  },
  "_writerName": "Rasmus",
  "_hasChildren": true,
  "_level": 1,
  "_createDate": "2019-06-17T13:46:24.093Z",
  "_id": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
  "_updateDate": "2019-09-17T14:43:14.827Z",
  "_links": {
    "self": {
      "href": "https://cdn.umbraco.io/content/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
    },
    "featuredproducts": [
      {
        "href": "https://cdn.umbraco.io/content/262beb70-53a6-49b8-9e98-cfde2e85a78e",
        "title": "Biker Jacket"
      },
      {
        "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c",
        "title": "Tattoo"
      },
      {
        "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2",
        "title": "Unicorn"
      }
    ],
    "root": {
      "href": "https://cdn.umbraco.io/content"
    },
    "children": {
      "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324/children"
    },
    "ancestors": {
      "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324/ancestors"
    },
    "descendants": {
      "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324/descendants"
    },
    "parent": {
      "href": "https://cdn.umbraco.io/content"
    }
  },
  "contentTypeAlias": "products",
  "name": "Products",
  "sortOrder": 3,
  "seoMetaDescription": "",
  "keywords": [],
  "umbracoNavihide": false,
  "pageTitle": "Our Gorgeous Selection",
  "defaultCurrency": "€",
  "featuredProducts": [
    {
      "_creatorName": "Rasmus",
      "_url": "/products/biker-jacket/",
      "_urls": {
        "en-us": "/products/biker-jacket/"
      },
      "_writerName": "Rasmus",
      "_hasChildren": false,
      "_level": 2,
      "_createDate": "2019-06-17T13:46:24.497Z",
      "_id": "262beb70-53a6-49b8-9e98-cfde2e85a78e",
      "_updateDate": "2019-09-16T11:25:44.433Z",
      "_links": {
        "photos": {
          "href": "https://cdn.umbraco.io/media/55514845-b8bd-487c-b370-9724852fd6bb",
          "title": "Biker Jacket"
        }
      },
      "contentTypeAlias": "product",
      "name": "Biker Jacket",
      "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
      "sortOrder": 7,
      "productName": "Biker Jacket",
      "price": 199.0,
      "description": "Donec rutrum congue leo eget malesuada. Vivamus suscipit tortor eget felis porttitor volutpat.",
      "sku": "UMB-BIKER-JACKET",
      "photos": null,
      "features": [
        {
          "contentTypeAlias": "feature",
          "featureName": "Free shipping",
          "featureDetails": "Isn't that awesome - you only pay for the product"
        },
        {
          "contentTypeAlias": "feature",
          "featureName": "1 Day return policy",
          "featureDetails": "You'll need to make up your mind fast"
        },
        {
          "contentTypeAlias": "feature",
          "featureName": "100 Years warranty",
          "featureDetails": "But if you're satisfied it'll last a lifetime"
        }
      ]
    },
    {
      "_creatorName": "Rasmus",
      "_url": "/products/tattoo/",
      "_urls": {
        "en-us": "/products/tattoo/"
      },
      "_writerName": "Rasmus",
      "_hasChildren": false,
      "_level": 2,
      "_createDate": "2019-06-17T13:46:24.14Z",
      "_id": "df1eb830-411b-4d41-a343-3917b76d533c",
      "_updateDate": "2019-06-26T22:11:05.727Z",
      "_links": {
        "photos": {
          "href": "https://cdn.umbraco.io/media/20e3a8ff-ad1b-4fe9-b48c-b8461c46d2d0",
          "title": "Tattoo"
        }
      },
      "contentTypeAlias": "product",
      "name": "Tattoo",
      "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
      "sortOrder": 0,
      "productName": "Tattoo",
      "price": 499.0,
      "description": "Cras ultricies ligula sed magna dictum porta.",
      "sku": "UMB-TATTOO",
      "photos": null,
      "features": []
    },
    {
      "_creatorName": "Rasmus",
      "_url": "/products/unicorn/",
      "_urls": {
        "en-us": "/products/unicorn/"
      },
      "_writerName": "Rasmus",
      "_hasChildren": false,
      "_level": 2,
      "_createDate": "2019-06-17T13:46:24.187Z",
      "_id": "4e96411a-b8e1-435f-9322-2faee30ef5f2",
      "_updateDate": "2019-06-26T22:11:05.803Z",
      "_links": {
        "photos": {
          "href": "https://cdn.umbraco.io/media/1bc5280b-8658-4027-89d9-58e2576e469b",
          "title": "Unicorn"
        }
      },
      "contentTypeAlias": "product",
      "name": "Unicorn",
      "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
      "sortOrder": 1,
      "productName": "Unicorn",
      "price": 249.0,
      "description": "Quisque velit nisi, pretium ut lacinia in, elementum id enim. Vivamus magna justo, lacinia eget consectetur sed, convallis at tellus. Cras ultricies ligula sed magna dictum porta.",
      "sku": "UMB-UNICORN",
      "photos": null,
      "features": []
    }
  ]
}

Get by URL

Get a single published content by its URL.

URL: /content/url?url={url}

Method: GET

Query Strings

?hyperlinks={boolean=true}
?depth={integer=1}

Success Response

Code: 200

Content Example:

{
  "_creatorName": "Rasmus",
  "_url": "/people/",
  "_urls": {
    "en-us": "/people/"
  },
  "_writerName": "Rasmus",
  "_hasChildren": true,
  "_level": 1,
  "_createDate": "2019-06-17T13:46:24.543Z",
  "_id": "e8ad9b65-cff6-4952-ac5b-efe56a60db62",
  "_updateDate": "2019-06-17T13:46:54.97Z",
  "_links": {
    "self": {
      "href": "https://cdn.umbraco.io/content/e8ad9b65-cff6-4952-ac5b-efe56a60db62"
    }
  },
  "contentTypeAlias": "people",
  "name": "People",
  "sortOrder": 1,
  "seoMetaDescription": "",
  "keywords": [],
  "umbracoNavihide": false,
  "pageTitle": "Nice crazy people",
  "featuredPeople": null
}

Get by type

Get content by its Content Type.

Use the Content Type alias to filter all returned content to that specific type.

Example: GET /content/type?contentType=product gets all content based on the product Content Type.

URL: /content/type?contentType={string}

Method: GET

Query Strings

?hyperlinks={boolean=true}
?page={integer=1}
?pageSize={integer=10}

Success Response

Code: 200

Content Example:

{
  "_totalItems": 3,
  "_totalPages": 1,
  "_page": 1,
  "_pageSize": 10,
  "_links": {
    "self": {
      "href": "https://cdn.umbraco.io/content/type?contentType=product&page=1&pageSize=10"
    },
    "page": {
      "href": "https://cdn.umbraco.io/content/type{?contentType,page,pageSize}",
      "templated": true
    },
    "root": {
      "href": "https://cdn.umbraco.io/content{?contentType}",
      "templated": true
    },
    "content": [
      {
        "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c"
      },
      {
        "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2"
      },
      {
        "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752"
      }
    ]
  },
  "_embedded": {
    "content": [
      {
        "_creatorName": "Rasmus",
        "_url": "/products/tattoo/",
        "_urls": {
          "en-us": "/products/tattoo/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": false,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.14Z",
        "_id": "df1eb830-411b-4d41-a343-3917b76d533c",
        "_updateDate": "2019-06-26T22:11:05.727Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c"
          },
          "photos": {
            "href": "https://cdn.umbraco.io/media/20e3a8ff-ad1b-4fe9-b48c-b8461c46d2d0",
            "title": "Tattoo"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content{?contentType}",
            "templated": true
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "product",
        "name": "Tattoo",
        "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "sortOrder": 0,
        "productName": "Tattoo",
        "price": 499.0,
        "description": "Cras ultricies ligula sed magna dictum porta.",
        "sku": "UMB-TATTOO",
        "photos": {
          "_creatorName": "Rasmus",
          "_url": "https://media.umbraco.io/my-headless-site/media/20e3a8ffad1b4fe9b48cb8461c46d2d0/00000006000000000000000000000000/7371127652_e01b6ab56f_b.jpg",
          "_writerName": "Rasmus",
          "_hasChildren": false,
          "_level": 2,
          "_createDate": "2019-06-17T13:46:42.503Z",
          "_id": "20e3a8ff-ad1b-4fe9-b48c-b8461c46d2d0",
          "_updateDate": "2019-06-17T13:46:42.503Z",
          "_links": null,
          "mediaTypeAlias": "Image",
          "name": "Tattoo",
          "parentId": "6d5bf746-cb82-45c5-bd15-dd3798209b87",
          "sortOrder": 0,
          "umbracoFile": {
            "src": "/media/20e3a8ffad1b4fe9b48cb8461c46d2d0/00000006000000000000000000000000/7371127652_e01b6ab56f_b.jpg",
            "focalPoint": null,
            "crops": null
          },
          "umbracoWidth": 683,
          "umbracoHeight": 1024,
          "umbracoBytes": 258796,
          "umbracoExtension": "jpg"
        },
        "features": []
      },
      {
        "_creatorName": "Rasmus",
        "_url": "/products/unicorn/",
        "_urls": {
          "en-us": "/products/unicorn/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": false,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.187Z",
        "_id": "4e96411a-b8e1-435f-9322-2faee30ef5f2",
        "_updateDate": "2019-06-26T22:11:05.803Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2"
          },
          "photos": {
            "href": "https://cdn.umbraco.io/media/1bc5280b-8658-4027-89d9-58e2576e469b",
            "title": "Unicorn"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content{?contentType}",
            "templated": true
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "product",
        "name": "Unicorn",
        "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "sortOrder": 1,
        "productName": "Unicorn",
        "price": 249.0,
        "description": "Quisque velit nisi, pretium ut lacinia in, elementum id enim. Vivamus magna justo, lacinia eget consectetur sed, convallis at tellus. Cras ultricies ligula sed magna dictum porta.",
        "sku": "UMB-UNICORN",
        "photos": {
          "_creatorName": "Rasmus",
          "_url": "https://media.umbraco.io/my-headless-site/media/1bc5280b8658402789d958e2576e469b/00000006000000000000000000000000/14272036539_469ca21d5c_h.jpg",
          "_writerName": "Rasmus",
          "_hasChildren": false,
          "_level": 2,
          "_createDate": "2019-06-17T13:46:42.64Z",
          "_id": "1bc5280b-8658-4027-89d9-58e2576e469b",
          "_updateDate": "2019-06-17T13:46:42.64Z",
          "_links": null,
          "mediaTypeAlias": "Image",
          "name": "Unicorn",
          "parentId": "6d5bf746-cb82-45c5-bd15-dd3798209b87",
          "sortOrder": 0,
          "umbracoFile": {
            "src": "/media/1bc5280b8658402789d958e2576e469b/00000006000000000000000000000000/14272036539_469ca21d5c_h.jpg",
            "focalPoint": null,
            "crops": null
          },
          "umbracoWidth": 1067,
          "umbracoHeight": 1600,
          "umbracoBytes": 367954,
          "umbracoExtension": "jpg"
        },
        "features": []
      },
      {
        "_creatorName": "Rasmus",
        "_url": "/products/ping-pong-ball/",
        "_urls": {
          "en-us": "/products/ping-pong-ball/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": false,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.247Z",
        "_id": "d390a562-107d-4f02-8df7-57aa86bad752",
        "_updateDate": "2019-06-26T22:11:05.847Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752"
          },
          "photos": {
            "href": "https://cdn.umbraco.io/media/c09ec77f-08e3-466a-ac58-c979befd3cd6",
            "title": "Ping Pong Ball"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content{?contentType}",
            "templated": true
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "product",
        "name": "Ping Pong Ball",
        "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "sortOrder": 2,
        "productName": "Ping Pong Ball",
        "price": 2.0,
        "description": "Vivamus suscipit tortor eget felis porttitor volutpat. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Cras ultricies ligula sed magna dictum porta.",
        "sku": "UMB-PINGPONG",
        "photos": {
          "_creatorName": "Rasmus",
          "_url": "https://media.umbraco.io/my-headless-site/media/c09ec77f08e3466aac58c979befd3cd6/00000006000000000000000000000000/5852022211_9028df67c0_b.jpg",
          "_writerName": "Rasmus",
          "_hasChildren": false,
          "_level": 2,
          "_createDate": "2019-06-17T13:46:42.767Z",
          "_id": "c09ec77f-08e3-466a-ac58-c979befd3cd6",
          "_updateDate": "2019-06-17T13:46:42.767Z",
          "_links": null,
          "mediaTypeAlias": "Image",
          "name": "Ping Pong Ball",
          "parentId": "6d5bf746-cb82-45c5-bd15-dd3798209b87",
          "sortOrder": 0,
          "umbracoFile": {
            "src": "/media/c09ec77f08e3466aac58c979befd3cd6/00000006000000000000000000000000/5852022211_9028df67c0_b.jpg",
            "focalPoint": null,
            "crops": null
          },
          "umbracoWidth": 1024,
          "umbracoHeight": 683,
          "umbracoBytes": 205417,
          "umbracoExtension": "jpg"
        },
        "features": []
      }
    ]
  }
}

Get ancestors

Get ancestors of a single published content.

URL: /content/{id}/ancestors

Method: GET

Query Strings

?hyperlinks={boolean=true}
?contentType={string}

Success Response

Code: 200

Content Example:

{
  "_links": {
    "self": {
      "href": "https://cdn.umbraco.io/content/4f0b7052-d854-43b5-bb7c-6c82af4d96d1/ancestors"
    },
    "content": [
      {
        "href": "https://cdn.umbraco.io/content/e8ad9b65-cff6-4952-ac5b-efe56a60db62"
      },
      {
        "href": "https://cdn.umbraco.io/content/32ded4f8-191a-418e-a4c9-0dabceba90ee"
      }
    ]
  },
  "_embedded": {
    "content": [
      {
        "_creatorName": "Rasmus",
        "_url": "/home/people/",
        "_urls": {
          "en-us": "/home/people/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": true,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.543Z",
        "_id": "e8ad9b65-cff6-4952-ac5b-efe56a60db62",
        "_updateDate": "2019-06-17T13:46:54.97Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/e8ad9b65-cff6-4952-ac5b-efe56a60db62"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content"
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/e8ad9b65-cff6-4952-ac5b-efe56a60db62/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/e8ad9b65-cff6-4952-ac5b-efe56a60db62/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/e8ad9b65-cff6-4952-ac5b-efe56a60db62/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/32ded4f8-191a-418e-a4c9-0dabceba90ee"
          }
        },
        "contentTypeAlias": "people",
        "name": "People",
        "parentId": "32ded4f8-191a-418e-a4c9-0dabceba90ee",
        "sortOrder": 0,
        "seoMetaDescription": "",
        "keywords": [],
        "umbracoNavihide": false,
        "pageTitle": "Nice crazy people",
        "featuredPeople": null
      },
      {
        "_creatorName": "Rasmus",
        "_url": "/home/",
        "_urls": {
          "en-us": "/home/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": true,
        "_level": 1,
        "_createDate": "2019-06-17T13:46:24.012Z",
        "_id": "32ded4f8-191a-418e-a4c9-0dabceba90ee",
        "_updateDate": "2019-06-17T13:46:24.012Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/32ded4f8-191a-418e-a4c9-0dabceba90ee"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content"
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/32ded4f8-191a-418e-a4c9-0dabceba90ee/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/32ded4f8-191a-418e-a4c9-0dabceba90ee/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/32ded4f8-191a-418e-a4c9-0dabceba90ee/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content"
          }
        },
        "contentTypeAlias": "home",
        "name": "Home",
        "sortOrder": 4
      }
    ]
  }
}

Get children

Get children of a single published content.

URL: /content/{id}/children

Method: GET

Query Strings

?hyperlinks={boolean=true}
?contentType={string}
?page={integer=1}
?pageSize={integer=10}

Success Response

Code: 200

Content Example:

{
  "_totalItems": 3,
  "_totalPages": 1,
  "_page": 1,
  "_pageSize": 10,
  "_links": {
    "self": {
      "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324/children?page=1"
    },
    "page": {
      "href": "https://cdn.umbraco.io/content/{id}/children{?page,pageSize}",
      "templated": true
    },
    "root": {
      "href": "https://cdn.umbraco.io/content"
    },
    "content": [
      {
        "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c"
      },
      {
        "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2"
      },
      {
        "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752"
      }
    ]
  },
  "_embedded": {
    "content": [
      {
        "_creatorName": "Rasmus",
        "_url": "/products/tattoo/",
        "_urls": {
          "en-us": "/products/tattoo/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": false,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.14Z",
        "_id": "df1eb830-411b-4d41-a343-3917b76d533c",
        "_updateDate": "2019-06-26T22:11:05.727Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c"
          },
          "photos": {
            "href": "https://cdn.umbraco.io/media/20e3a8ff-ad1b-4fe9-b48c-b8461c46d2d0",
            "title": "Tattoo"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content"
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "product",
        "name": "Tattoo",
        "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "sortOrder": 0,
        "productName": "Tattoo",
        "price": 499.0,
        "description": "Cras ultricies ligula sed magna dictum porta.",
        "sku": "UMB-TATTOO",
        "photos": {
          "_creatorName": "Rasmus",
          "_url": "https://media.umbraco.io/my-headless-site/media/20e3a8ffad1b4fe9b48cb8461c46d2d0/00000006000000000000000000000000/7371127652_e01b6ab56f_b.jpg",
          "_writerName": "Rasmus",
          "_hasChildren": false,
          "_level": 2,
          "_createDate": "2019-06-17T13:46:42.503Z",
          "_id": "20e3a8ff-ad1b-4fe9-b48c-b8461c46d2d0",
          "_updateDate": "2019-06-17T13:46:42.503Z",
          "_links": null,
          "mediaTypeAlias": "Image",
          "name": "Tattoo",
          "parentId": "6d5bf746-cb82-45c5-bd15-dd3798209b87",
          "sortOrder": 0,
          "umbracoFile": {
            "src": "/media/20e3a8ffad1b4fe9b48cb8461c46d2d0/00000006000000000000000000000000/7371127652_e01b6ab56f_b.jpg",
            "focalPoint": null,
            "crops": null
          },
          "umbracoWidth": 683,
          "umbracoHeight": 1024,
          "umbracoBytes": 258796,
          "umbracoExtension": "jpg"
        },
        "features": []
      },
      {
        "_creatorName": "Rasmus",
        "_url": "/products/unicorn/",
        "_urls": {
          "en-us": "/products/unicorn/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": false,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.187Z",
        "_id": "4e96411a-b8e1-435f-9322-2faee30ef5f2",
        "_updateDate": "2019-06-26T22:11:05.803Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2"
          },
          "photos": {
            "href": "https://cdn.umbraco.io/media/1bc5280b-8658-4027-89d9-58e2576e469b",
            "title": "Unicorn"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content"
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "product",
        "name": "Unicorn",
        "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "sortOrder": 1,
        "productName": "Unicorn",
        "price": 249.0,
        "description": "Quisque velit nisi, pretium ut lacinia in, elementum id enim. Vivamus magna justo, lacinia eget consectetur sed, convallis at tellus. Cras ultricies ligula sed magna dictum porta.",
        "sku": "UMB-UNICORN",
        "photos": {
          "_creatorName": "Rasmus",
          "_url": "https://media.umbraco.io/my-headless-site/media/1bc5280b8658402789d958e2576e469b/00000006000000000000000000000000/14272036539_469ca21d5c_h.jpg",
          "_writerName": "Rasmus",
          "_hasChildren": false,
          "_level": 2,
          "_createDate": "2019-06-17T13:46:42.64Z",
          "_id": "1bc5280b-8658-4027-89d9-58e2576e469b",
          "_updateDate": "2019-06-17T13:46:42.64Z",
          "_links": null,
          "mediaTypeAlias": "Image",
          "name": "Unicorn",
          "parentId": "6d5bf746-cb82-45c5-bd15-dd3798209b87",
          "sortOrder": 0,
          "umbracoFile": {
            "src": "/media/1bc5280b8658402789d958e2576e469b/00000006000000000000000000000000/14272036539_469ca21d5c_h.jpg",
            "focalPoint": null,
            "crops": null
          },
          "umbracoWidth": 1067,
          "umbracoHeight": 1600,
          "umbracoBytes": 367954,
          "umbracoExtension": "jpg"
        },
        "features": []
      },
      {
        "_creatorName": "Rasmus",
        "_url": "/products/ping-pong-ball/",
        "_urls": {
          "en-us": "/products/ping-pong-ball/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": false,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.247Z",
        "_id": "d390a562-107d-4f02-8df7-57aa86bad752",
        "_updateDate": "2019-06-26T22:11:05.847Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752"
          },
          "photos": {
            "href": "https://cdn.umbraco.io/media/c09ec77f-08e3-466a-ac58-c979befd3cd6",
            "title": "Ping Pong Ball"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content"
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "product",
        "name": "Ping Pong Ball",
        "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "sortOrder": 2,
        "productName": "Ping Pong Ball",
        "price": 2.0,
        "description": "Vivamus suscipit tortor eget felis porttitor volutpat. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Cras ultricies ligula sed magna dictum porta.",
        "sku": "UMB-PINGPONG",
        "photos": {
          "_creatorName": "Rasmus",
          "_url": "https://media.umbraco.io/my-headless-site/media/c09ec77f08e3466aac58c979befd3cd6/00000006000000000000000000000000/5852022211_9028df67c0_b.jpg",
          "_writerName": "Rasmus",
          "_hasChildren": false,
          "_level": 2,
          "_createDate": "2019-06-17T13:46:42.767Z",
          "_id": "c09ec77f-08e3-466a-ac58-c979befd3cd6",
          "_updateDate": "2019-06-17T13:46:42.767Z",
          "_links": null,
          "mediaTypeAlias": "Image",
          "name": "Ping Pong Ball",
          "parentId": "6d5bf746-cb82-45c5-bd15-dd3798209b87",
          "sortOrder": 0,
          "umbracoFile": {
            "src": "/media/c09ec77f08e3466aac58c979befd3cd6/00000006000000000000000000000000/5852022211_9028df67c0_b.jpg",
            "focalPoint": null,
            "crops": null
          },
          "umbracoWidth": 1024,
          "umbracoHeight": 683,
          "umbracoBytes": 205417,
          "umbracoExtension": "jpg"
        },
        "features": []
      }
    ]
  }
}

Get descendants

Get descendants of a single published content.

URL: /content/{id}/descendants

Method: GET

Query Strings

?hyperlinks={boolean=true}
?contentType={string}
?page={integer=1}
?pageSize={integer=10}

Success Response

Code: 200

Content Example:

{
  "_totalItems": 3,
  "_totalPages": 1,
  "_page": 1,
  "_pageSize": 10,
  "_links": {
    "self": {
      "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324/descendants?page=1"
    },
    "page": {
      "href": "https://cdn.umbraco.io/content/{id}/descendants{?page,pageSize}",
      "templated": true
    },
    "root": {
      "href": "https://cdn.umbraco.io/content"
    },
    "content": [
      {
        "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c"
      },
      {
        "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2"
      },
      {
        "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752"
      }
    ]
  },
  "_embedded": {
    "content": [
      {
        "_creatorName": "Rasmus",
        "_url": "/products/tattoo/",
        "_urls": {
          "en-us": "/products/tattoo/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": false,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.14Z",
        "_id": "df1eb830-411b-4d41-a343-3917b76d533c",
        "_updateDate": "2019-06-26T22:11:05.727Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c"
          },
          "photos": {
            "href": "https://cdn.umbraco.io/media/20e3a8ff-ad1b-4fe9-b48c-b8461c46d2d0",
            "title": "Tattoo"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content"
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/df1eb830-411b-4d41-a343-3917b76d533c/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "product",
        "name": "Tattoo",
        "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "sortOrder": 0,
        "productName": "Tattoo",
        "price": 499.0,
        "description": "Cras ultricies ligula sed magna dictum porta.",
        "sku": "UMB-TATTOO",
        "photos": {
          "_creatorName": "Rasmus",
          "_url": "https://media.umbraco.io/my-headless-site/media/20e3a8ffad1b4fe9b48cb8461c46d2d0/00000006000000000000000000000000/7371127652_e01b6ab56f_b.jpg",
          "_writerName": "Rasmus",
          "_hasChildren": false,
          "_level": 2,
          "_createDate": "2019-06-17T13:46:42.503Z",
          "_id": "20e3a8ff-ad1b-4fe9-b48c-b8461c46d2d0",
          "_updateDate": "2019-06-17T13:46:42.503Z",
          "_links": null,
          "mediaTypeAlias": "Image",
          "name": "Tattoo",
          "parentId": "6d5bf746-cb82-45c5-bd15-dd3798209b87",
          "sortOrder": 0,
          "umbracoFile": {
            "src": "/media/20e3a8ffad1b4fe9b48cb8461c46d2d0/00000006000000000000000000000000/7371127652_e01b6ab56f_b.jpg",
            "focalPoint": null,
            "crops": null
          },
          "umbracoWidth": 683,
          "umbracoHeight": 1024,
          "umbracoBytes": 258796,
          "umbracoExtension": "jpg"
        },
        "features": []
      },
      {
        "_creatorName": "Rasmus",
        "_url": "/products/unicorn/",
        "_urls": {
          "en-us": "/products/unicorn/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": false,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.187Z",
        "_id": "4e96411a-b8e1-435f-9322-2faee30ef5f2",
        "_updateDate": "2019-06-26T22:11:05.803Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2"
          },
          "photos": {
            "href": "https://cdn.umbraco.io/media/1bc5280b-8658-4027-89d9-58e2576e469b",
            "title": "Unicorn"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content"
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/4e96411a-b8e1-435f-9322-2faee30ef5f2/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "product",
        "name": "Unicorn",
        "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "sortOrder": 1,
        "productName": "Unicorn",
        "price": 249.0,
        "description": "Quisque velit nisi, pretium ut lacinia in, elementum id enim. Vivamus magna justo, lacinia eget consectetur sed, convallis at tellus. Cras ultricies ligula sed magna dictum porta.",
        "sku": "UMB-UNICORN",
        "photos": {
          "_creatorName": "Rasmus",
          "_url": "https://media.umbraco.io/my-headless-site/media/1bc5280b8658402789d958e2576e469b/00000006000000000000000000000000/14272036539_469ca21d5c_h.jpg",
          "_writerName": "Rasmus",
          "_hasChildren": false,
          "_level": 2,
          "_createDate": "2019-06-17T13:46:42.64Z",
          "_id": "1bc5280b-8658-4027-89d9-58e2576e469b",
          "_updateDate": "2019-06-17T13:46:42.64Z",
          "_links": null,
          "mediaTypeAlias": "Image",
          "name": "Unicorn",
          "parentId": "6d5bf746-cb82-45c5-bd15-dd3798209b87",
          "sortOrder": 0,
          "umbracoFile": {
            "src": "/media/1bc5280b8658402789d958e2576e469b/00000006000000000000000000000000/14272036539_469ca21d5c_h.jpg",
            "focalPoint": null,
            "crops": null
          },
          "umbracoWidth": 1067,
          "umbracoHeight": 1600,
          "umbracoBytes": 367954,
          "umbracoExtension": "jpg"
        },
        "features": []
      },
      {
        "_creatorName": "Rasmus",
        "_url": "/products/ping-pong-ball/",
        "_urls": {
          "en-us": "/products/ping-pong-ball/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": false,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.247Z",
        "_id": "d390a562-107d-4f02-8df7-57aa86bad752",
        "_updateDate": "2019-06-26T22:11:05.847Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752"
          },
          "photos": {
            "href": "https://cdn.umbraco.io/media/c09ec77f-08e3-466a-ac58-c979befd3cd6",
            "title": "Ping Pong Ball"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content"
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/d390a562-107d-4f02-8df7-57aa86bad752/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "product",
        "name": "Ping Pong Ball",
        "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "sortOrder": 2,
        "productName": "Ping Pong Ball",
        "price": 2.0,
        "description": "Vivamus suscipit tortor eget felis porttitor volutpat. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Cras ultricies ligula sed magna dictum porta.",
        "sku": "UMB-PINGPONG",
        "photos": {
          "_creatorName": "Rasmus",
          "_url": "https://media.umbraco.io/my-headless-site/media/c09ec77f08e3466aac58c979befd3cd6/00000006000000000000000000000000/5852022211_9028df67c0_b.jpg",
          "_writerName": "Rasmus",
          "_hasChildren": false,
          "_level": 2,
          "_createDate": "2019-06-17T13:46:42.767Z",
          "_id": "c09ec77f-08e3-466a-ac58-c979befd3cd6",
          "_updateDate": "2019-06-17T13:46:42.767Z",
          "_links": null,
          "mediaTypeAlias": "Image",
          "name": "Ping Pong Ball",
          "parentId": "6d5bf746-cb82-45c5-bd15-dd3798209b87",
          "sortOrder": 0,
          "umbracoFile": {
            "src": "/media/c09ec77f08e3466aac58c979befd3cd6/00000006000000000000000000000000/5852022211_9028df67c0_b.jpg",
            "focalPoint": null,
            "crops": null
          },
          "umbracoWidth": 1024,
          "umbracoHeight": 683,
          "umbracoBytes": 205417,
          "umbracoExtension": "jpg"
        },
        "features": []
      }
    ]
  }
}

Content Filter

Get content filtered by property values and optionally content type.

This endpoint can be used for advanced filtering of content based on the value of specific properties. You can choose to filter on one or more properties by their alias and a value. The matching criteria include whether the property contains or is like the passed-in value.

Say you have a property with an alias called "title" and you want all content, which contains the word "world". The payload you post to the /content/filter endpoint would be as shown below.

{
  "contentTypeAlias": "",
  "properties": [{
    "alias": "title",
    "value": "world",
    "match": "CONTAINS"
  }]
}

Setting the above properties to "hello world" results in content with a "title" property containing either "hello" or "world" as values.

If you want the value of a property to match on both "page" and "pages" then you could use like with a payload as shown below.

{
  "contentTypeAlias": "",
  "properties": [{
    "alias": "title",
    "value": "page",
    "match": "LIKE"
  }]
}

Filtering is performed on individual content items, indicating that content matching is not conducted on related content or media.

URL: /content/filter

Method: POST

Query Strings

?hyperlinks={boolean=true}
?page={integer=1}
?pageSize={integer=10}

Headers

This endpoint is available from API-Version: 2.1. Specify the header as shown below when using the REST API.

Api-Version: 2.1
Umb-Project-Alias: {project-alias}

Request

In this example, we perform a filter with criteria for a "productName"-property containing the value "Jacket" and a "description"-property containing the value "Vivamus". Additionally, the Document Type should have the alias "product."

At least one object with alias, value and match in the properties array is required. The contentTypeAlias is optional and the match property can be either CONTAINS or LIKE.

{
  "contentTypeAlias": "product",
  "properties": [{
    "alias": "productName",
    "value": "Jacket",
    "match": "CONTAINS"
  },
  {
    "alias": "description",
    "value": "Vivamus",
    "match": "CONTAINS"
  }]
}

Success Response

Code: 200

Content Example:

{
  "_totalItems": 1,
  "_totalPages": 1,
  "_page": 1,
  "_pageSize": 10,
  "_links": {
    "self": {
      "href": "https://cdn.umbraco.io/content/filter?page=1&pageSize=10"
    },
    "page": {
      "href": "https://cdn.umbraco.io/content/filter{?page,pageSize}",
      "templated": true
    },
    "root": {
      "href": "https://cdn.umbraco.io/content{?contentType}"
    },
    "content": {
      "href": "https://cdn.umbraco.io/content/262beb70-53a6-49b8-9e98-cfde2e85a78e"
    }
  },
  "_embedded": {
    "content": [
      {
        "_creatorName": "Rasmus",
        "_url": "/products/biker-jacket/",
        "_urls": {
          "en-us": "/products/biker-jacket/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": false,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.497Z",
        "_id": "262beb70-53a6-49b8-9e98-cfde2e85a78e",
        "_updateDate": "2019-09-16T11:25:44.433Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/262beb70-53a6-49b8-9e98-cfde2e85a78e"
          },
          "photos": {
            "href": "https://cdn.umbraco.io/media/55514845-b8bd-487c-b370-9724852fd6bb",
            "title": "Biker Jacket"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content"
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/262beb70-53a6-49b8-9e98-cfde2e85a78e/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/262beb70-53a6-49b8-9e98-cfde2e85a78e/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/262beb70-53a6-49b8-9e98-cfde2e85a78e/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "product",
        "name": "Biker Jacket",
        "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "sortOrder": 7,
        "productName": "Biker Jacket",
        "price": 199.0,
        "description": "Donec rutrum congue leo eget malesuada. Vivamus suscipit tortor eget felis porttitor volutpat.",
        "sku": "UMB-BIKER-JACKET",
        "photos": {
          "_creatorName": "Rasmus",
          "_url": "https://media.umbraco.io/my-headless-site/media/55514845b8bd487cb3709724852fd6bb/00000006000000000000000000000000/4730684907_8a7f8759cb_b.jpg",
          "_writerName": "Rasmus",
          "_hasChildren": false,
          "_level": 2,
          "_createDate": "2019-06-17T13:46:42.377Z",
          "_id": "55514845-b8bd-487c-b370-9724852fd6bb",
          "_updateDate": "2019-06-17T13:46:42.377Z",
          "_links": null,
          "mediaTypeAlias": "Image",
          "name": "Biker Jacket",
          "parentId": "6d5bf746-cb82-45c5-bd15-dd3798209b87",
          "sortOrder": 0,
          "umbracoFile": {
            "src": "/media/55514845b8bd487cb3709724852fd6bb/00000006000000000000000000000000/4730684907_8a7f8759cb_b.jpg",
            "focalPoint": null,
            "crops": null
          },
          "umbracoWidth": 680,
          "umbracoHeight": 1024,
          "umbracoBytes": 224349,
          "umbracoExtension": "jpg"
        },
        "features": [
          {
            "contentTypeAlias": "feature",
            "featureName": "Free shipping",
            "featureDetails": "Isn't that awesome - you only pay for the product"
          },
          {
            "contentTypeAlias": "feature",
            "featureName": "1 Day return policy",
            "featureDetails": "You'll need to make up your mind fast"
          },
          {
            "contentTypeAlias": "feature",
            "featureName": "100 Years warranty",
            "featureDetails": "But if you're satisfied it'll last a lifetime"
          }
        ]
      }
    ]
  }
}

Search

Search for published content by keyword.

URL: /content/search?term={string}

Method: GET

Query Strings

?hyperlinks={boolean=true}
?page={integer=1}
?pageSize={integer=10}

Success Response

Code: 200

Content Example:

{
  "_totalItems": 1,
  "_totalPages": 1,
  "_page": 1,
  "_pageSize": 10,
  "_links": {
    "self": {
      "href": "https://cdn.umbraco.io/content/search?term=jacket&page=1&pageSize=10"
    },
    "page": {
      "href": "https://cdn.umbraco.io/content/search{?term,page,pageSize}",
      "templated": true
    },
    "root": {
      "href": "https://cdn.umbraco.io/content"
    },
    "content": {
      "href": "https://cdn.umbraco.io/content/262beb70-53a6-49b8-9e98-cfde2e85a78e"
    }
  },
  "_embedded": {
    "content": [
      {
        "_creatorName": "Rasmus",
        "_url": "/products/biker-jacket/",
        "_urls": {
          "en-us": "/products/biker-jacket/"
        },
        "_writerName": "Rasmus",
        "_hasChildren": false,
        "_level": 2,
        "_createDate": "2019-06-17T13:46:24.497Z",
        "_id": "262beb70-53a6-49b8-9e98-cfde2e85a78e",
        "_updateDate": "2019-09-16T11:25:44.433Z",
        "_links": {
          "self": {
            "href": "https://cdn.umbraco.io/content/262beb70-53a6-49b8-9e98-cfde2e85a78e"
          },
          "photos": {
            "href": "https://cdn.umbraco.io/media/55514845-b8bd-487c-b370-9724852fd6bb",
            "title": "Biker Jacket"
          },
          "root": {
            "href": "https://cdn.umbraco.io/content"
          },
          "children": {
            "href": "https://cdn.umbraco.io/content/262beb70-53a6-49b8-9e98-cfde2e85a78e/children"
          },
          "ancestors": {
            "href": "https://cdn.umbraco.io/content/262beb70-53a6-49b8-9e98-cfde2e85a78e/ancestors"
          },
          "descendants": {
            "href": "https://cdn.umbraco.io/content/262beb70-53a6-49b8-9e98-cfde2e85a78e/descendants"
          },
          "parent": {
            "href": "https://cdn.umbraco.io/content/ec4aafcc-0c25-4f25-a8fe-705bfae1d324"
          }
        },
        "contentTypeAlias": "product",
        "name": "Biker Jacket",
        "parentId": "ec4aafcc-0c25-4f25-a8fe-705bfae1d324",
        "sortOrder": 7,
        "productName": "Biker Jacket",
        "price": 199.0,
        "description": "Donec rutrum congue leo eget malesuada. Vivamus suscipit tortor eget felis porttitor volutpat.",
        "sku": "UMB-BIKER-JACKET",
        "photos": {
          "_creatorName": "Rasmus",
          "_url": "https://media.umbraco.io/my-headless-site/media/55514845b8bd487cb3709724852fd6bb/00000006000000000000000000000000/4730684907_8a7f8759cb_b.jpg",
          "_writerName": "Rasmus",
          "_hasChildren": false,
          "_level": 2,
          "_createDate": "2019-06-17T13:46:42.377Z",
          "_id": "55514845-b8bd-487c-b370-9724852fd6bb",
          "_updateDate": "2019-06-17T13:46:42.377Z",
          "_links": null,
          "mediaTypeAlias": "Image",
          "name": "Biker Jacket",
          "parentId": "6d5bf746-cb82-45c5-bd15-dd3798209b87",
          "sortOrder": 0,
          "umbracoFile": {
            "src": "/media/55514845b8bd487cb3709724852fd6bb/00000006000000000000000000000000/4730684907_8a7f8759cb_b.jpg",
            "focalPoint": null,
            "crops": null
          },
          "umbracoWidth": 680,
          "umbracoHeight": 1024,
          "umbracoBytes": 224349,
          "umbracoExtension": "jpg"
        },
        "features": [
          {
            "contentTypeAlias": "feature",
            "featureName": "Free shipping",
            "featureDetails": "Isn't that awesome - you only pay for the product"
          },
          {
            "contentTypeAlias": "feature",
            "featureName": "1 Day return policy",
            "featureDetails": "You'll need to make up your mind fast"
          },
          {
            "contentTypeAlias": "feature",
            "featureName": "100 Years warranty",
            "featureDetails": "But if you're satisfied it'll last a lifetime"
          }
        ]
      }
    ]
  }
}

Schema Generation

Documentation for Umbraco Heartcore GraphQL schema generation

The GraphQL schema is generated from the Content Types upon creation, and it is generated when a Content Type or a Data Type is changed.

The type name is the Content Type's alias in Pascal Case, e.g. if a Content Type has an alias of product it's GraphQL type name would be Product.

Types

The types generated depends on how the Content Types are configured.

interface NavigationBase {
  seoMetaDescription: String
  umbracoNavihide: Boolean
}

type Feature implements Element {
  contentTypeAlias: String!
  featureName: String
  featureDescription: String
}

type Product implements Content & NavigationBase {
  ancestors(...): ContentConnection!
  category: [String]
  children(...): ContentConnection!
  contentTypeAlias: String!
  createDate: DateTime!
  descendants(...): ContentConnection!
  description: String
  features: [Element]
  id: ID!
  level: Int!
  name: String
  parent: Content
  photos: Media
  price: Decimal
  productName: String
  sku: String
  sortOrder: Int!
  seoMetaDescription: String
  umbracoNavihide: Boolean
  updateDate: DateTime
  url: String
}

A Connection and an Edge type will also be generated, these are used when quering Content of a specific type.

type ProductConnection {
  edges: [ProductEdge]
  pageInfo: PageInfo
}

type ProductEdge {
  cursor: String!
  node: Product
}

Fields

type Product implements Content & NavigationBase {
  ...
  productName(culture: String): String
  ...
}

Root Query

The Query type is the entry to the GraphQL API. By default it contains two fields, one to get a single Content item by ID or url and one to get all Content.

type Query {
  """
  Get Content by its unique identifier or url. Either id or url must be specified but not both.
  """
  content(
    """
    The unique identifier of the content.
    """
    id: ID,
    """
    The url of the content.
    """
    url: String,
    """
    The culture to fetch the content in. If empty the default culture will be used.
    """
    culture: String
    """
    Specifies if draft content should be returned. Requires the request to be authenticated.
    """
    preview: Boolean
  ): Content
  """
  Get all Content.
  """
  allContent(
    """
    Specifies the number of edges to return starting from `after` or the first entry if `after` is not specified.
    """
    first: Int,
    """
    Only look at connected edges with cursors greater than the value of `after`.
    """
    after: String,
    """
    Specifies the number of edges to return counting reversely from `before`, or the last entry if `before` is not specified.
    """
    last: Int,
    """
    Only look at connected edges with cursors smaller than the value of `before`.
    """
    before: String,
    """
    The culture to fetch the value in. If empty the default culture will be used.
    """
    culture: String,
    """
    Specifies if draft content should be returned. Requires the request to be authenticated.
    """
    preview: Boolean
    """
    Filter the returned data.
    """
    where: ContentFilterInput,
    """
    Sort the returned data.
    """
    orderBy: [ContentOrderByInput]
  ): ContentConnection!
}

For each Document Type that is not used as a Composition or marked as an Element Type, two fields will be generated on the Query type. One for getting a single Content item by either it's ID or url and a field for getting all Content of that specific type.

type Query {
  ...
  allProduct(first: Int, after: String, last: Int, before: String, culture: String, preview: Boolean, where: ProductFilterInput, orderBy: [ProductOrderByInput]): ProductConnection!
  product(culture: String, id: ID, url: String, preview: Boolean): Product
  ...
}

Reserved Type Names and Property Aliases

GraphQL requires that type names are unique. If a Content Type will collide with one of the reserved names the type will be excluded from generation.

The same applies to Properties. If a Property alias is a reserved one it will also be excluded from generation.

Reserved Type Names

List of reserved type names, these cannot be used as an alias for Content Types.

The GraphQL type name is the Content Type alias converted to Pascal Case.

BigInt
BlockGrid
BlockGridArea
BlockGridItem
BlockListItem
Byte
Content
Date
DateTime
DateTimeOffset
Decimal
DecimalRange
Element
Guid
HTML
ImageCropAnchor
ImageCropFormat
ImageCropMode
ImageCropper
ImageCropperCrop
ImageCropperCropCoordinates
ImageCropperFocalPoint
ImageCropRatioMode
JSON
Link
LinkType
Long
Media
MediaConnection
MediaEdge
Milliseconds
OurUmbracoGMaps
OurUmbracoGMapsAddress
OurUmbracoGMapsCoordinate
OurUmbracoGMapsMapConfig
OurUmbracoGMapsMapType
PageInfo
PickedColor
Query
SByte
Seconds
Short
UInt
ULong
Uri
UShort

Reserved Element Type Property Names

List of reserved Element Type Property names, these cannot be used as a Property alias on an Element Type.

contentTypeAlias

Reserved Content Type Property Names

List of reserved Content Type Property names, these cannot be used as a Property alias on a Content Type.

ancestors
children
contentTypeAlias
createDate
descendants
id
level
name
parent
content
parentId
sortOrder
updateDate
url

Reserved Media Type Property Names

List of reserved Media Type Property names, these cannot be used as a Property alias on a Media Type.

ancestors
children
createDate
descendants
id
level
mediaTypeAlias
name
parent
sortOrder
updateDate
url

Built-in Custom Types

The Umbraco Heartcore GraphQL schema contains some default types, below you can find a list of these types.

Block Grid

type BlockGrid {
    """
    Items in the grid.
    """
    items: [BlockGridItem]!

    """
    Number of columns in the grid.
    """
    gridColumns: Int!
}

Query

{
  contentPage {
    blocks {
      gridColumns
    }
  }
}

Output

{
  "data": {
    "contentPage": {
      "blocks": {
        "gridColumns": 12
      }
    }
  }
}

Block Grid Area

type BlockGridArea {
    """
    Name of the area.
    """
    alias: String!

    """
    Items in the area.
    """
    items: [BlockGridItem]!

    """
    Number of rows spanned by the area.
    """
    rowSpan: Int!

    """
    Number of columns spanned by the area.
    """
    columnSpan: Int!
}

Query

{
  contentPage {
    blocks {
      items {
        areas: {
          alias
          columnSpan
          items {
            title
          }
        }
      }
    }
  }
}

Output

{
  "data": {
    "contentPage": {
      "blocks": {
        "items": [{
          "areas": [{
            "alias": "mainArea",
            "columnSpan": 12,
            "items": [{
              "title": "Essential Heartcore Tips: Volume 4"
            }]
          }]
        }]
      }
    }
  }
}

Block Grid Item

type BlockGridItem {
    """
    The content.
    """
    content: Element!

    """
    The settings.
    """
    settings: Element

    """
    Number of rows spanned by the item.
    """
    rowSpan: Int!

    """
    Number of columns spanned by the item.
    """
    columSpan: Int!

    """
    Number of columns in child areas.
    """
    areaGridColumns: Int!

    """
    Number of columns in child areas.
    """
    areas: [BlockGridArea]
}

Query

{
  contentPage {
    blocks {
      items: {
        content: {
          title
        }
        settings: {
          openLinkInNewTab
        }
        rowSpan
        columnSpan
      }
    }
  }
}

Output

{
  "data": {
    "contentPage": {
      "blocks": {
        "items": [{
          "content": {
            "title": "Essential Heartcore Tips: Volume 7"
          },
          "settings": {
            "openLinkInNewTab": false
          },
          "rowSpan": 1,
          "columnSpan": 4
        }]
      }
    }
  }
}

Block List Item

type BlockListItem {
    """
    The content.
    """
    content: Element!

    """
    The settings.
    """
    settings: Element
}

Query

{
  textPage {
    elements {
      content {
        title
      }
      settings {
        showLargeImage
      }
    }
  }
}

Output:

{
  "data": {
    "textPage": {
      "elements": [{
        "content": {
          "title": "Why use Umbraco Heartcore?"
        },
        "settings" {
          "showLargeImage": true
        }
      }]
    }
  }
}

Decimal Range

# Represents a range of decimals.
type DecimalRange {
  """
  Maximum value of the range.
  """
  maximum: Decimal!
  """
  Minimum value of the range.
  """
  minimum: Decimal!
}

Query:

{
  product {
    durability {
      minimum
      maximum
    }
  }
}

Output:

{
  "data": {
    "product": {
      "durability": {
        "minimum": 7,
        "maximum": 10
      }
    }
  }
}

HTML

"""
A string containing HTML code.
"""
scalar HTML

Query:

{
  product {
    description
  }
}

Output:

{
  "data": {
    "product": {
      "description": "<p>A nice leather jacket.</p>"
    }
  }
}

Image Cropper

type ImageCropper {
  """
  The predefined crops.
  """
  crops: [ImageCropperCrop]!
  """
  The image url with crop parameters.
  """
  cropUrl(
    """
    The crop alias.
    """
    alias: String
    """
    Change background color of the image.
    """
    backgroundColor: String
    """
    The width of the output image.
    """
    width: Int
    """
    The height of the output image.
    """
    height: Int
    """
    Quality percentage of the output image.
    """
    quality: Int
    """
    The image crop mode.
    """
    cropMode: ImageCropMode
    """
    The image crop anchor.
    """
    cropAnchor: ImageCropAnchor
    """
    Use a dimension as a ratio.
    """
    ratioMode: ImageCropRatioMode
    """
    The format of the output image.
    """
    format: ImageCropFormat
    """
    Use focal point to generate an output image using the focal point instead of the predefined crop if there is one.
    """
    preferFocalPoint: Boolean = false
    """
    If the image should be upscaled to requested dimensions.
    """
    upscale: Boolean = false
  ): String
  """
  The focal point position.
  """
  focalPoint: ImageCropperFocalPoint!
  """
  The focal point url template.
   """
  focalPointUrlTemplate: String!
  """
  The image url.
  """
  url: String!
}

Query:

{
  product {
    photo {
      cropUrl(width: 1980, height: 430)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=center&mode=crop&width=1980&height=430&upscale=false"
      }
    }
  }
}

Image Crop Anchor

enum ImageCropAnchor {
  """
  Anchors the position of the image to the bottom of it's bounding container.
  """
  BOTTOM
  """
  Anchors the position of the image to the bottom left side of it's bounding container.
  """
  BOTTOM_LEFT
  """
  Anchors the position of the image to the bottom right side of it's bounding container.
  """
  BOTTOM_RIGHT
  """
  Anchors the position of the image to the center of it's bounding container.
  """
  CENTER
  """
  Anchors the position of the image to the left of it's bounding container.
  """
  LEFT
  """
  Anchors the position of the image to the right of it's bounding container.
  """
  RIGHT
  """
  Anchors the position of the image to the top of it's bounding container.
  """
  TOP
  """
  Anchors the position of the image to the top left side of it's bounding container.
  """
  TOP_LEFT
  """
  Anchors the position of the image to the top right side of it's bounding container.
  """
  TOP_RIGHT
}

Query:

{
  product {
    photo {
      cropUrl(width:1980, height: 430, cropAnchor: TOP_LEFT)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=topleft&mode=crop&width=1980&height=430&upscale=false"
      }
    }
  }
}

Image Crop Format

enum ImageCropFormat {
  PNG
  JPG
  GIF
  WEBP
}

Query:

{
  product {
    photo {
      cropUrl(width:1980, height: 430, format: WEBP)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=center&mode=crop&width=1980&height=430&upscale=false&format=webp"
      }
    }
  }
}

Image Crop Mode

enum ImageCropMode {
  """
  When upscaling an image the image pixels themselves are not resized, rather the image is padded to fit the given dimensions.
  """
  BOX_PAD
  """
  Resizes the image to the given dimensions. If the set dimensions do not match the aspect ratio of the original image then the output is cropped to match the new aspect ratio.
  """
  CROP
  """
  Resizes the image to the given dimensions. If the set dimensions do not match the aspect ratio of the original image then the output is resized to the maximum possible value in each direction while maintaining the original aspect ratio.
  """
  MAX
  """
  Resizes the image until the shortest side reaches the set given dimension. This will maintain the aspect ratio of the original image. Upscaling is disabled in this mode and the original image will be returned if attempted.
  """
  MIN
  """
  Passing a single dimension will automatically preserve the aspect ratio of the original image. If the requested aspect ratio is different then the image will be padded to fit.
  """
  PAD
  """
  Resizes the image to the given dimensions. If the set dimensions do not match the aspect ratio of the original image then the output is stretched to match the new aspect ratio.
  """
  STRETCH
}

Query:

{
  product {
    photo {
      cropUrl(width:1980, height: 430, cropMode: PAD)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=center&mode=pad&width=1980&height=430&upscale=false"
      }
    }
  }
}

Image Crop Ratio Mode

enum ImageCropRatioMode {
  """
  Calculate the image ratio based on the height.
  """
  HEIGHT
  """
  Calculate the image ratio based on the width.
  """
  WIDTH
}

Query:

{
  product {
    photo {
      cropUrl(width:1980, height: 430, ratioMode: WIDTH)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=center&mode=crop&height=430&widthratio=4.6046511627906976744186046512&upscale=false"
      }
    }
  }
}

Image Cropper Crop

type ImageCropperCrop {
  """
  The crop alias.
  """
  alias: String!
  """
  The crop coordinates.
  """
  coordinates: ImageCropperCropCoordinates
  """
  The crop height.
  """
  height: Int!
  """
  The crop width.
  """
  width: Int!
}

Query:

{
  product {
    photo {
      crops {
        alias
        height
        width
      }
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "crops": {
          "alias": "Hero",
          "height": 600,
          "width": 1580
        }
      }
    }
  }
}

Image Cropper Crop Coordinates

type ImageCropperCropCoordinates {
  x1: Decimal!
  x2: Decimal!
  y1: Decimal!
  y2: Decimal!
}

Query:

{
  product {
    photo {
      crops {
        coordinates {
          x1
          x2
          y1
          y2
        }
      }
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "crops": {
          "coordinates": {
            "x1": 0.08901424149934925,
            "x2": 0.055992598445931165,
            "y1": 0.3183501211863771,
            "y2": 0.4660414375419126
          }
        }
      }
    }
  }
}

Image Cropper Focal Point

type ImageCropperFocalPoint {
  """
  The left position.
  """
  left: Decimal!
  """
  The top position.
  """
  top: Decimal!
}

Query:

{
  product {
    photo {
      focalPoint {
        left
        top
      }
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "focalPoint": {
          "left": 0.5,
          "top": 0.5
        }
      }
    }
  }
}

JSON

"""
The `JSON` scalar type represents JSON values as specified by [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf).
"""
scalar JSON

Query:

{
  product {
    data
  }
}

Output:

{
  "data": {
    "product": {
      "data": {
        "size": "100x100x100 mm",
        "weight": "300 g"
      }
    }
  }
}

Link

type Link {
  """
  The name of the Link.
  """
  name: String!
  """
  The link target.
  """
  target: String
  """
  The link type.
  """
  type: LintType!
  """
  The link udi if type is CONTENT or MEDIA.
  """
  udi: String
  """
  The url.
  """
  url: String!
}

Query:

{
  product {
    link {
      name
      target
      type
      udi
      url
    }
  }
}

Output:

{
  "data": {
    "product": {
      "link": {
        "name": "Umbraco",
        "target": "_blank",
        "type": "EXTERNAL",
        "udi": null,
        "url": "https://umbraco.com/"
      }
    }
  }
}

Link Type

enum LintType {
  """
  The link is a Content link.
  """
  CONTENT
  """
  The link is an external link.
  """
  EXTERNAL
  """
  The link is a media link.
  """
  MEDIA
}

Query:

{
  product {
    link {
      type
    }
  }
}

Output:

{
  "data": {
    "product": {
      "link": {
        "type": "CONTENT"
      }
    }
  }
}

Media With Crops

type MediaWithCrops {
  """
  The predefined crops.
  """
  crops: [ImageCropperCrop]!
  """
  The image url with crop parameters.
  """
  cropUrl(
    """
    The crop alias.
    """
    alias: String
    """
    Change background color of the image.
    """
    backgroundColor: String
    """
    The width of the output image.
    """
    width: Int
    """
    The height of the output image.
    """
    height: Int
    """
    Quality percentage of the output image.
    """
    quality: Int
    """
    The image crop mode.
    """
    cropMode: ImageCropMode
    """
    The image crop anchor.
    """
    cropAnchor: ImageCropAnchor
    """
    Use a dimension as a ratio.
    """
    ratioMode: ImageCropRatioMode
    """
    The format of the output image.
    """
    format: ImageCropFormat
    """
    Use focal point to generate an output image using the focal point instead of the predefined crop if there is one.
    """
    preferFocalPoint: Boolean = false
    """
    If the image should be upscaled to requested dimensions.
    """
    upscale: Boolean = false
  ): String
  """
  The focal point position.
  """
  focalPoint: ImageCropperFocalPoint!
  """
  The focal point url template.
  """
  focalPointUrlTemplate: String!
  """
  The media
  """
  media: Media!
  """
  The image url.
  """
  url: String!
}

Query:

{
  product {
    photo {
      cropUrl(width: 1980, height: 430)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=center&mode=crop&width=1980&height=430&upscale=false"
      }
    }
  }
}

Our Umbraco GMaps

type OurUmbracoGMaps {
  address: OurUmbracoGMapsAddress
  mapconfig: OurUmbracoGMapsMapConfig
}

Query:

{
  frontpage {
    location {
      address {
        coordinates {
          lat
          lng
        }
      }
      mapconfig {
        zoom
      }
    }
  }
}

Output:

{
  "data": {
    "frontpage": {
      "location": {
        "address": {
          "lat": 55.4063759,
          "lng": 10.3887197
        },
        "mapconfig": {
          "zoom": 19
        }
      }
    }
  }
}

Our Umbraco GMaps Address

type OurUmbracoGMapsAddress {
  coordinates: OurUmbracoGMapsCoordinate
}

Query:

{
  frontpage {
    location {
      address {
        coordinates {
          lat
          lng
        }
      }
    }
  }
}

Output:

{
  "data": {
    "frontpage": {
      "location": {
        "address": {
          "lat": 55.4063759,
          "lng": 10.3887197
        }
      }
    }
  }
}

Our Umbraco GMaps Config

type OurUmbracoGMapsMapConfig {
  apikey: String
  zoom: Int
  centerCoordinates: OurUmbracoGMapsCoordinate
  maptype: OurUmbracoGMapsMapType
  mapstyle: JSON
}

Query:

{
  frontpage {
    location {
      mapconfig {
        apikey
        zoom
        centerCoordinates {
          lat
          lng
        }
        maptype
      }
    }
  }
}

Output:

{
  "data": {
    "frontpage": {
      "location": {
        "mapconfig": {
          "apikey": "my-api-key",
          "zoom": 19,
          "centerCoordinates": {
            "lat": 55.4063759,
            "lng": 10.3887197
          },
          "maptype": "satellite"
        }
      }
    }
  }
}

Our Umbraco GMaps Coordinate

type OurUmbracoGMapsCoordinate {
  coordinates: String
  lat: Decimal
  lng: Decimal
  isEmpty: Boolean
}

Query:

{
  frontpage {
    location {
      address {
        coordinates {
          coordinates
          lat
          lng
          isEmpty
        }
      }
    }
  }
}

Output:

{
  "data": {
    "frontpage": {
      "location": {
        "address": {
          "coordinates": "55.4063759,10.3887197",
          "lat": 55.4063759,
          "lng": 10.3887197,
          "isEmpty": false
        }
      }
    }
  }
}

Our Umbraco GMaps Map Type

enum OurUmbracoGMapsMapType {
  roadmap
  satellite
  hybrid
  terrain
  styled_map
}

Page Info

"""
Information about pagination in a connection.
"""
type PageInfo {
  """
  When paginating forwards, the cursor to continue.
  """
  endCursor: String
  """
  When paginating forwards, are there more items?
  """
  hasNextPage: Boolean!
  """
  When paginating backwards, are there more items?
  """
  hasPreviousPage: Boolean!
  """
  When paginating backwards, the cursor to continue.
  """
  startCursor: String
}

Query:

{
  allProduct(first: 2) {
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
  }
}

Output:

{
  "data": {
    "allProduct": {
      "pageInfo": {
        "endCursor": "eyJ0cmVlUGF0aCI6WzYsMV19",
        "hasNextPage": true,
        "hasPreviousPage": false,
        "startCursor": "eyJ0cmVlUGF0aCI6WzYsMF19"
      }}
    }
  }
}

Picked Color

type PickedColor {
  """
  The color.
  """
  color: String!
  """
  The label.
  """
  label: String!
}

Query:

{
  product {
    color
  }
}

Output:

{
  "data": {
    "product": {
      "color": {
        "color": "ff0000",
        "label": "Red"
      }
    }
  }
}

Element

interface Element {
  """
  The Content Type alias.
  """
  contentTypeAlias: String!
}

Query:

{
  product {
    features {
      contentTypeAlias
    }
  }
}

Output:

{
  "data": {
    "product": {
      "features": {
        "contentTypeAlias": "feature"
      }
    }
  }
}

Content

interface Content {
    """
    The ancestors.
    """
    ancestors(
        """
        Specifies the number of edges to return starting from `after` or the first entry if `after` is not specified.
        """
        first: Int,
        """
        Only look at connected edges with cursors greater than the value of `after`.
        """
        after: String,
        """
        Specifies the number of edges to return counting reversely from `before`, or the last entry if `before` is not specified.
        """
        last: Int,
        """
        Only look at connected edges with cursors smaller than the value of `before`.
        """
        before: String
        """
        The culture to fetch the value in. If empty the contents culture will be used.
        """
        culture: String
        """
        Filter the returned data.
        """
        where: ContentFilterInput,
        """
        Sort the returned data.
        """
        orderBy: [ContentOrderByInput],
    ): ContentConnection!
    """
    The children.
    """
    children(
        """
        Specifies the number of edges to return starting from `after` or the first entry if `after` is not specified.
        """
        first: Int,
        """
        Only look at connected edges with cursors greater than the value of `after`.
        """
        after: String,
        """
        Specifies the number of edges to return counting reversely from `before`, or the last entry if `before` is not specified.
        """
        last: Int,
        """
        Only look at connected edges with cursors smaller than the value of `before`.
        """
        before: String
        """
        The culture to fetch the value in. If empty the contents culture will be used.
        """
        culture: String
        """
        Filter the returned data.
        """
        where: ContentFilterInput,
        """
        Sort the returned data.
        """
        orderBy: [ContentOrderByInput],
    ): ContentConnection!
    """
    The Content Type alias.
    """
    contentTypeAlias: String!
    """
    The create date.
    """
    createDate: DateTime!
    """
    The descendants.
    """
    descendants(
        """
        Specifies the number of edges to return starting from `after` or the first entry if `after` is not specified.
        """
        first: Int,
        """
        Only look at connected edges with cursors greater than the value of `after`.
        """
        after: String,
        """
        Specifies the number of edges to return counting reversely from `before`, or the last entry if `before` is not specified.
        """
        last: Int,
        """
        Only look at connected edges with cursors smaller than the value of `before`.
        """
        before: String
        """
        The culture to fetch the value in. If empty the contents culture will be used.
        """
        culture: String
        """
        Filter the returned data.
        """
        where: ContentFilterInput,
        """
        Sort the returned data.
        """
        orderBy: [ContentOrderByInput],
    ): ContentConnection!
    """
    The unique identifier.
    """
    id: ID!
    """
    The level.
    """
    level: Int!
    """
    The name.
    """
    name(
        """
        The culture to fetch the value in. If empty the contents culture will be used.
        """
        culture: String
    ): String
    """
    The parent Content, can be null if content is at root.
    """
    parent(
        """
        The culture to fetch the value in. If empty the contents culture will be used.
        """
        culture: String
    ): Content
    """
    The sort order.
    """
    sortOrder: Int!
    """
    The update date.
    """
    updateDate(
        """
        The culture to fetch the value in. If empty the contents culture will be used.
        """
        culture: String
    ): DateTime
    """
    The url.
    """
    url(
        """
        The culture to fetch the value in. If empty the contents culture will be used.
        """
        culture: String
    ): String
}

Content Connection

"""
A connection from an object to a list of objects of type `Content`.
"""
type ContentConnection {
  """
  A list of all of the objects returned in the connection.
  This is a convenience field provided for quickly exploring the API;
  rather than querying for \"{ edges { node } }\" when no edge data is needed, this field can be used instead.
  Note that when clients like Relay need to fetch the \"cursor\" field on the edge to enable efficient pagination,
  this shortcut cannot be used, "and the full \"{ edges { node } } \" version should be used instead.
  """
  items: [Content]!
  """
  A list of edges.
  """
  edges: [ContentEdge]!
  """
  Information to aid in pagination.
  """
  pageInfo: PageInfo!
}

Content Edge

"""
An edge in a connection from an object to another object of type `Content`
"""
type ContentEdge {
  """
  A cursor for use in pagination.
  """
  cursor: String!
  """
  The item at the end of the edge.
  """
  node: Content
}

Media

interface Media {
  """
  The ancestors.
  """
  ancestors(
      """
      Specifies the number of edges to return starting from `after` or the first entry if `after` is not specified.
      """
      first: Int,
      """
      Only look at connected edges with cursors greater than the value of `after`.
      """
      after: String,
      """
      Specifies the number of edges to return counting reversely from `before`, or the last entry if `before` is not specified.
      """
      last: Int,
      """
      Only look at connected edges with cursors smaller than the value of `before`.
      """
      before: String
  ): MediaConnection!
  """
  The children.
  """
  children(
    """
    Specifies the number of edges to return starting from `after` or the first entry if `after` is not specified.
    """
    first: Int,
    """
    Only look at connected edges with cursors greater than the value of `after`.
    """
    after: String,
    """
    Specifies the number of edges to return counting reversely from `before`, or the last entry if `before` is not specified.
    """
    last: Int,
    """
    Only look at connected edges with cursors smaller than the value of `before`.
    """
    before: String
  ): MediaConnection!
  """
  The create date.
  """
  createDate: DateTime!
  """
  The descendants.
  """
  descendants(
    """
    Specifies the number of edges to return starting from `after` or the first entry if `after` is not specified.
    """
    first: Int,
    """
    Only look at connected edges with cursors greater than the value of `after`.
    """
    after: String,
    """
    Specifies the number of edges to return counting reversely from `before`, or the last entry if `before` is not specified.
    """
    last: Int,
    """
    Only look at connected edges with cursors smaller than the value of `before`.
    """
    before: String
  ): MediaConnection!
  """
  The unique identifier.
  """
  id: ID!
  """
  The level.
  """
  level: Int!
  """
  The Media Type alias
  """
  mediaTypeAlias: String!
  """
  The name.
  """
  name: String!
  """
  The parent Content, can be null if content is at root.
  """
  parent: Media
  """
  The sort order.
  """
  sortOrder: Int!
  """
  The update date.
  """
  updateDate: DateTime
  """
  The url.
  """
  url(
    """
    Change the background color of the image.
    """
    backgroundColor: String,
    """
    The width of the output image.
    """
    width: Int,
    """
    The height of the output image.
    """
    height: Int,
    """
    Quality percentage of the output image.
    """
    quality: Int,
    """
    The image crop mode.
    """
    cropMode: ImageCropMode,
    """
    The image crop anchor.
    """
    cropAnchor: ImageCropAnchor,
    """
    Use a dimension as a ratio.
    """
    ratioMode: ImageCropRatioMode,
    """
    If the image should be upscaled to requested dimensions.
    """
    upscale: Boolean = false,
    """
    Change the format of the output image.
    """
    format: ImageCropFormat
  ): String
}

Media Connection

"""
A connection from an object to a list of objects of type `Media`.
"""
type MediaConnection {
  """
  A list of all of the objects returned in the connection.
  This is a convenience field provided for quickly exploring the API;
  rather than querying for \"{ edges { node } }\" when no edge data is needed, this field can be used instead.
  Note that when clients like Relay need to fetch the \"cursor\" field on the edge to enable efficient pagination,
  this shortcut cannot be used, "and the full \"{ edges { node } } \" version should be used instead.
  """
  items: [Media]!
  """
  A list of edges.
  """
  edges: [MediaEdge]!
  """
  Information to aid in pagination.
  """
  pageInfo: PageInfo!
}

Media Edge

"""
An edge in a connection from an object to another object of type `Media`
"""
type MediaEdge {
  """
  A cursor for use in pagination.
  """
  cursor: String!
  """
  The item at the end of the edge.
  """
  node: Media
}

Filtering

For all Document Types a FilterInput type is generated. The name is the type name postfixed by FilterInput e.g. given a type named Product the name will be ProductFilterInput.

Default Filter Fields

To filter the allContent field, ancestors, children and descendants connections the ContentFilterInput is used.

All filter inputs for Content Types will also have the default fields.

"""
A filter input for the type `Content`.
"""
input ContentFilterInput {
  """
  All of the filters must match.
  """
  AND: [ContentFilterInput]
  """
  Some of the filters must match.
  """
  OR: [ContentFilterInput]
  """
  None of the filters must match.
  """
  NOT: [ContentFilterInput]
  """
  Field must equal value.
  """
  contentTypeAlias: String
  """
  Field must match any of the values.
  """
  contentTypeAlias_any: [String]
  """
  Field must start with the value.
  """
  contentTypeAlias_starts_with: String
  """
  Field must end with the value.
  """
  contentTypeAlias_ends_with: String
  """
  Field must contain the value.
  """
  contentTypeAlias_contains: String
  """
  Field must equal value.
  """
  createDate: DateTime
  """
  Field must be greater than the value.
  """
  createDate_gt: DateTime
  """
  Field must be greater than or equal the value.
  """
  createDate_gte: DateTime
  """
  Field must be less than the value.
  """
  createDate_lt: DateTime
  """
  Field must be less than or equal the value.
  """
  createDate_lte: DateTime
  """
  Field must equal value.
  """
  id: ID
  """
  Field must match any of the values.
  """
  id_any: [ID]
  """
  Field must equal value.
  """
  level: Int
  """
  Field must be greater than the value.
  """
  level_gt: Int
  """
  Field must be greater than or equal the value.
  """
  level_gte: Int
  """
  Field must be less than the value.
  """
  level_lt: Int
  """
  Field must be less than or equal the value.
  """
  level_lte: Int
  """
  Field must match any of the values.
  """
  level_any: [Int]
  """
  Field must equal value.
  """
  name: String
  """
  Field must match any of the values.
  """
  name_any: [String]
  """
  Field must start with the value.
  """
  name_starts_with: String
  """
  Field must end with the value.
  """
  name_ends_with: String
  """
  Field must contain the value.
  """
  name_contains: String
  """
  Field must equal value.
  """
  sortOrder: Int
  """
  Field must be greater than the value.
  """
  sortOrder_gt: Int
  """
  Field must be greater than or equal the value.
  """
  sortOrder_gte: Int
  """
  Field must be less than the value.
  """
  sortOrder_lt: Int
  """
  Field must be less than or equal the value.
  """
  sortOrder_lte: Int
  """
  Field must match any of the values.
  """
  sortOrder_any: [Int]
  """
  Field must equal value.
  """
  updateDate: DateTime
  """
  Field must be greater than the value.
  """
  updateDate_gt: DateTime
  """
  Field must be greater than or equal the value.
  """
  updateDate_gte: DateTime
  """
  Field must be less than the value.
  """
  updateDate_lt: DateTime
  """
  Field must be less than or equal the value.
  """
  updateDate_lte: DateTime
}

Filtering is possible only on non-complex Property Editors like Text Area and Label. Filtering on more complex types like Content Picker and Multi-node Tree Picker has to be done client-side.

Strings

For fields returning String the following filter fields are generated.

Given the following type:

Product implements Content {
...
  sku: String
...
}

The following type will be generated, incl. the fields from the ContentFilterInput.

"""
A filter input for the type `Product`.
"""
input ProductFilterInput {
  """
  All of the filters must match.
  """
  AND: [ProductFilterInput]
  """
  Some of the filters must match.
  """
  OR: [ProductFilterInput]
  """
  None of the filters must match.
  """
  NOT: [ProductFilterInput]
...
  """
  Field must equal value.
  """
  sku: String
  """
  Field must match any of the values.
  """
  sku_any: [String]
  """
  Field must start with the value.
  """
  sku_starts_with: String
  """
  Field must end with the value.
  """
  sku_ends_with: String
  """
  Field must contain the value.
  """
  sku_contains: String
...
}

Ints

For fields returning Int or Decimal the following filters are generated.

The type is either Int or Decimal depending on the output type.

Given the following type:

Product implements Content {
...
  price: Decimal
...
}

The following type will be generated, incl. the fields from the ContentFilterInput.

"""
A filter input for the type `Product`.
"""
input ProductFilterInput {
  """
  All of the filters must match.
  """
  AND: [ProductFilterInput]
  """
  Some of the filters must match.
  """
  OR: [ProductFilterInput]
  """
  None of the filters must match.
  """
  NOT: [ProductFilterInput]
...
  """
  Field must equal value.
  """
  price: Decimal
  """
  Field must be greater than the value.
  """
  price_gt: Decimal
  """
  Field must be greater than or equal to the value.
  """
  price_gte: Decimal
  """
  Field must be less than the value.
  """
  price_lt: Decimal
  """
  Field must be less than or equal to the value.
  """
  price_lte: Decimal
  """
  Field must match any of the values.
  """
  price_any: [Decimal]
...
}

Boolean

For types returning Boolean the following filters are generated.

Given the following type:

Product implements Content {
...
  purchase: Boolean
...
}

The following type will be generated, incl. the fields from the ContentFilterInput.

"""
A filter input for the type `Product`.
"""
input ProductFilterInput {
  """
  All of the filters must match.
  """
  AND: [ProductFilterInput]
  """
  Some of the filters must match.
  """
  OR: [ProductFilterInput]
  """
  None of the filters must match.
  """
  NOT: [ProductFilterInput]
....
  # Field must equal value.
  purchase: Boolean
...
}

Content

Dates

For types returning DateTime the following filters are generated.

Given the following type:

Product implements Content {
  availableDate: DateTime
...
}

The following type will be generated, incl. the fields from the ContentFilterInput.

"""
A filter input for the type `Product`.
"""
input ProductFilterInput {
  """
  All of the filters must match.
  """
  AND: [ProductFilterInput]
  """
  Some of the filters must match.
  """
  OR: [ProductFilterInput]
  """
  None of the filters must match.
  """
  NOT: [ProductFilterInput]
...
  """
  Field must equal value.
  """
  availableDate: DateTime
  """
  Field must be greater than the value.
  """
  availableDate_gt: DateTime
  """
  Field must be greater than or equal to the value.
  """
  availableDate_gte: DateTime
  """
  Field must be less than the value.
  """
  availableDate_lt: DateTime
  """
  Field must be less than or equal to the value.
  """
  availableDate_lte: DateTime
...
}

Media

For types returning Media the MediaFilterInput is used.

"""
A filter input for the type `Media`.
"""
input MediaFilterInput {
  """
  All of the filters must match.
  """
  AND: [MediaFilterInput]
  """
  Some of the filters must match.
  """
  OR: [MediaFilterInput]
  """
  None of the filters must match.
  """
  NOT: [MediaFilterInput]
  """
  Field must equal value.
  """
  mediaTypeAlias: String
  """
  Field must match any of the values.
  """
  mediaTypeAlias_any: [String]
  """
  Field must start with the value.
  """
  mediaTypeAlias_starts_with: String
  """
  Field must end with the value.
  """
  mediaTypeAlias_ends_with: String
  """
  Field must contain the value.
  """
  mediaTypeAlias_contains: String
  """
  Field must equal value.
  """
  createDate: DateTime
  """
  Field must be greater than the value.
  """
  createDate_gt: DateTime
  """
  Field must be greater than or equal the value.
  """
  createDate_gte: DateTime
  """
  Field must be less than the value.
  """
  createDate_lt: DateTime
  """
  Field must be less than or equal the value.
  """
  createDate_lte: DateTime
  """
  Field must equal value.
  """
  id: ID
  """
  Field must match any of the values.
  """
  id_any: [ID]
  """
  Field must equal value.
  """
  level: Int
  """
  Field must be greater than the value.
  """
  level_gt: Int
  """
  Field must be greater than or equal the value.
  """
  level_gte: Int
  """
  Field must be less than the value.
  """
  level_lt: Int
  """
  Field must be less than or equal the value.
  """
  level_lte: Int
  """
  Field must match any of the values.
  """
  level_any: [Int]
  """
  Field must equal value.
  """
  name: String
  """
  Field must match any of the values.
  """
  name_any: [String]
  """
  Field must start with the value.
  """
  name_starts_with: String
  """
  Field must end with the value.
  """
  name_ends_with: String
  """
  Field must contain the value.
  """
  name_contains: String
  """
  Field must equal value.
  """
  sortOrder: Int
  """
  Field must be greater than the value.
  """
  sortOrder_gt: Int
  """
  Field must be greater than or equal the value.
  """
  sortOrder_gte: Int
  """
  Field must be less than the value.
  """
  sortOrder_lt: Int
  """
  Field must be less than or equal the value.
  """
  sortOrder_lte: Int
  """
  Field must match any of the values.
  """
  sortOrder_any: [Int]
  """
  Field must equal value.
  """
  updateDate: DateTime
  """
  Field must be greater than the value.
  """
  updateDate_gt: DateTime
  """
  Field must be greater than or equal the value.
  """
  updateDate_gte: DateTime
  """
  Field must be less than the value.
  """
  updateDate_lt: DateTime
  """
  Field must be less than or equal the value.
  """
  updateDate_lte: DateTime
}

Lists

For types returning [Decimal], [Int] or [String] the following filters are generated.

The type is [Decimal], [Int] or [String] depending on the output type

Given the following type:

Product implements Content {
...
  tags: [String]
...
}

The following type will be generated, incl. the fields from the ContentFilterInput.

# A filter input for the type `Product`.
input ProductFilterInput {
  """
  All of the filters must match.
  """
  AND: [ProductFilterInput]
  """
  Some of the filters must match.
  """
  OR: [ProductFilterInput]
  """
  None of the filters must match.
  """
  NOT: [ProductFilterInput]
...
  """
  Field must match all of the values.
  """
  tags_all: [String]
  """
  Field must match any of the values.
  """
  tags_some: [String]
...
}

Ordering

The result can be ordered by specifying a value for the orderBy argument.

An OrderBy type is generated for all Document Types. The name is the type name postfixed by OrderByInput e.g. given a type named Product the name will be ProductOrderByInput.

Fields returning DateTime, Decimal, Boolean, Int or String can be used to order by.

Default OrderBy Fields

To filter the allContent field, ancestors, children and descendants connections the ContentOrderBy is used.

All order by inputs for Content Types will also have the default fields.

``"""
An order input for the type `Content`.
"""
enum ContentOrderByInput {
  """
  Order by `contentTypeAlias` in ascending order.
  """
  contentTypeAlias_ASC
  """
  Order by `contentTypeAlias` in descending order.
  """
  contentTypeAlias_DESC
  """
  Order by `createDate` in ascending order.
  """
  createDate_ASC
  """
  Order by `createDate` in descending order.
  """
  createDate_DESC
  """
  Order by `level` in ascending order.
  """
  level_ASC
  """
  Order by `level` in descending order.
  """
  level_DESC
  """
  Order by `name` in ascending order.
  """
  name_ASC
  """
  Order by `name` in descending order.
  """
  name_DESC
  """
  Order by `path` in ascending order.
  """
  path_ASC
  """
  Order by `path` in descending order.
  """
  path_DESC
  """
  Order by `sortOrder` in ascending order.
  """
  sortOrder_ASC
  """
  Order by `sortOrder` in descending order.
  """
  sortOrder_DESC
  """
  Order by `updateDate` in ascending order.
  """
  updateDate_ASC
  """
  Order by `updateDate` in descending order.
  """
  updateDate_DESC
}`

### Custom OrderBy Fields

Given the following type:

```graphql
Product implements Content {
...
  price: Decimal
  sku: String
...
}

The following type will be generated, incl. the fields from the ContentOrderByInput.

"""
An order by input for the type `Product`.
"""
enum ProductOrderByInput {
...
  """
  Order by `price` in ascending order.
  """
  price_ASC
  """
  Order by `price` in descending order.
  """
  price_DESC
  """
  Order by `sku` in ascending order.
  """
  sku_ASC
  # Order by `sku` in descending order.
  sku_DESC
...
}

Default ordering

If you don't specify any order the data returned will be ordered by the path they appear in, in the Umbraco Backoffice tree.

Building a project from scratch

A guide to building an Umbraco Heartcore project

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.

This guide will assume that you have already set up an Umbraco Heartcore project without any content.

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.

New to Umbraco?

If you are new to Umbraco, we recommend that you take the Backoffice Tour we've created! You can find it by selecting the question mark in the top-right corner.

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:

Right-click on the Document Types folder and choose + Create....
- Or select the three ellipses on the right, when hovering the folder.
Choose the first option: Document Type.
Give the new Document Type a name like Home Page.
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.

Property Groups

Groups are a way to group certain properties together. It can help content editors getting an overview of content nodes with many properties.

Groups also serves as a way to navigate a content node in the Content section.

Select Add Group in the middle of the Document Type editor area.
Give the group a name like Content.

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

Select Add Property.
In the Property Settings dialog, we'll start by giving the Property a name: Heading.
(Optional) Give the Property a description
Select Add Editor

Select Editor

In this dialog you choose which editor to add to the Property. The editor you choose defines the type of data that can be added to the property.

Create New lets you create your own Data Types based on the editors in Umbraco. Use existing provides you with the option to select on the pre-defined Data Types.

Use the search field to find and select the pre-defined Textstring Data Type.
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:

Name

Property Settings

Intro Text

Textarea Data Type

PromoImage

Media Picker Data Type

Media Picker

This editor lets you upload or select an existing media item from the Media section and add it to your content.

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.

Right-click on the Document Types folder and choose + Create....
- Or select the three ellipses on the right, when hovering the folder.
Choose the second option: Document Type Collection....

Document Type Collections

When working with content you might want to be able to relate certain types of nodes to each other. This could be articles you would like to nest under a News section, or it could be a Blog where it should be possible to create blog posts.

The Document Type Collection allows you to create 2 Document Types in one go, and at the same time, they will be given a parent/child relationship.

Example: Parent Document Type: News Area Item Document Type: News Article

In the Content section, you will with this setup be able to create a News Area content node, and then create your News Articles under that node.

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

Name the Parent Document Type Blog Area.
Name the Child Document Type Blog Post.
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

Name

Property Settings

SubTitle

Textstring Data Type

MainContent

Richtext Editor Data Type

Blog Area

Name

Property Settings

BlogDescription

Textarea Data Type

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.

Select the Home Page Document Type in the tree.
Navigate to the Permissions tab in the top-right corner.
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.
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.
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.

Go to the Content section.
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.

Select the Home Page.
Give the content item a name: Welcome to Umbraco Heartcore.
Add some text to both the Heading and the Intro text properties.
To choose an image for the PromoImage property, select the plus-sign.
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.
Once you've chosen an image, select it from the dialog and select the green Select button at the bottom of the dialog.

Media items and images

When you add media and images to your content using the default Media Picker Data Type, the items will automatically be added to the media library you can find in the Media section of the backoffice.

Select the Media section in the top navigation bar, and you can browse all the media items that have been uploaded to the project.

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:

Right-click the root node, Welcome to Umbraco Heartcore, and choose Create...
- Or select the three ellipses next to the node when hovering.
Select to create a Blog Area.
Give it a name: Blog.
(Optional) Add some text to the BlogDescription property.
To start adding blog posts to our Blog, right-click the Blog node in the Content tree.
Choose to Create... a new item based on the Blog Post Document Type.
Give the blog post a name and add some text to the Subtitle and MainContent properties.

Rich Text Editor

The editor we chose for the MainContent property is a Rich Text Editor.

It gives us a lot of flexibility when writing text, as there are multiple formatting options.

Once you're happy with how your blog post looks, select Save and publish.
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

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.

Content Management Sample

Learn how to access and work with the Content Management API on your Umbraco Heartcore project.

Requirements

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

Getting Started

Add the Umbraco.Headless.Client.Net package to your project.
dotnet add package Umbraco.Headless.Client.Net

Add environment variables for your project alias and your API key.

appsettings.json

{
    "Heartcore": {
        "ProjectAlias": "your-project-alias",
        "ApiKey": "your-api-key"
    }
}

Register the ContentManagementService to your dependency injection container. The registration of the ContentManagementService is handled by the AddUmbracoHeartcore extension method.

Program.cs / Startup.cs

```csharp
builder.Services.AddUmbracoHeartcore(options =>
{
    //configure options
});
```

Inject the ContentManagementService into your non-static class.

private readonly ContentManagementService _contentManagementService;

public UmbracoService(ContentManagementService contentManagementService)
{
    _contentManagementService = contentManagementService;
}

If you don't want to use dependency injection, you can manually create an instance of the ContentManagementService class. The constructor requires that you know the project alias and your API key.

var managementService = new ContentManagementService("your-project-alias", "your-api-key");

Now you are ready to start using the ContentManagementService.

Content

When working with content, the ContentManagementService can Get, Create, Update, Publish, Unpublish, and Delete content.

Get Content

The ContentManagementService has three methods for getting content.

`GetRoot()`

Gets all content at the root of the tree.

To use this method, call the method on the ContentManagementService instance:

var content = await _contentManagementService.Content.GetRoot();

`GetById(Guid id)`

Gets a specific content item matching a GUID.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the content item you want to get:

var content = await _contentManagementService.Content.GetById(yourGuidObject);
//or
var content = await _contentManagementService.Content.GetById(Guid.Parse("your-guid-as-a-string"));

`GetChildren(Guid id)`

Gets all content that is a child of a specific content item.

To use this method, call the method on the ContentManagementService instance and pass the GUID of the content item to get the children:

var content = await _contentManagementService.Content.GetChildren(yourGuidObject);
//or
var content = await _contentManagementService.Content.GetChildren(Guid.Parse("your-guid-as-a-string"));

Create Content

The ContentManagementService has one method for creating content.

`Create(Content content)`

Creates a new content item based on the passed-in Content object.

To use this method, call the method on the ContentManagementService instance and pass in the content item you want to create:

var newContent = await _contentManagementService.Content.Create(yourContentObject);

Update Content

The ContentManagementService has one method for updating content.

`Update(Content content)`

Updates an existing content item based on the passed-in Content object.

To use this method, call the method on the ContentManagementService instance and pass in the content item you want to update:

var updatedContent = await _contentManagementService.Content.Update(yourContentObject);

Publish Content

The ContentManagementService has one method for publishing content.

`Publish(Guid id, string culture = "*")`

Publishes an existing content item based on the passed-in GUID and culture.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the content item you want to publish:

var publishedContent = await _contentManagementService.Content.Publish(yourGuidObject);
//or
var publishedContent = await _contentManagementService.Content.Publish(Guid.Parse("your-guid-as-a-string"));

Optionally, you can also pass in the culture of the content item you want to publish:

var publishedContent = await _contentManagementService.Content.Publish(yourGuidObject, "en-US");
//or
var publishedContent = await _contentManagementService.Content.Publish(Guid.Parse("your-guid-as-a-string"), "en-US");

Unpublish Content

The ContentManagementService has one method for unpublishing content.

`Unpublish(Guid id, string culture = "*")`

Unpublishes an existing content item based on the passed-in GUID and culture.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the content item you want to unpublish:

var unpublishedContent = await _contentManagementService.Content.Unpublish(yourGuidObject);
//or
var unpublishedContent = await _contentManagementService.Content.Unpublish(Guid.Parse("your-guid-as-a-string"));

Optionally, you can also pass in the culture you want to unpublish the content item in:

var unpublishedContent = await _contentManagementService.Content.Unpublish(yourGuidObject, "en-US");
//or
var unpublishedContent = await _contentManagementService.Content.Unpublish(Guid.Parse("your-guid-as-a-string"), "en-US");

Delete Content

The ContentManagementService has one method for deleting content.

`Delete(Guid id)`

Deletes an existing content item based on the passed-in GUID.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the content item you want to delete:

var deletedContent = await _contentManagementService.Content.Delete(yourGuidObject);
//or
var deletedContent = await _contentManagementService.Content.Delete(Guid.Parse("your-guid-as-a-string"));

Media

When working with media, the ContentManagementService can Get, Create, Update and Delete media.

For Media you create programmatically, you have to use the "raw" property values that Umbraco expects for the specific property editor.

The different scenarios are:

File Upload (A File Upload property editor)

When uploading a file, you must specify the file name for the umbracoFile property alias.

var media = new Umbraco.Headless.Client.Net.Management.Models.Media {
    Name = "name-of-media", 
    MediaTypeAlias = "File", 
    ParentId = parentFolderGuidObject};
media.SetValue(
    "umbracoFile", 
    fileName, 
    new FileInfoPart(new FileInfo(imagePath), 
    fileName, 
    $"image/{Path.GetExtension(imagePath).Trim('.')}"));

Image Upload (A Image Cropper property editor)

When uploading an Image (by default, it uses the Image Cropper property editor), you must specify the source's file name for the umbracoFile property alias.

var media = new Umbraco.Headless.Client.Net.Management.Models.Media {
    Name = "name-of-media", 
    MediaTypeAlias = "Image", 
    ParentId = parentFolderGuidObject};
media.SetValue(
    "umbracoFile", 
    new { src = fileName }, 
    new FileInfoPart(new FileInfo(imagePath), 
    fileName, 
    $"image/{Path.GetExtension(imagePath).Trim('.')}"));

Get Media

The ContentManagementService has three methods for getting media.

`GetRoot()`

Gets all media at the root of the tree.

To use this method, call the method on the ContentManagementService instance:

var rootMedia = await _contentManagementService.Media.GetRoot();

`GetById(Guid id)`

Gets a specific media item matching a GUID.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the media item you want to get:

var media = await _contentManagementService.Media.GetById(yourGuidObject);
//or
var media = await _contentManagementService.Media.GetById(Guid.Parse("your-guid-as-a-string"));

`GetChildren(Guid id)`

Gets all media that is a child of a specific media item.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the media item to get the children:

var mediaChildren = await _contentManagementService.Media.GetChildren(yourGuidObject);
//or
var mediaChildren = await _contentManagementService.Media.GetChildren(Guid.Parse("your-guid-as-a-string"));

Create Media

The ContentManagementService has one method for creating media.

`Create(Media media)`

Creates a new media item based on the passed-in Media object.

To use this method, call the method on the ContentManagementService instance and pass in the media item you want to create:

var newMedia = await _contentManagementService.Media.Create(yourMediaObject);

Update Media

The ContentManagementService has one method for updating media.

`Update(Media media)`

Updates an existing media item based on the passed-in Media object.

To use this method, call the method on the ContentManagementService instance and pass in the media item you want to update:

var updatedMedia = await _contentManagementService.Media.Update(yourMediaObject);

Delete Media

The ContentManagementService has one method for deleting media.

`Delete(Guid id)`

Deletes an existing media item based on the passed-in GUID.

To use this method, call the method on the ContentManagementService instance and pass in the GUID of the media item you want to delete:

var deletedMedia = await _contentManagementService.Media.Delete(yourGuidObject);
//or
var deletedMedia = await _contentManagementService.Media.Delete(Guid.Parse("your-guid-as-a-string"));

Custom Grid Editors

Learn how to create a Custom Grid Editor in Umbraco Heartcore.

Content

Create a Document Type and grid configuration

First, we will need to create a Document Type containing the Grid Layout property editor.

Go to the Settings section.
Create a new Document Type called Grid Page.
Add a new property called Grid Content.
Select the Grid layout editor.
Accept the default configuration.

The Document Type should now look like this:

To allow the Document Type to be created in the tree we need to change the permissions:

Select the Permissions tab.
Ensure Allow as root is checked.

To verify the configuration follow these steps:

Go to the Content section.
Create a new page based on the Grid Page Document Type we created.
Give it a name.
Save the page.

Try choosing a layout, add a row and click Add content. Here we will see that we have a couple of editors to choose from.

Try adding one of them to the page to see how they work.

A look at a default grid editor

Before we start writing our own Grid Editor, let's have a look at the Headline Grid Editor.

As we can see the page is divided into two sections; one with a Text Editor with the code for the editor and one with a preview of the editor.

Let's take a look at the code.

A custom editor inherits from HTMLElement and must be the default export.

export default class extends HTMLElement {

  #textarea
  #template = `<textarea
    rows="1"
    placeholder="Write here..."
    class="textstring input-block-level"
    style="font-size: 36px; line-height: 45px; font-weight: bold"></textarea>`

In the constructor we set the inner HTML of our custom element to our template and set the #textarea field to a reference to the textarea.

  constructor() {
    super()

    this.innerHTML = this.#template
    this.#textarea = this.querySelector('textarea')
  }

The click method is called when the grid control is clicked. In this case we use it to set focus on the textarea.

  click() {
    this.#textarea.focus()
  }

A value property is needed for the value to be stored when a page is saved and to set the value when the editor is loaded.

In this example the value property is setting and returning the value of the textarea.

  get value() { return this.#textarea.value }
  set value(value) {
    this.#textarea.value = value || ''
  }
}

Create a custom grid editor

Go to the Settings section.
Create a new Grid Editor.
Choose an icon.
Name it Image Gallery.
Change the alias to my-image-gallery.

The alias is used as the custom element tag name and must be unique. By choosing a prefix that is less likely to used by any other HTML element, in this case my-, there is less chance for running into conflicts.

In the JS view we can see there is already some boilerplate code. Let's replace it with the following:

import { LitElement, css, html } from 'https://cdn.jsdelivr.net/gh/lit/dist@2/all/lit-all.min.js'

export default class extends LitElement {
  static properties = {
    value: { type: Array },
  }

  static styles = css`
.container {
  display: grid;
  grid-gap: 5px;
  grid-template-columns: repeat(auto-fit, 200px);
  padding: 5px;
}
.add-button {
  font-family: var(--font-family-base);
  font-size: var(--font-size-base);
  line-height: var(--line-height-base);
  cursor: pointer;
  width: 200px;
  height: 200px;
  padding: 20px;
  padding-bottom: 30px;
  background-color: var(--color-white);
  border: 4px dashed var(--color-gray-8);
  text-align: center;
  box-sizing: border-box;
}
.add-button svg {
  display: block;
  fill: var(--color-gray-8);
  font-size: 85px;
  line-height: 1;
  display: inline-block;
  height: 1.15em;
  width: 1.15em;
  margin: 10px auto;
}
.add-button div {
  color: var(--color-black);
  font-size: 14px;
  font-weight: 700;
}
`

  render() {
    return html`<div class="container">
      <button class="add-button">
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
          <path d="M246.486 299.31l-85.604-91.047-58.21 107.66v29.658h289.12c-36.821-31.753-114.476-99.682-114.476-99.682l-30.83 53.411zM347 230.786c16.062 0 29.073-13 29.073-29.06 0-16.04-13.012-29.062-29.073-29.062-16.019 0-29.038 13.021-29.038 29.062 0 16.06 13.019 29.06 29.038 29.06zM37.74 102.699v306.569h434.688V102.699H37.74zm396.082 267.916H77.635l-.016-228.033h354.928v.017h1.275v228.016z"></path>
        </svg>
        <div>Add image</div>
      </button>
    </div>`
  }
}

The preview should now look like this:

Let's break down the code.

import { LitElement, css, html } from 'https://cdn.jsdelivr.net/gh/lit/dist@2/all/lit-all.min.js'

Here we're importing LitElement, CSS and HTML from the Lit library.

export default class extends LitElement {

We're exporting a default class inheriting from LitElement.

  static properties = {
    value: { type: Array },
  }

We tell Lit that we have a value property which we expect to be an Array.

  static styles = css`
.container {
  display: grid;
  grid-gap: 5px;
  grid-template-columns: repeat(auto-fit, 200px);
  padding: 5px;
}
.add-button {
  font-family: var(--font-family-base);
  font-size: var(--font-size-base);
  line-height: var(--line-height-base);
  cursor: pointer;
  width: 200px;
  height: 200px;
  padding: 20px;
  padding-bottom: 30px;
  background-color: var(--color-white);
  border: 4px dashed var(--color-gray-8);
  text-align: center;
  box-sizing: border-box;
}
.add-button svg {
  display: block;
  fill: var(--color-gray-8);
  font-size: 85px;
  line-height: 1;
  display: inline-block;
  height: 1.15em;
  width: 1.15em;
  margin: 10px auto;
}
.add-button div {
  color: var(--color-black);
  font-size: 14px;
  font-weight: 700;
}

  render() {
    return html`<div class="container">
      <button class="add-button">
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
          <path d="M246.486 299.31l-85.604-91.047-58.21 107.66v29.658h289.12c-36.821-31.753-114.476-99.682-114.476-99.682l-30.83 53.411zM347 230.786c16.062 0 29.073-13 29.073-29.06 0-16.04-13.012-29.062-29.073-29.062-16.019 0-29.038 13.021-29.038 29.062 0 16.06 13.019 29.06 29.038 29.06zM37.74 102.699v306.569h434.688V102.699H37.74zm396.082 267.916H77.635l-.016-228.033h354.928v.017h1.275v228.016z"></path>
        </svg>
        <div>Add image</div>
      </button>
    </div>`
  }
}

Let's save the editor and see how it looks when adding it to the a content item.

We now have the Add image button rendering, but clicking it does nothing. Let's do something about that.

Go back to the Settings section.
Click on the Image Gallery Grid Editor.

We will start by adding the following to the top of the file:

import { mediaPicker } from 'https://cdn.jsdelivr.net/npm/@umbraco/headless-backoffice-bridge@0/headless-backoffice-bridge.min.js'

We will add another function before the render function:

showPicker() {
  mediaPicker.show({
    disableFolderSelect: true,
    onlyImages: true,
    showDetails: true,
    submit: (items) => {
      const selected = items[0]
      if(!this.value) this.value = []
      this.value.push(({ url: selected.udi, ...selected }))
      this.requestUpdate('value')
    }
  })
}

This will open the Media Picker with a configuration that only allows selecting images and showing the detail view, which allows us to enter an alt text, caption and choose a focal point.

The submit callback is called when the Submit is clicked. It will contain an array of the selected items. In this case it will contain a single item, but if we set multiple to true multiple items can be returned.

In our callback method we check if this.value has been initialized. If it has not we initialize a new array. We then push the selected image to the array. Note that we also store the udi (the id of the media) in a url property. We will come back to why we do that later.

Since we add to the array and do not set the value property we need to tell Lit that the property was updated. We do this by calling this.requestUpdate('value').

We will also need to add a click event to the button so it will show the dialog:

<button type="button" class="add-button" @click=${() => this.showPicker()}>

Clicking the button in preview mode does nothing. This is because of a limitation when previewing where we do not have access to the full backoffice. Saving and testing on a Content item should work.

Click Save.
Go back to the content page.
Click the Add image button.

We should now see the image overlay.

Selecting an image does not currently render anything. Let's do something about that. Go back to the grid editor code in the Settings section.

Update the render() function with the following

render() {
  const items = this.value || []

  return html`<div class="container">
    ${items.map(image => html`<umbh-image width="200" height="200" udi=${image.udi} alt=${image.altText} .focalPoint=${image.focalPoint}></umbh-image>`)}
    <button class="add-button" @click=${() => this.showPicker()}>
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
        <path d="M246.486 299.31l-85.604-91.047-58.21 107.66v29.658h289.12c-36.821-31.753-114.476-99.682-114.476-99.682l-30.83 53.411zM347 230.786c16.062 0 29.073-13 29.073-29.06 0-16.04-13.012-29.062-29.073-29.062-16.019 0-29.038 13.021-29.038 29.062 0 16.06 13.019 29.06 29.038 29.06zM37.74 102.699v306.569h434.688V102.699H37.74zm396.082 267.916H77.635l-.016-228.033h354.928v.017h1.275v228.016z"></path>
      </svg>
      <div>Add image</div>
    </button>
  </div>`
}

We assign the editor value to a local variable items, if this.value is null or undefined we assign an empty array. Then in the HTML we are now looping over the items and returning an umbh-image for each item. umbh-image is a custom element included with the backoffice bridge, it takes an udi and renders an images based on that.

Go back to the Content section try to add some images to a page using the editor.

We now have an editor that we can add images to which gets rendered in the backoffice. Next step would be to add edit and delete functionality, but we will leave that to the reader.

Using module aliases

Up until now we have been using the full URL when importing third party modules into our editors. While this works fine most of the time, we will most likely run into issues when importing libraries that registers custom elements. This is because custom elements needs to be registered using an HTML tag and a tag can only be registered once.

Imagine we have an editor using custom elements from a third party library. We then create another editor using the same library but in a newer version which adds some new functionality to the custom element we use.

One of two things will happen:

The library checks if a custom element with the same name has already been registered and skips registration. This will leave us not knowing which version is used and might break our implementation.
It will try to register the element with the same name but fail because there is already an element registered with the same name.

In either case we will end up with a broken editor experience. This is where module aliases comes in.

Module aliases allows us to define a common name for a module that we can use in our editors instead of the full URL. A module alias can be defined by going to the Headless -> Custom Editor Configuration page in the Settings section.

With this alias added we can update our import in our editor to:

import { mediaPicker } from '@headless-backoffice-bridge'

The alias will automatically be replaced with the URL we have defined, similar to how node does.

By using the same alias in all our editors, we can ensure that only one version of the library is loaded. If we want to upgrade to a newer version, we will only need to update the URL in one place.

Describing the grid editor using JSON schema

Now that we have a working editor, let's add a couple of images to our page. When done, click Save and publish.

Note down the Id from the Info tab. We will need that in a bit.

Go to the Settings section.
Expand the Headless node.
Type in https://cdn.umbraco.io/content/<CONTENT_ID> in the Explorer URL bar, replacing <CONTENT-ID> with the id we copied before.
Click Go!.

In the output we can see the JSON we have stored in the editor.

Let's go back to our Grid Editor implementation and see what we can do.

Looking at the default JSON schema we can see that the type is set to string. This tells Heartcore that our editor is returning its data as a string. This is what we saw before in the API response. Since we are storing an array of images, let's change the type to array. We also need to specify what the array is containing. We do that by adding an items property containing a type: object property.

Change the type from string to array
Add an items property containing a type: object property.

The schema should now look like this:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "array",
    "items": {
        "type": "object"
    }
}

Let's go back to the API Browser, type the same URL as before and click Go!.

Inspecting the output, we can already see an improvement. The value is now returned as an array which is already much better.

Remember the url property stored earlier? Let's make it return a URL instead of a UDI.

Go back to the Grid Editor schema.
Update it to the following:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "url": { "type": "string", "format": "uri-reference" }
        }
    }
}

With the JSON above we are adding a properties object containing a url property. This property has its type set to string, and most importantly, format set to uri-reference. By specifying the format as uri-reference Heartcore will try to parse the value as a UDI and if the UDI is for either a document or media, the URL of that item will be returned instead. We can see that if we go back to the API Browser.

We now have an array where each item has the URL to the picked media item.

While it is not necessary to define all properties in the JSON Schema, it is highly recommended as the schema is also used for validating the editor data when saving.

Besides the uri-reference format there's also rich-text. This is useful when storing rich text data like the output from the TinyMCE editor. When specifying the rich-text format, things like {locallink} and data-uri will automatically be replaced with the correct URLs.

Related articles

Querying with GraphQL

Learn how to query Umbraco Heartcore with GraphQL.

In this tutorial we will be looking at how we can fetch data from Umbraco Heartcore using GraphQL.

We will be using https://demo.heartcore.dev/ as a reference.

At the end of the tutorial we should be able to use the Umbraco Heartcore GraphQL API and be able to fetch all the content needed to render the page in with a single query.

Creating the Document Types

First, we will need to create some Document Types, and as a start, we will create some element types.

Start by creating a folder named Elements under the Document Types folder in the Settings section of the Backoffice.

In that folder create the following Document Types:

Text and Image

Alias: textAndImage

Add a new group called Content with the following properties:

Name

Alias

Property Editor

Property Editor Configuration

Title

title

Textstring

Use defaults

Text

text

Rich Text Editor

Use defaults

Image

image

Media Picker

Pick multiple items: not checked Pick only images: checked Disable folder select: checked

Show large image

showLargeImage

Checkbox

Use defaults

Then under permissions check Element Type

Unique Selling Point

Alias: uniqueSellingPoint

Add a new group called Content with the following properties:

Name

Alias

Property Editor

Property Editor Configuration

Image

image

Media Picker

Pick multiple items: not checked Pick only images: checked Disable folder select: checked

Title

title

Textstring

Use defaults

Text

text

Textarea

Use defaults

Link

link

Multi Url Picker

Max number of items: 1

Then under permissions check Element Type

Then create another folder called Compositions and create the following Document Types in that folder:

Elements Composition

Alias: elementsComposition

Add a new group called Elements with the following properties:

Name

Alias

Property Editor

Property Editor Configuration

Elements

elements

Nested Content

Document Types: Element Type: Text and image, Group: Content, Template: {{title}} Confirm Deletes: checked Show icons: checked Hide label: checked

Then click the Reorder button and change the value for Elements from 0 to 15

Hero Composition

Alias: heroComposition

Add a new group called Hero with the following properties:

Name

Alias

Property Editor

Property Editor Configuration

Image

heroImage

Media Picker

Pick multiple items: not checked Pick only images: checked Disable folder select: checked

Title

heroTitle

Textstring

Use defaults

Subtitle

heroSubtitle

Textstring

Use defaults

Unique Selling Points Composition

Alias: uniqueSellingPointsComposition

Add a new group called Unique Selling Points with the following properties:

Name

Alias

Property Editor

Property Editor Configuration

Title

uniqueSellingPointsTitle

Textstring

Document Types: Use defaults

Unique Selling Points

uniqueSellingPoints

Nested Content

Document Types: Element Type: Unique Selling Point, Group: Content, Template: {{title}} Confirm Deletes: checked Show icons: not checked Hide label: checked

Then click the Reorder button and change the value for Elements from 0 to 20

At the root create the following Document Types:

Textpage

Alias: textpage

Click on Compositions and select Elements Composition and Hero Composition

Frontpage

Alias: frontpage

Add a new group called Footer with the following properties:

Name

Alias

Property Editor

Property Editor Configuration

Title

footerTitle

Textstring

Use defaults

Links

footerLinks

Multi Url Picker

Use defaults

Then click on Compositions and select Elements Composition, Hero Composition and Unique Selling Points Composition, click on Submit.

On the permissions tab check Allow at root and add Textpage to the Allowed child node types property.

Then go to the Content section and create a new Frontpage with the name Home and create some subpages.

Querying the GraphQL API

The GraphQL endpoint accepts POST requests with the content type application/json, the body should be an object containing as a minimum a query property, for example

{
  "query": "..."
}

Lets start with a basic query that fetches the name, url, and heroTitle properties from the Frontpage.

{
  frontpage(url: "/home/") {
    name
    url
    heroTitle
  }
}

Result:

{
  "data": {
    "frontpage": {
      "name": "Home",
      "url": "/home/",
      "heroTitle": "Umbraco Heartcore"
    }
  }
}

Making the Query Generic

Up until now, we have been working on a single Document Type. In most cases this is fine, but since we want to dynamically fetch content based on the URL we can use the content field.

The content field returns the Content interface type that contains the default fields. To allow us to query the fields on the derived types we can use fragments.

A fragment allows us to query data on the underlying concrete type.

{
  content(url: "/home/") {
    name
    ... on Frontpage {
      heroTitle
      heroSubtitle
      heroImage {
        url(width: 1980, height: 430, cropMode: CROP)
      }
    }
  }
}

This returns the following JSON:

{
  "data": {
    "content": {
      "name": "Home",
      "heroTitle": "Umbraco Heartcore",
      "heroSubtitle": "Umbraco Heartcore is a headless CMS by Umbraco. With Heartcore, you can use the Umbraco backoffice to manage content and media that's ready to be displayed on any device.",
      "heroImage": {
        "url": "https://media.umbraco.io/demo-headless/8d832c5cee78cf8/umbraco-heartcore-preview.png?mode=crop&width=1980&height=430&upscale=false"
      }
    }
  }
}

The query is fetching the name field which exists on the Content interface, it also fetches the heroTitle, heroSubtitle and heroImage on the Frontpage type.

Querying Composition Fields

There is one problem with our query though. Try changing the url argument to a subpage and see whats happening.

As you can see we don't get any data back for the hero fields, even though our Document Type has those fields. This is because we are telling GraphQL that we only want them on the Frontpage type. You might be tempted to fix this by adding another fragment on the Textpage type which would work, but remember we created a Document Type that only contains hero fields which we have added as a Composition to both the Frontpage and Textpage Document Types. We can change the ... on Frontpage fragment to ... on HeroComposition and we will now get the expected data back.

Now our query looks like this:

{
  content(url: "/home/") {
    name
    ... on HeroComposition {
      heroTitle
      heroSubtitle
      heroImage {
        url(width: 1980, height: 430, cropMode: CROP)
      }
    }
  }
}

Querying Nested Content

Since Nested Content is an interface named Element we can query the fields by the specific type using fragments.

{
  frontpage(url: "/home/") {
    elements {
      ... on TextAndImage {
        title
        text
        showLargeImage
        image {
          small: url(width: 320, height: 240, cropMode: CROP)
          medium: url(width: 480, height: 360, cropMode: CROP)
          large: url(width: 1024, height: 768, cropMode: CROP)
        }
      }
    }
  }
}

Now try to write a query that fetches the title, text, link and image fields for the Unique Selling Points property.

The only thing we are missing now to be able to render the complete page is the main navigation and the footer.

The main navigation is showing the children of the frontpage, we can fetch them with the following query:

{
  frontpage(url: "/home/") {
    children {
      edges {
        node {
          name
          url
        }
      }
    }
  }
}

The footer can be fetched using the following query:

{
  frontpage(url: "/home/") {
    footerTitle
    footerLinks {
      name
      target
      type
      url
    }
  }
}

We can even combine the two queries into a single query:

{
  global: frontpage(url: "/home/") {
    mainNavigation: children {
      edges {
        node {
          name
          url
        }
      }
    }
    footerTitle
    footerLinks {
      name
      target
      type
      url
    }
  }
}

In the query above we are also using field aliases, this means that in the response data frontpage will be named global and children will be named mainNavigation.

{
  "data": {
    "global": {
      "mainNavigation": {
        "edges": [
          {
            "node": {
              "name": "What is a Headless CMS?",
              "url": "/home/what-is-a-headless-cms/"
            }
          },
          {
            "node": {
              "name": "What you get with Umbraco Heartcore",
              "url": "/home/what-you-get-with-umbraco-heartcore/"
            }
          }
        ]
      },
      "footerTitle": "About Umbraco",
      "footerLinks": [
        {
          "name": "Umbraco Website",
          "target": "_blank",
          "type": "EXTERNAL",
          "url": "https://umbraco.com/products/umbraco-heartcore"
        },
        {
          "name": "Umbraco Heartcore Documentation",
          "target": "_blank",
          "type": "EXTERNAL",
          "url": "https://docs.umbraco.com/umbraco-heartcore/"
        }
      ]
    }
  }
}

Using Variables

You might have noticed that the url argument is hardcoded in the query. This means that we will always get back the Content for that url. What we want is to pass the argument to the query dynamically.

We can do this by altering the query to include a variable instead of the hardcoded value, this can be done by replacing the argument with $url and wrapping the query with query($url: String).

query ($url: String!){
  content(url: $url) {
    name
    ... on HeroComposition {
      heroTitle
      heroSubtitle
      heroImage {
        url(width: 1980, height: 430, cropMode: CROP)
      }
    }
  }
}

And then we pass the variable in a separate JSON property called variables

{
  "query": "...",
  "variables": {
    "url": "/home/"
  }
}

Putting it all together

Now that we have all the individual parts we can combine it all into a single query that fetches all the data needed to display the pages on our site:

query($url: String!) {
  content(url: $url) {
    ...Hero
    ...UniqueSellingPoints
    ...Elements
  }
  global: frontpage(url: "/home/") {
    mainNavigation: children {
      edges {
        node {
          name
          url
        }
      }
    }
    footerTitle
    footerLinks {
      name
      target
      type
      url
    }
  }
}

fragment Hero on HeroComposition {
  heroTitle
  heroSubtitle
  heroImage {
    url(width: 1980, height: 430, cropMode: CROP)
  }
}

fragment Elements on ElementsComposition {
  elements {
    ... on TextAndImage {
      title
      text
      showLargeImage
      image {
        small: url(width: 320, height: 240, cropMode: CROP)
        medium: url(width: 480, height: 360, cropMode: CROP)
        large: url(width: 1024, height: 768, cropMode: CROP)
      }
    }
  }
}

fragment UniqueSellingPoints on UniqueSellingPointsComposition {
  uniqueSellingPointsTitle
  uniqueSellingPoints {
    ... on UniqueSellingPoint {
      title
      text
      link {
        name
        target
        type
        url
      }
      image {
        url
      }
    }
  }
}