> ## 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.

# Migrating subgraph 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:

```bash theme={null}
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:

```bash theme={null}
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:**

```bash theme={null}
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:

```bash theme={null}
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):**

```javascript theme={null}
const SUBGRAPH_URL = "https://subgraph.satsuma-prod.com/<QUERY_KEY>/<TEAM_ID>/my-subgraph/api";
```

**After (Goldsky):**

```javascript theme={null}
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:

```bash theme={null}
# 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.