umbraco.ninjaUmbraco upgrade & security

Tutorials · Intermediate

Go headless with the Umbraco Content Delivery API

Turn on Umbraco's Content Delivery API, query pages as JSON with filters, sorting and paging, secure it with an API key, and fetch content from JavaScript, React or a mobile app.

9 min read Umbraco 14 – 18 Updated 29 October 2026

What the Delivery API is

The Content Delivery API serves your published content as JSON, so any front end can use it: a React or Next.js site, a mobile app, digital signage, or another system. Umbraco stays your CMS, and the front end is up to you.

Step 1: Register it in Program.cs

In Umbraco 18 the project template doesn't add the Delivery API for you. Add .AddDeliveryApi() to the builder:

Program.cs
builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .Build();

Step 2: Turn it on

appsettings.json
{
  "Umbraco": {
    "CMS": {
      "DeliveryApi": {
        "Enabled": true,
        "PublicAccess": true,
        "RichTextOutputAsJson": false
      }
    }
  }
}

Restart the site. Umbraco builds a dedicated search index, DeliveryApiContentIndex, for the API. If results are missing, rebuild it under Settings › Examine Management.

Step 3: Make your first requests

Terminal
# Every published page (paged, 10 at a time by default)
curl "https://localhost:44360/umbraco/delivery/api/v2/content"

# One page by its URL path
curl "https://localhost:44360/umbraco/delivery/api/v2/content/item/about-us/"

# The 5 newest blog posts
curl "https://localhost:44360/umbraco/delivery/api/v2/content?filter=contentType:blogPost&sort=updateDate:desc&take=5"

# Children of the /blog/ page
curl "https://localhost:44360/umbraco/delivery/api/v2/content?fetch=children:/blog/"

# Only return the fields you need (use -g so curl doesn't treat [ ] as a pattern)
curl -g "https://localhost:44360/umbraco/delivery/api/v2/content?filter=contentType:blogPost&fields=properties[title,summary]"

Every item includes its name, contentType, route (its URL), dates and properties.

Step 4: Use it from JavaScript

js
const base = "https://cms.example.com/umbraco/delivery/api/v2";

async function latestPosts() {
  const res = await fetch(`${base}/content?filter=contentType:blogPost&sort=updateDate:desc&take=5`);
  if (!res.ok) throw new Error(`Delivery API returned ${res.status}`);
  const data = await res.json();
  return data.items.map(item => ({
    title: item.name,
    url: item.route.path,
    summary: item.properties.summary,
  }));
}

Step 5: Lock it down

If your content isn't meant to be public, turn off public access and require an API key:

appsettings.json
{
  "Umbraco": {
    "CMS": {
      "DeliveryApi": {
        "Enabled": true,
        "PublicAccess": false,
        "ApiKey": "set-this-as-an-environment-variable"
      }
    }
  }
}

Send it with every request in the Api-Key header. Keep the key on your server; never put it in browser JavaScript.

You can also stop certain document types from appearing in the API with DisallowedContentTypeAliases, for example ["settings", "formSubmission"].

Need a hand?

umbraco.ninja has more than 20 years of Umbraco experience. If you'd rather not do this yourself, we'll set it up, test it and hand it over.

Get a fixed-price quote