Subgraphs: Identifiers and Endpoint Aliases

Every Subgraph query names a version, directly or indirectly. Choose who controls that version: pin a deployment yourself, follow the Subgraph owner on The Graph Network, or manage releases through your own Endpoint Alias. The choice decides whether a schema change can reach your application without a release on your side.

Identifier types

Identifier	Endpoint segment	Who controls updates	Best for
Deployment CID	`deploymentCID/<DEPLOYMENT_CID>`	No one; the deployment is immutable.	Staying on one exact deployment and schema.
Graph Network Subgraph ID	`subgraphId/<SUBGRAPH_ID>`	The Subgraph owner on The Graph Network.	Following the current version selected on The Graph Network.
Endpoint Alias	`alias/<ALIAS>`	Your organization in the GraphOps Platform UI.	Stable endpoints targeting a Deployment CID, a Managed Subgraph, or a Graph Network Subgraph ID.

Deployment CID

A Deployment CID identifies one immutable Subgraph deployment. Use it to keep the code and schema version fixed. Its indexed data still changes as new blocks arrive; a CID does not freeze query results.

https://subgraphs.graphops.xyz/v1/deploymentCID/<DEPLOYMENT_CID>

Deployment CIDs are useful for:

Verifying a migration against one exact deployment.
Holding application behavior stable during a release.
Running query tests against a known schema.

Graph Network Subgraph ID

A Graph Network Subgraph ID identifies a Subgraph on The Graph Network. It can move to a new deployment when the Subgraph is upgraded on the network.

https://subgraphs.graphops.xyz/v1/subgraphId/<SUBGRAPH_ID>

Use Graph Network Subgraph IDs when you want to follow the version selected by the Subgraph owner on The Graph Network.

Endpoint Alias

An Endpoint Alias is an organization-owned name for a query endpoint. Its URL stays the same while your organization chooses its Target type:

A Deployment CID target stays on that exact deployment until you change the target. Its code and schema are fixed; indexed data can still change.
A Managed Subgraph target follows the resource's serving Current version when a ready Next version is promoted, through a manual upgrade or automatic following.
A Graph Network Subgraph ID target follows the latest validated publication for that ID on The Graph Network, independently of Managed Subgraph indexing readiness.

The Endpoint Alias name is scoped to the organization associated with the API key.

https://subgraphs.graphops.xyz/v1/alias/<ALIAS>

An Endpoint Alias keeps one URL while your organization chooses its target. A Deployment CID target never moves on its own; a Managed Subgraph target moves on promotion; a Graph Network Subgraph ID target follows the network.

Target a Managed Subgraph when endpoint changes should wait for its promotion checks. Promotion requires a healthy version that meets indexing readiness checks; it does not guarantee schema compatibility. Manual upgrades can accept breaking changes, and following a Graph Network Subgraph ID authorizes them automatically. Test affected clients before enabling following or promoting a manual upgrade. Use a Deployment CID target when your team wants to change deployments manually.

Choose an identifier

Requirement	Choose
Your team wants to keep one exact deployment until it explicitly changes the target	Deployment CID, or an Endpoint Alias with a Deployment CID target
The endpoint should track The Graph Network version	Graph Network Subgraph ID
Your Endpoint Alias should track published versions without waiting for managed indexing	Endpoint Alias with a Graph Network Subgraph ID target
Your team must approve each upgrade	Endpoint Alias with a Managed Subgraph target and manual upgrades
Published versions should be indexed and promoted automatically when ready	Endpoint Alias with a Managed Subgraph target that follows a Graph Network Subgraph ID
You want to test a candidate deployment before release	Next version or Deployment CID
You want application code to avoid hardcoded CIDs	Endpoint Alias

Apply the model

Treat a change to an Endpoint Alias with a Deployment CID target like an application release.
Prefer Deployment CIDs for migration tests and rollback targets.
Choose manual Managed Subgraph upgrades when your team must test each release before promotion.
Enable following only when your clients can accept releases chosen by the Subgraph owner, including breaking schema changes.
Check _meta.deployment after changing a Graph Network Subgraph ID or Endpoint Alias target.