home / skills / nikiskaarup / skills / umbraco-content-delivery-api

umbraco-content-delivery-api skill

safe

This skill guides Claude to use the Umbraco Content Delivery API safely and efficiently with endpoint selection, localization, and preview handling.

npx playbooks add skill nikiskaarup/skills --skill umbraco-content-delivery-api

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

1.6 KB

---
name: umbraco-content-delivery-api
description: Guide Claude to use the Umbraco Content Delivery API effectively and safely.
---

# Umbraco Content Delivery API

## Purpose

Guide Claude to use the Umbraco Content Delivery API endpoints correctly and efficiently.

## Scope

- Included: endpoint selection, path vs id usage, query parameters, headers, preview, localization.
- Excluded: backoffice mutations, schema changes, or MCP administrative operations.

## When to Use

- You need to read content via the Delivery API.
- You need to craft requests with filters, expansion, or paging.

## When Not to Use

- You need to create or update content.
- You need to manage content types or media in the backoffice.

## Endpoint Strategy

- Choose the smallest endpoint that returns the needed data.
- Prefer single-item endpoints for known content items.
- Use list and query endpoints for discovery and pagination.
- See `references/request-recipes.md` for common request shapes.

## Request Policy

- Use `Start-Item` for multi-site or root-scoped queries.
- Use `Accept-Language` only when requesting by id.
- Use `Preview: true` with `Api-Key` for draft content.
- Limit payloads with `fields` and use `expand` only when needed.

## Response Format

- Provide a canonical request shape with headers and query parameters.
- Explain the minimum required inputs and expected response types.

## Examples

- Get a content item by id.
- Get a content item by path.
- Fetch children of a node with paging.
- Filter by content type and sort by update date.
- Fetch a draft item with preview and API key.

Overview

This skill guides Claude to call the Umbraco Content Delivery API effectively and safely. It focuses on read-only operations: selecting the correct endpoints, composing headers and query parameters, and handling preview and localization. The guidance helps produce minimal, predictable requests and interpret standard responses.

How this skill works

The skill inspects the intent to read content and chooses the smallest endpoint that returns the required fields. It composes canonical requests with appropriate headers (Start-Item, Accept-Language, Preview, Api-Key) and query parameters (fields, expand, paging, filters, sort). It also explains expected response shapes and when to prefer id vs path queries.

When to use it

When you need to fetch a single content item or list of items for rendering.
When you must filter, sort, or page through content collections.
When requesting draft content using Preview with an Api-Key.
When resolving multi-site or root-scoped content via Start-Item.

Best practices

Choose the smallest endpoint that returns only the data you need to reduce payload size.
Prefer single-item endpoints by id for known content; use path endpoints only when ids are unknown.
Limit response fields with the fields parameter and enable expand only for necessary relations.
Use Start-Item for multi-site or root-scoped requests to guarantee correct resolution.
Send Accept-Language only on id-based requests to avoid ambiguous behavior.
Use Preview: true together with a valid Api-Key to fetch draft content safely.

Example use cases

Get a content item by id with fields=title,body and Accept-Language for localized content.
Fetch a content item by path to discover a page when id is unknown.
List children of a node with paging parameters (page, pageSize) and sort by update date.
Filter a collection by content type and a custom property, then expand related items as needed.
Fetch a draft preview of a page using Preview: true and including the Api-Key in headers.

FAQ

When should I use path vs id queries?

Use id queries when you know the content id for precision and performance. Use path queries when ids are unknown or when resolving routes from URLs.

How do I request draft content?

Include Preview: true in headers and provide a valid Api-Key. Limit the request to required fields and avoid exposing Api-Key in client-side code.