# GraphQL API

The GraphQL API can be accessed on `https://graphql.umbraco.io`, it accepts POST requests with the content type `application/json`. The body must be JSON and contain a `query` field with the query as a string and an optional `variables` field containing the variables.

```json
{
  "query": "query($url: String) { content(url: $url) { name } }",
  "variables": {
    "url": "/"
  }
}
```

## API Access

In order to access the data for your Umbraco Heartcore project you need to provide a project identifier (Project Alias) via an HTTP Header or a Querystring parameter.

The Project Alias is an HTTP friendly version of the Project Name under your Umbraco Cloud account.

### Access via Umb-Project-Alias header

```http
POST https://graphql.umbraco.io/
Umb-Project-Alias: {project-alias}
```

## Authorization

By default the GraphQL API is not protected. This can be enabled through the Backoffice, where API keys for each user in the Backoffice is also managed.

To access the GraphQL API the user must have access to the `Content` section and have the `Browse Node` permission.

### Access via an Api-Key header

```http
POST https://graphql.umbraco.io/
Api-Key: {api-key}
```

## Preview

The GraphQL API supports fetching draft content, this can be done by passing a `preview` argument to the root query fields.

{% hint style="info" %}
Fetching draft content requires an API Key to be passed with the request.
{% endhint %}

```graphql
query {
  content(preview: true) {
    name
  }
}
```

## Persisted queries

The GraphQL API supports [persisted queries](https://docs.umbraco.com/umbraco-heartcore/api-documentation/graphql/persisted-queries), running a persisted query can be done using the following payload in the Graphql request:

```json
{
  "extensions": {
    "persistedQuery": {
      "alias": "{Alias}"
    }
  }
}
```

The persisted queries also support variables

```json
{
  "extensions": {
    "persistedQuery": {
      "alias": "{Alias}"
    }
  },
  "variables": {
    "url": "/"
  }
}
```

{% hint style="info" %}
Persisted queries can be created within the backoffice in the [GraphQL Playground](https://docs.umbraco.com/umbraco-heartcore/getting-started/graphql-playground#persisted-queries)
{% endhint %}

## [Schema Generation](https://docs.umbraco.com/umbraco-heartcore/api-documentation/graphql/schema-generation)

Information on how the GraphQL schema is generated, reserved names and built-in custom types.

## [Property Editors](https://docs.umbraco.com/umbraco-heartcore/api-documentation/graphql/property-editors)

A list of all the built-in Umbraco Property Editors and their GraphQL types.

## [Filtering and Ordering](https://docs.umbraco.com/umbraco-heartcore/api-documentation/graphql/filtering-and-ordering)

Documentation on how to filter and order collections with the GraphQL API.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.umbraco.com/umbraco-heartcore/api-documentation/graphql.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.