Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.goldsky.com/llms.txt

Use this file to discover all available pages before exploring further.

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.