API Reference
Alchemy Login

Subgraph Versioning

Learn how to maintain multiple versions of your subgraph.

Overview

Alchemy Subgraphs (fka Satsuma) allows you to deploy different subgraphs and subgraph versions.

  • Each subgraph has a live version, which serves traffic at a static endpoint:

    https://subgraph.satsuma-prod.com/<QUERY KEY>/<TEAM ID>/<SUBGRAPH NAME>/api

  • Each subgraph version gets a version-specific endpoint:

    https://subgraph.satsuma-prod.com/<QUERY KEY>/<TEAM ID>/<SUBGRAPH NAME>/version/<VERSION NAME>/api

  • Version names must be unique within a subgraph.

  • Alchemy will randomly generate a version name when deploying from versions of the CLIs that don't support the --version-label flag.

Promoting a version to live

When deploying a new subgraph, the first version will be set to live.

However, new versions of existing subgraphs will not be automatically promoted to live. You can promote the version to live within the dashboard.

API endpoint

You can also set a version to live via an API call:

curl -X POST https://subgraphs.alchemy.com/api/subgraphs/<TEAM ID>/<SUBGRAPH_NAME>/<VERSION_NAME>/promote-live \
	-H 'x-api-key: <DEPLOY_KEY>'

Your team ID is automatically-generated — it can be found directly after the query key in your subgraph's query endpoint.

Use cases

This flexible system allows you to do things like:

  • Test a new version with live queries before switching your application over.
  • Instantly roll back to a previous version if there are issues with a new version.

Auto-promote

In certain situations, you might want to auto-promote a newly deployed version. Once the subgraph version finishes syncing, it will automatically get promoted to live.

This can be useful within your CI / CD pipelines.

API endpoint

Make a request to this endpoint to enable auto-promote for a subgraph version:

curl -X POST https://subgraphs.alchemy.com/api/subgraphs/<TEAM ID>/<SUBGRAPH_NAME>/<VERSION_NAME>/auto-promote-live \
	-H "Content-Type: application/json" -H "x-api-key: <DEPLOY_KEY>"

Your team ID is automatically-generated — it can be found directly after the query key in your subgraph's query endpoint.

ReadMe