API Documentation

    This page contains documentation for the Umbraco Headless API endpoints divided into two main areas: Content Delivery and Content Mangement.

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

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

    REST API Standard

    The Umbraco Headless APIs are based on the HAL Standard.

    System level properties

    The properties in the Umbraco Headless 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 Umbraco Headless 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 Headless 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

    GET https://cdn.umbraco.io/content
    Umb-Project-Alias: project-alias

    Access via Query String parameter

    GET https://cdn.umbraco.io/content?Umb-Project-Alias=project-alias

    Versioning

    API versioning is handled by ASP.NET API 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

    GET https://cdn.umbraco.io/content
    api-version: 2

    Access via Query String parameter

    GET https://cdn.umbraco.io/content?api-version=2

    Access via Content negotiation

    GET https://cdn.umbraco.io/content
    Accept: application/json+hal;v=2

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

    GET https://api.umbraco.io/
    Authorization: Basic {base64-encoded-string}

    Access via an Api-Key header

    GET https://api.umbraco.io/
    Api-Key: {api-key}

    Bearer token

    The endpoints implements 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.

    POST https://api.umbraco.io/oauth/token
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=password&username={username}&password={password}

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

    GET https://api.umbraco.io/
    Authorization: Bearer {token}