> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-cms/17.latest/develop-with-umbraco/templating-and-rendering/querying/udi-identifiers.md).

# UDI Identifiers

UDIs are an identifier format in Umbraco. Learn how they are structured, how to query content with them, and how to convert between UDIs and GUIDs.

A Unique Document Identifier (UDI) is a string that identifies an Umbraco entity. An example of a UDI is `umb://document/4fed18d8c5e34d5e88cfff3a5b457bf2`.

Most Umbraco APIs identify entities by their GUID key. The backoffice and the Management API both work with plain GUIDs. UDIs are more commonly used as a storage and integration format.

## Format

A UDI consists of three parts:

| Part        | Example                            | Description                                                                                         |
| ----------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- |
| Scheme      | `umb://`                           | Marks the value as an Umbraco identifier.                                                           |
| Entity type | `document`                         | The type of entity the identifier points to. Other examples are `media`, `member`, and `data-type`. |
| Identifier  | `4fed18d8c5e34d5e88cfff3a5b457bf2` | The unique identifier of the entity.                                                                |

### GUID and string UDIs

The identifier part is either a GUID or a string. Which one is used depends on the entity type.

A [`GuidUdi`](https://apidocs.umbraco.com/v17/csharp/api/Umbraco.Cms.Core.GuidUdi.html) has a GUID as its identifier. The GUID is written without dashes. Most entity types use this format, such as `document`, `media`, and `member`.

```none
umb://document/4fed18d8c5e34d5e88cfff3a5b457bf2
```

A [`StringUdi`](https://apidocs.umbraco.com/v17/csharp/api/Umbraco.Cms.Core.StringUdi.html) has a string as its identifier, such as a file path or a culture code. A few entity types use this format, such as `stylesheet`, `script`, and `language`.

```none
umb://stylesheet/style.css
umb://language/en-US
```

## Where you encounter UDIs

You do not usually create a UDI yourself. It shows up in stored property values that reference another entity:

* The Content Picker and Multi Node Tree Picker property editors store their raw database value as a UDI. For multiple selections, the value is a comma-separated list of UDIs. If you read the stored value, for example with `IContent.GetValue<string>()`, you get the UDI string.

Use `UdiParser.TryParse()` to read the value. See [Convert between UDIs and GUIDs](#convert-between-udis-and-guids).

## Query content with a UDI

`IPublishedContentQuery` accepts UDIs directly through the `Content(Udi)` and `Media(Udi)` overloads. You do not need to convert a UDI to a GUID first.

The following example resolves a UDI in a view:

{% code title="MyView\.cshtml" %}

```csharp
@using Umbraco.Cms.Core
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@inject IPublishedContentQuery PublishedContentQuery

@{
    const string storedValue = "umb://document/4fed18d8c5e34d5e88cfff3a5b457bf2";
    if (UdiParser.TryParse(storedValue, out Udi? udi))
    {
        // Pass the UDI straight to the query. No conversion needed.
        IPublishedContent? content = PublishedContentQuery.Content(udi);
        <p>@content?.Name</p>
    }
}
```

{% endcode %}

`UmbracoHelper` exposes the same overloads. In a view that inherits `UmbracoViewPage`, you can call `Umbraco.Content(udi)` instead.

## Convert between UDIs and GUIDs

Use `UdiParser.TryParse()` to read a UDI. Parsing is safer than manipulating the string, as it validates both the entity type and the identifier. The `Guid` property gives you the key used by the GUID-first APIs:

```csharp
if (UdiParser.TryParse("umb://document/4fed18d8c5e34d5e88cfff3a5b457bf2", out GuidUdi? udi))
{
    Guid contentKey = udi.Guid;
}
```

To build a UDI from an entity type and a GUID key, use `Udi.Create()`:

```csharp
Guid contentKey = Guid.Parse("4fed18d8-c5e3-4d5e-88cf-ff3a5b457bf2");
Udi udi = Udi.Create(Constants.UdiEntityType.Document, contentKey);
```

These types are all in the `Umbraco.Cms.Core` namespace.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/umbraco-cms/17.latest/develop-with-umbraco/templating-and-rendering/querying/udi-identifiers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.