---
canonical: https://amplience.com/developers/docs/apis/asset-management/overview/conventions/
title: Conventions
description: GraphQL conventions for the Amplience GraphQL Management API, including connections, edges, nodes, pagination and the Relay cursor connections specification.
audience: Developer
date_published: 2022-06-23
date_modified: 2026-07-13
---

# Conventions

## Connections and pagination

GraphQL Cursor Connections Specification, or [Relay spec](https://relay.dev/graphql/connections.htm) provides a consistent interface for querying by id and for pagination within queries that return a list.

The GraphQL Management API uses this standard wherever paginated result sets are available — not just for assets and media, but across the whole API, including content generation sessions, teams, extensions and webhook listeners.

### Connections

Connections are used to describe the connection between an object in the graph and the objects it is connected to. In the GraphQL Management API the `viewer` is connected to its `mediaHubs` and `organizations`, each media hub is connected to its `assetRepositories`, each asset repository is connected to its `assetFolders` and each asset folder is connected to its `assets`.

```
├── viewer
│   ├── mediaHubs
│   │   ├── assetRepositories
│   │   │   ├── assetFolders
│   │   │   │   ├── assets
│   ├── organizations
```

### Edges and PageInfo

Connections will always contain `edges` and a `pageInfo` field (of type [PageInfo](https://amplience.com/developers/docs/apis/asset-management/reference/objects/#pageinfo)).

The `edge` describes the relationship between the two nodes (e.g. between the media hub and the asset repository).

The `pageInfo` object describes the current set of results and is detailed in the [Pagination](#pagination) section below.

### Nodes

A `node` is a single entity in the graph, for example an `asset` or an `assetFolder`.

### Single node queries

You can fetch a single `asset` using the [node](https://amplience.com/developers/docs/apis/asset-management/reference/queries/#node) query

```graphql
{
  node(id: "QXNzZXQ6ZjQwYTQ2MjQtMDAyYS00YThiLTljODMtYzU4NDJmZWNhODkx") {
    id
    ... on Asset {
      mimeType
    }
  }
}
```

### Multiple node queries

Queries that return a list (multiple `nodes`) use the `connection` > `edges` > `node` structure defined by the Cursor Connections Specification.

For example to return the list of assets for an [assetSearch](https://amplience.com/developers/docs/apis/asset-management/reference/queries/#assetsearch) query:

```graphql
{
  assetSearch(keyword: "Red") {
    edges {
      node {
        id
        name
      }
    }
  }
}
```

> **Note:** The id used in node queries is a specific id for use within our GraphQL Management API. Assets also have an `assetId`, which is a shorter UUID, which is for compatibility with asset manifests and existing integrations.

## Pagination

For multiple node queries that support pagination, the values in the `pageInfo` object can be used along with the arguments `first` and `after`, or `last` and `before`:

- `first` specifies the number of results to return when paginating forwards, and is **required whenever `after` is used**
- `last` specifies the number of results when paginating backwards, and **must be used together with `before`**

The [PageInfo](https://amplience.com/developers/docs/apis/asset-management/reference/objects/#pageinfo) object will allow you to determine whether there is a next or previous page (`hasNextPage`, `hasPreviousPage`) as well as the start and end cursor to use when paging (`startCursor`, `endCursor`).

For example the following `assetSearch` query

```graphql
{
  assetSearch(keyword: "Red") {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        name
      }
    }
  }
}
```

Returns this response:

```json
{
  "data": {
    "assetSearch": {
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJtYXJrZXIiOiJBb0lJUDRBQUFEOEZabVpo..."
      },
      "edges": [
        {
          "node": {
            "id": "QXNzZXQ6ZjQwYTQ2MjQtMDAyYS00YThiLTljODMtYzU4NDJmZWNhODkx",
            "name": "red-armchair"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6MDAxMTIyMzMtNDQ1NS02Njc3LTg4OTktYWFiYmNjZGRlZWZm",
            "name": "red-lamp"
          }
        }
      ]
    }
  }
}
```

The `endCursor` value from the response can then be passed into the `after` argument of the next request:

```graphql
{
  assetSearch(
    keyword: "Red"
    first: 20
    after: "eyJtYXJrZXIiOiJBb0lJUDRBQUFEOEZabVpo..."
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        name
      }
    }
  }
}
```

> **Note:** `assetSearch` connections additionally return a `total` field with the overall result count, which is useful when building paging controls. `total` is specific to asset search results — most other connections in the API expose only `edges` and `pageInfo`.