# Manage Endpoint Aliases Source: https://docs.graphops.xyz/subgraphs/guides/manage-aliases Keep the same query URL when you release a new Subgraph version. An Endpoint Alias gives your application a name such as `positions` or `production`, while your organization chooses its target and when that target changes. ## Prerequisites * A GraphOps organization with Subgraphs access. * An Owner or Developer role to manage Endpoint Aliases. * An API key that includes Subgraphs. * A Deployment CID, Graph Network Subgraph ID, or existing Managed Subgraph to target. * The schema fields your production clients use, so you can check compatibility before you retarget. ## Choose a target type The **Target type** decides when your Endpoint Alias moves to a new deployment: * **Deployment CID**: stays on that exact deployment until you change it. * **Graph Network Subgraph ID**: follows the versions published for that ID on The Graph Network, including schema changes chosen by the Subgraph owner. * **Managed Subgraph**: serves a version of a Managed Subgraph your organization indexes. ## Choose a target behavior Graph Network Subgraph ID and Managed Subgraph targets also need a **Target behavior**: * **Latest available version** (Graph Network Subgraph ID, recommended): serves the newest version that indexers on The Graph Network can serve. When the owner publishes, the previous version keeps serving until indexers catch up on the new one. It then moves and stays on the new version. * **Latest published version** (Graph Network Subgraph ID): moves as soon as the owner publishes, even if no indexer can serve the new version yet. * **Current version** (Managed Subgraph): follows the serving Current version, so it moves only after a Next version meets the readiness checks and is promoted. Use it for production. * **Next version** (Managed Subgraph): serves the Next version while it's being indexed, including partially indexed data, and falls back to the Current version when there's no Next version that can serve. Use it as a staging endpoint. *Endpoint Aliases for one published Subgraph when its owner publishes a new version: two Graph Network Subgraph ID targets with different target behaviors, a Managed Subgraph that follows the same ID, and a Deployment CID. Each moves at a different time.* - Before: Every Endpoint Alias serves the owner's published version. (Latest published version: Qm…a1f4; Latest available version: Qm…a1f4; Managed Subgraph: Qm…a1f4; Deployment CID: Qm…a1f4) - Owner publishes: Latest published moves once the release is validated, before indexers can serve it. Latest available keeps serving the previous version, and the Managed Subgraph indexes the release as Next. (Latest published version: Qm…7c2e; Latest available version: Qm…a1f4 Waiting for indexers; Managed Subgraph: Qm…a1f4 Next Syncing; Deployment CID: Qm…a1f4) - New version serves: Latest available moves once indexers serve the new version, and the Managed Subgraph target moves when its Next version is promoted. The Deployment CID target stays until you change it. (Latest published version: Qm…7c2e; Latest available version: Qm…7c2e; Managed Subgraph: Qm…7c2e; Deployment CID: Qm…a1f4) Choose Latest available version or a Managed Subgraph target when indexing readiness should control endpoint changes. Choose a Deployment CID target when your team wants to change deployments by hand. [Choose your Subgraph setup](../choose-a-setup) compares the complete setups. A typical release flow for your own Subgraph uses two Endpoint Aliases on one Managed Subgraph: a `production` alias with Current version and a `staging` alias with Next version. Staging moves to a new version as soon as it can serve queries, production moves when you promote it, and both serve the same version between releases. ## Choose and update an Endpoint Alias ### Create or choose the Endpoint Alias \[#create-or-choose-the-endpoint-alias] Choose a short name that represents the application contract, such as `uniswap-v3`, `positions`, or `production`. Use separate Endpoint Aliases, such as `positions` and `positions-dev`, when environments should move at different times. You can also create one while getting a query endpoint: in **Get query endpoint**, choose Subgraphs, then **Endpoint Alias**, and choose **Create Endpoint Alias**. It asks the same questions as creating the Endpoint Alias from the Endpoint Aliases page, described in the next step. After it's created, choose **Get query endpoint** to return with the new Endpoint Alias selected, ready to choose an API key. If you close it instead, you return to where you left off. Endpoint Alias query URL: ```text https://subgraphs.graphops.xyz/v1/alias/ ``` ### Point the Endpoint Alias to a target \[#point-the-endpoint-alias-to-a-target] [Create Endpoint Alias](https://platform.graphops.xyz/organizations/current/services/subgraphs/new) Creating an Endpoint Alias asks two questions, one at a time, before you name it: 1. What it follows: choose its [**Target type**](#choose-a-target-type), then enter the Deployment CID or Graph Network Subgraph ID, or select the Managed Subgraph. 2. How it moves to new versions: choose its [**Target behavior**](#choose-a-target-behavior) from the ones that target type offers. A Deployment CID target has none to choose; it stays on that deployment. Then name it and check the query URL the name gives. Review shows the target, its target behavior and the Deployment CID the Endpoint Alias will serve, and nothing is created until you confirm there. A Managed Subgraph target needs an active Managed Subgraph in your organization; until you have one, choose **Set up a Subgraph** from that option's explanation to create one. While you [explore a Subgraph](./discover-public-subgraphs#keep-the-subgraph-in-your-organization), you can instead choose **Create Endpoint Alias** to start with its identifier. On a Managed Subgraph's page, it starts with that Managed Subgraph as the target. To change an existing Endpoint Alias, choose **Change target** from its row actions. It asks the same two questions. Before you save, it shows what the Endpoint Alias serves now and after saving. A Deployment CID, Latest published version or Current version target switches queries as soon as you save, so confirm the new deployment answers first. A Latest available version or Next version target switches once that version can serve queries. After you save, it shows the Deployment CID the Endpoint Alias serves and, for a Latest available version alias that is waiting, the latest version and why it isn't serving yet. Every target must resolve to a valid single-network deployment. If a Graph Network Subgraph ID target can't be resolved later, the Endpoint Alias keeps its last mapping and shows a tracking error. ### Verify the target \[#verify-the-target] The **Target type** column shows each Endpoint Alias's target type and target behavior; their info icons explain them. The **Target** column shows the Graph Network Subgraph ID or Managed Subgraph the Endpoint Alias follows and its **Serving CID**, the Deployment CID that answers its queries. When that isn't the version its target behavior names, a note says which version it is, such as Previous version. When a Latest available version alias is waiting for indexers, the column also shows the **Latest CID** and why it isn't serving yet. Use the row's actions to explore the target's schema or get its query endpoint. Then query `_meta` through the Endpoint Alias: ```graphql query AliasTarget { _meta { deployment block { number hash } hasIndexingErrors } } ``` Output ```json { "data": { "_meta": { "deployment": "QmTZ8ejXJxRo7vDBS4uwqBeGoxLSWbhaA7oXa1RvxunLy7", "block": { "number": 26285621, "hash": "0x40c3154aaa484a99057c58a6c72c27171ed861d260179db387850027655d0881" }, "hasIndexingErrors": false } } } ``` Should match the Serving Deployment CID Should keep rising on the new target Roll back if this turns true ### Roll back if needed \[#roll-back-if-needed] For an Endpoint Alias with a Deployment CID target, change its target to the previous Deployment CID after confirming that deployment is queryable. Keep previous CIDs in your release records. For an Endpoint Alias with a Managed Subgraph target, prepare and promote the previous deployment as another [Managed Subgraph upgrade](../managed-subgraphs), or explicitly convert the Endpoint Alias to a Deployment CID target. A Managed Subgraph upgrade must meet the readiness checks before promotion. To stop an Endpoint Alias from following Graph Network publications, convert it to a Deployment CID target. A Latest available version alias doesn't move back to an earlier version on its own; to return to one, change it to a Deployment CID target. ## Release safely * Treat Endpoint Alias updates as application releases, and retarget during low-risk windows if schema changes can affect live traffic. * Confirm required entity names, fields, filters, and ordering fields before you retarget. * Keep previous Deployment CIDs available as rollback targets. * Log the [`X-Deployment-CID` response header](../api#response-headers) or `_meta.deployment` in production diagnostics so support can see which deployment served a request. ## Next steps * [Managed Subgraphs](../managed-subgraphs): Prepare and promote a Next version behind a Managed Subgraph target. * [Monitor sync health](./monitor-sync-health): Confirm the serving deployment and its freshness after each change. * [Identifiers and Endpoint Aliases](../concepts/identifiers-and-aliases): Compare Endpoint Aliases with direct identifiers.