---
title: Working with pages in the API
related:
  - https://docs.kentico.com/k12sp/managing-website-content/working-with-pages.md
  - https://docs.kentico.com/k12sp/developing-websites/retrieving-content-in-mvc-applications/displaying-page-content.md
  - https://docs.kentico.com/k12sp/developing-websites/defining-website-content-structure/creating-and-configuring-page-types.md
  - https://docs.kentico.com/k12sp/developing-websites/generating-classes-for-kentico-objects.md
  - https://docs.kentico.com/k12sp/custom-development/working-with-pages-in-the-api/reference-documentquery-methods.md
  - https://docs.kentico.com/k12sp/custom-development/retrieving-database-data-using-objectquery-api.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

The Kentico API allows you to retrieve and manage page content using custom code.

Use the following classes from the **CMS.DocumentEngine** namespace to work with pages in the API:

- **TreeNode** – object that represents pages. The _TreeNode_ class encapsulates data from the _CMS\_Tree_ and _CMS\_Document_ [tables](https://docs.kentico.com/k12sp/custom-development/working-with-pages-in-the-api/page-database-structure.md), and the coupled data tables of individual page types.
- **DocumentQuery** and **MultiDocumentQuery** – classes that represent a query for loading pages. You can further parametrize the query to only retrieve the pages you need. Both are similar in functionality:
  - **DocumentQuery** allows you to retrieve pages of a single [page type](https://docs.kentico.com/k12sp/developing-websites/defining-website-content-structure/creating-and-configuring-page-types.md) (when an instance is created with a page type class name as the constructor parameter) or general pages of any type (when using a parameterless constructor). If used for a single specific page type, the resulting query automatically includes coupled data of the given page type (e.g., news, articles, blogs). _DocumentQuery_ is also used internally by [generated page type providers](https://docs.kentico.com/k12sp/developing-websites/retrieving-content-in-mvc-applications/displaying-page-content.md) and any custom providers or repositories built around them.
  - **MultiDocumentQuery** allows you to retrieve pages of multiple page types in a single query at the cost of effectiveness. The coupled data of page types is not retrieved unless explicitly requested using the _WithCoupledColumns_ [parametrization method](https://docs.kentico.com/k12sp/custom-development/working-with-pages-in-the-api/reference-documentquery-methods.md).
- **DocumentHelper** – provides static methods for retrieving and managing the latest edited versions of pages. Internally, the _DocumentHelper_ class utilizes _DocumentQuery_ or _MultiDocumentQuery_ to retrieve pages and then further adjusts the query, for example by applying the _CombineWithDefaultCulture_ parametrization method based on the value of the _Combine with default culture_ setting.

> **Info:** **Page query parametrization methods**
>
> For detailed information about the options that allow you to parameterize page queries, see the dedicated reference: [Reference - DocumentQuery methods](https://docs.kentico.com/k12sp/custom-development/working-with-pages-in-the-api/reference-documentquery-methods.md)

> **Info:** **Loading other objects**
>
> To learn how to retrieve other types of non-page data from the Kentico database, see [Retrieving database data using ObjectQuery API](https://docs.kentico.com/k12sp/custom-development/retrieving-database-data-using-objectquery-api.md).

## Retrieving pages

For basic retrieval of pages in your code, use the **DocumentHelper.GetDocuments** method and parameterize it using [parametrization methods](https://docs.kentico.com/k12sp/custom-development/working-with-pages-in-the-api/reference-documentquery-methods.md) to only include the pages you need. If you have [generated page type providers](https://docs.kentico.com/k12sp/developing-websites/generating-classes-for-kentico-objects.md) available, you can use them with the same parametrization methods, and then work with strongly typed page objects.

```csharp title="Example"

// Retrieves the published English version of articles that are in the '/Articles/May' section of the 'MySite' site's content tree
// Only loads pages that are currently published on the live site according to the value of their Published from/to setting
var pages = DocumentHelper.GetDocuments("MySite.Articles")
                    .OnSite("MySite")
                    .Culture("en-us")
                    .Path("/Articles/May", PathTypeEnum.Children)
                    .PublishedVersion()
                    .Published();

```

### Retrieving pages under workflow

When working with pages under [workflow](https://docs.kentico.com/k12sp/configuring-kentico/configuring-the-environment-for-content-editors/configuring-workflows.md), you may want to retrieve the latest edited version in some cases and the published version in others.

- Use the **PublishedVersion** [parametrization method](https://docs.kentico.com/k12sp/custom-development/working-with-pages-in-the-api/reference-documentquery-methods.md) to retrieve the published version of pages under workflow (when retrieving pages to be displayed on the live site).
- Use the **LatestVersion** [method](https://docs.kentico.com/k12sp/custom-development/working-with-pages-in-the-api/reference-documentquery-methods.md) to retrieve the latest edited version of pages under workflow (when retrieving pages for further editing or previewing of unpublished changes).

> **Note:** **Note**: The **Published** [parametrization method](https://docs.kentico.com/k12sp/custom-development/working-with-pages-in-the-api/reference-documentquery-methods.md) does not specify the version of the pages you retrieve, instead it limits the retrieved pages to only those that are currently published according to the value of their  **Published from** / **Published to**  settings and have a published version.

### Retrieving content in the preview mode and page builder

When retrieving page content in the code of your MVC application for the [preview mode](https://docs.kentico.com/k12sp/developing-websites/retrieving-content-in-mvc-applications/adding-preview-mode-support.md) or the [page builder](https://docs.kentico.com/k12sp/developing-websites/page-builder-development.md) interface, you want to get the latest version of the content, but you want the published version to be displayed on the live site. To achieve this, you can parametrize queries to conditionally serve a different version of content based on where the content is displayed.

```csharp

using CMS.DocumentEngine;

using Kentico.Content.Web.Mvc;
using Kentico.PageBuilder.Web.Mvc;
using Kentico.Web.Mvc;

// Checks whether the current page is displayed in preview mode or the edit mode of the page builder
bool showLatest = HttpContext.Kentico().PageBuilder().EditMode || HttpContext.Kentico().Preview().Enabled;

// Retrieves the latest edited version of pages in preview mode or the page builder, but the published version in other cases
DocumentQuery pages = DocumentHelper.GetDocuments("Custom.Smartphone")
                                        .LatestVersion(showLatest);

```

### Retrieving pages for custom scenarios

**DocumentHelper** automatically performs some parameterization of the query to simplify the code for the most common scenarios. However, if you require full control over the query, you can directly use the **DocumentQuery** or **MultiDocumentQuery** classes to ensure that there is not any unexpected parametrization done in the background.

```csharp

// Retrieves all pages that match the query
var pages = new MultiDocumentQuery()
                    .OnCurrentSite()
                    .Path("/Articles/Reviews")
                    .Culture("en-us")
                    .PublishedVersion()
                    .WithCoupledColumns();

```

```csharp

// Retrieves pages of the specified page type that match the query
var pages = new DocumentQuery("Custom.Smartphone")
                    .OnCurrentSite()
                    .Path("/Products")
                    .Culture("en-us")
                    .PublishedVersion();

```

## Working with retrieved pages

You can iterate through the retrieved collection to access the properties of individual pages. The available columns depend on how you parametrized the query when retrieving the pages.

```csharp

// Retrieves smartphone pages
DocumentQuery smartphones = DocumentHelper.GetDocuments("CMS.Smartphone")
                                .Path("/Products/", PathTypeEnum.Children)
                                .OnSite("CorporateSite");

// Writes the 'DocumentName' and 'SmartphoneOS' values of each of the retrieved smartphones into an HTTP output response stream
foreach (TreeNode smartphone in smartphones)
{      
    string smartphoneOS = smartphone.GetValue<string>("SmartphoneOS", "Default OS");
    Response.Write(HTMLHelper.HTMLEncode(smartphone.DocumentName) + " - " + HTMLHelper.HTMLEncode(smartphoneOS) + "<br />");
}

```

## Updating pages

To update a page (_TreeNode_ object):

1. Retrieve the latest edited version of a page using the methods described above.
2. Modify the page's data:
   - For general page fields, directly set the corresponding _TreeNode_ properties.
   - For the fields of specific page types, call the _TreeNode.SetValue("FieldName", value)_ method.
3. Call the **TreeNode.Update()** method.

> **Note:** **Updating pages under workflow**
>
> When using the API to update pages under [workflow](https://docs.kentico.com/k12sp/configuring-kentico/configuring-the-environment-for-content-editors/configuring-workflows.md) or [versioning](https://docs.kentico.com/k12sp/configuring-kentico/configuring-the-environment-for-content-editors/configuring-and-using-page-versioning.md), always retrieve the page objects with all fields. Otherwise, the update may cause data loss. Use one of the following approaches:
>
> - Call the _DocumentHelper.GetDocuments(string className)_ method with a _className_ parameter for a specific page type.
> - Use the **Types** query method to identify the page types and then apply the **WithCoupledColumns** method.