Assets, while most commonly used for photos, can support any file type including audio files, zip files and more. You can extend assets with custom fields.

Assets are handled through our CDN, Filestack. As such, some of the behavior listed below will include special handling as there's a secondary service to account for. Assets are localized by default.

Asset Fields

Assets are a core feature in GraphCMS and are their own distinct type. The default fields for an asset are:

url(transformation: AssetTransformationInput): String!

The url transorm.

stage: Stage!

locale: Locale!

The current locale of the asset (without any other filters this will be the default).


All the localizations available for the asset.

locales: [Locale!]! = [en, de, es, fr],
includeCurrent: Boolean! = false
): [Asset!]!


Get all the stages where the document can be found.

stages: [Stage!]! = [DRAFT, PUBLISHED]
includeCurrent: Boolean! = false
inheritLocale: Boolean! = false
): [Asset!]!

id: ID!

The system ID for the asset enty

createdAt: DateTime!

The time the document was created

updatedAt: DateTime!

The time the document was updated

publishedAt: DateTime

The time the document was published. Null on documents in draft stage.

handle: String!

The file handle

fileName: String!

The file name from when the document was uploaded to the CMS.

height: Float

The height of the file (only for images)

width: Float

The file width (only for images)

size: Float

The total file size.

mimeType: String

The mime type of the file

Sample Asset Picker Query


authors {
avatar {


"data": {
"authors": [
"avatar": {
"url": ""

Filtering by Assets

Filtering by assets can be accomplished by their own fields and the associated field type (see the corresponding documentation or each type). Example: width_lte, height_gt, etc.

  • id: ID!
  • createdAt: DateTime!
  • updatedAt: DateTime!
  • publishedAt: DateTime
  • handle: String!
  • fileName: String!
  • height: Float
  • width: Float
  • size: Float
  • mimeType: String

Asset can also be filtered by relation, see relation filtering for more details.

Mutating an Asset

For mutating an asset, please see the related mutation documentation for the fields listed above. For connecting an asset, see relation mutations.

Were you expecting something more?

We are constantly contributing to our documentation, but if you spot something we're missing, let us know and we'll be sure to add it.

This site uses cookies to provide you with a better user experience. For more information, refer to our Privacy Policy