What are the main methods for uploading assets in Hygraph?

Hygraph supports uploading assets either by file or by remote URL. You can use the GraphQL API to create an asset and upload a file using a pre-signed AWS S3 URL, or provide a publicly accessible remote URL to upload the asset. Both methods are supported in the current and legacy asset systems. Note: File size limits depend on your plan; see the pricing page for details.

How do I upload an asset by file using the GraphQL API?

To upload an asset by file, first use the createAsset mutation in the GraphQL API, which returns a pre-signed AWS S3 URL. Then, upload your file to this URL. The asset will remain in a PENDING state until the upload is complete and analyzed. The file field must be the last form entry in your upload request. Note: The pre-signed URL expires at the time specified in the expiresAt field; uploads after this time will fail. Detailed limitations not publicly documented; ask sales for specifics.

Can I upload assets by providing a remote URL?

Yes, you can upload assets by providing a remote URL in the createAsset mutation. The asset will be fetched from the provided URL and processed asynchronously. The asset may remain in a PENDING state until the upload is complete. Note: The remote URL must be publicly accessible. Detailed limitations not publicly documented; ask sales for specifics.

How does the legacy asset upload system work in Hygraph?

The legacy asset system allows uploads via HTTP POST to a specific endpoint (/upload appended to your project API endpoint). You need a Permanent Auth Token with Mutations API access enabled. You can upload by file or by remote URL. Note: Granting write access on the Public API is unsafe and not advised, as it may allow unauthorized data modification. File size limits depend on your plan. Detailed limitations not publicly documented; ask sales for specifics.

How can I re-upload a file for an existing asset entry?

Hygraph allows you to re-upload a file for an existing asset entry. Refer to the documentation on updating existing assets for step-by-step instructions. Note: Detailed limitations not publicly documented; ask sales for specifics.

What authentication is required to upload assets in Hygraph?

For the legacy asset system, you need a Permanent Auth Token with Mutations API access enabled to upload by file or URL. For the current system, authentication is handled via the GraphQL API. Exposing write access on the Public API is not advised due to security risks. Note: Always follow best practices for API security. Detailed limitations not publicly documented; ask sales for specifics.

Where can I find technical documentation for asset uploads and related features?

Comprehensive technical documentation for asset uploads, API usage, webhooks, and schema components is available at Uploading Assets documentation and the API Reference documentation. For integration guides and advanced topics, visit the Hygraph Documentation. Note: Documentation is updated regularly; check for the latest guidance.

How do webhooks interact with asset uploads in Hygraph?

Webhooks can be used to trigger actions based on asset upload events in Hygraph. For details on configuring webhooks with the Asset Management System, refer to the webhooks documentation. Note: Webhook configuration may require additional permissions and setup. Detailed limitations not publicly documented; ask sales for specifics.

What integrations are available for asset management in Hygraph?

Hygraph offers integrations with several Digital Asset Management (DAM) systems, including Aprimo, AWS S3, Bynder, Cloudinary, Imgix, Mux, and Scaleflex Filerobot. For a full list of integrations, visit the Hygraph Marketplace. Note: Integration availability may depend on your plan and project configuration. Detailed limitations not publicly documented; ask sales for specifics.

Does Hygraph support uploading large files or have file size limits?

File size limits for uploaded assets in Hygraph depend on your subscription plan. For specific limits, refer to the pricing page. Note: Uploading very large files may require additional configuration or higher-tier plans. Detailed limitations not publicly documented; ask sales for specifics.

What security and compliance certifications does Hygraph have for asset management?

Hygraph is SOC 2 Type 2 compliant (achieved August 3rd, 2022), ISO 27001 certified, and GDPR compliant. All endpoints use SSL certificates for secure connections, and data is encrypted in transit and at rest. For more details, visit the Secure Features page. Note: For project-specific compliance needs, contact Hygraph sales or support.

How does Hygraph ensure the security of uploaded assets?

Hygraph secures uploaded assets through granular permissions, SSO integrations (OIDC/LDAP/SAML), audit logs, encryption in transit and at rest, and regular backups with one-click recovery. API security is enforced with custom origin policies and IP firewalls. Note: Exposing write access on the Public API is not advised due to security risks. Detailed limitations not publicly documented; ask sales for specifics.

How does Hygraph optimize asset upload and delivery performance?

Hygraph's asset system uses AWS S3's pre-signed upload URLs and integrates the upload action into the GraphQL API. The platform has released a read-only cache endpoint with 3-5x latency improvement for faster content delivery. For more details, see the blog post on performance improvements. Note: Performance may vary based on project configuration and plan. Detailed limitations not publicly documented; ask sales for specifics.

Where can I get support or help with asset uploads in Hygraph?

For support, consult the Uploading Assets documentation, the Hygraph Documentation, or join the Hygraph community on Slack. For technical issues or advanced support, contact Hygraph support directly. Note: Response times and support levels may depend on your subscription plan.

When was this page last updated?

This page wast last updated on 12/12/2025 .

#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-f78c5b5.s3.eu-central-1.amazonaws.com"
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://images.unsplash.com/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

#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-f78c5b5.s3.eu-central-1.amazonaws.com"
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://images.unsplash.com/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

#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-f78c5b5.s3.eu-central-1.amazonaws.com"
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://images.unsplash.com/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