Migrate from Alchemy - Tags

Tags are used to maintain a consistent GraphQL endpoint. You can treat them like pointers or aliases to specific versions, allowing you to swap in new subgraphs in your app without changing your front-end code. Both Alchemy and Goldsky support this concept, but they implement it differently. This guide will help you understand the differences and migrate your workflow.

How Alchemy handles versions

Alchemy Subgraphs uses a “live version” promotion system:

Each subgraph has a live version that serves traffic at a static endpoint
Each subgraph version also gets its own version-specific endpoint
When deploying a new subgraph, the first version is automatically set to live
When deploying new versions of existing subgraphs, they are not automatically promoted to live; you manually promote versions to live via the dashboard or API, or enable auto-promotion for a version to become live once it finishes syncing.

Alchemy endpoint structure:

# Live version endpoint (static, always points to promoted version)
https://subgraph.satsuma-prod.com/<QUERY_KEY>/<TEAM_ID>/<SUBGRAPH_NAME>/api

# Version-specific endpoint (unique per version)
https://subgraph.satsuma-prod.com/<QUERY_KEY>/<TEAM_ID>/<SUBGRAPH_NAME>/version/<VERSION_NAME>/api

Promoting a version to live: You can promote via the dashboard or make 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>'

Auto-promote (for CI/CD): You can enable auto-promote so a version automatically becomes live once it finishes syncing:

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>"

How Goldsky handles tags

Goldsky uses a simpler, explicit tagging system:

Subgraph endpoints are named after the subgraph name and version by default
You create tags explicitly using the CLI to create stable endpoint aliases
Tags can be moved between versions seamlessly
No concept of “live version” - tags are the primary mechanism for stable endpoints

Goldsky endpoint structure:

# Version-specific endpoint (default)
https://api.goldsky.com/api/public/<PROJECT_ID>/subgraphs/<SUBGRAPH_NAME>/<VERSION>/gn

# Tag-based endpoint
https://api.goldsky.com/api/public/<PROJECT_ID>/subgraphs/<SUBGRAPH_NAME>/<TAG>/gn

Goldsky deployment:

goldsky subgraph deploy <SUBGRAPH_NAME>/<VERSION> --path .

Migrating your workflow

Step 1: Create a tag for your production endpoint

Instead of promoting to “live”, create a tag that represents your production environment:

goldsky subgraph tag create my-subgraph/1.0.0 --tag prod

This creates a stable endpoint at:

https://api.goldsky.com/api/public/<PROJECT_ID>/subgraphs/my-subgraph/prod/gn

Step 2: Update your application code

Replace your Alchemy endpoint with the Goldsky tag-based endpoint: Before (Alchemy):

const SUBGRAPH_URL = "https://subgraph.satsuma-prod.com/<QUERY_KEY>/<TEAM_ID>/my-subgraph/api";

After (Goldsky):

const SUBGRAPH_URL = "https://api.goldsky.com/api/public/<PROJECT_ID>/subgraphs/my-subgraph/prod/gn";

Step 3: Deploy new versions and update tags

When you deploy a new version, the tag workflow is straightforward:

# Deploy new version
goldsky subgraph deploy my-subgraph/2.0.0 --path .

# Move the prod tag to the new version
goldsky subgraph tag create my-subgraph/2.0.0 --tag prod

Your application will now seamlessly query the new version without any code changes.

Benefits of Goldsky’s approach

More explicit: Tags are clearly defined, not implicit “live” promotions. While this means additional effort in switching the tags once a subgraph is sycned, it allows for more explicit control over when frontend changes go live.
Multiple stable endpoints: Create as many tags as you need (prod, staging, dev, etc.), and name them as appropriate in your workflow. This is a simpler mental model where all tags are just pointers to a specific subgraph version, there is no special “live” state.

​How Alchemy handles versions

​How Goldsky handles tags

​Migrating your workflow

​Step 1: Create a tag for your production endpoint

​Step 2: Update your application code

​Step 3: Deploy new versions and update tags

​Benefits of Goldsky’s approach