Skip to content

Endpoint Aliases

Keep one query URL for your application while your organization chooses which Subgraph version it serves, and when it moves to the next one.

Release a new Subgraph version without releasing your application. An Endpoint Alias is an organization-owned name for a query endpoint, such as orders or production. Its URL stays the same while your organization chooses what it serves and when that changes.

Reference

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

The Endpoint Alias name is scoped to the organization associated with the API key. To create one or change its target, follow Manage Endpoint Aliases.

Target types

The Target type decides what the Endpoint Alias serves:

  • A Deployment CID target stays on that exact deployment until you change the target. Its code and schema are fixed, but indexed data can still change.
  • A Graph Network Subgraph ID target follows the versions published for that ID on The Graph Network.
  • A Managed Subgraph target serves a version of a Managed Subgraph that your organization indexes.

Identifier types compares these identifiers when you query them directly, without an Endpoint Alias.

Target behaviors

Graph Network Subgraph ID and Managed Subgraph targets also have a Target behavior that decides which of the target's versions serves:

Target typeTarget behaviorServes
Graph Network Subgraph IDLatest available versionThe newest published version that indexers on The Graph Network can serve. While a new version is still being indexed, the previous version keeps serving.
Graph Network Subgraph IDLatest published versionEach new version as soon as its owner publishes it, even before indexers can serve it.
Managed SubgraphCurrent versionThe serving Current version. It moves when a ready Next version is promoted, through a manual upgrade or automatic following.
Managed SubgraphNext versionThe Next version while it's being indexed, including partially indexed data. Without a Next version that can serve, it falls back to the Current version.

Latest available version moves to a new version once an indexer serving it on The Graph Network reports it healthy and close to the chain head. After it moves, it stays on that version even if indexers later fall behind. Both Graph Network Subgraph ID behaviors follow schema changes chosen by the Subgraph owner.

An Endpoint Alias keeps one URL while your organization chooses its target and target behavior. A Deployment CID target never moves on its own; a Managed Subgraph target serves its Current or Next version; a Graph Network Subgraph ID target follows the network.

Versions shows, setup by setup, when an Endpoint Alias starts serving a newly published version.

Choose a target

  • 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 second Endpoint Alias with the Next version behavior as a staging endpoint for those tests.
  • Use a Deployment CID target when your team wants to change deployments by hand, and treat each change like an application release.
  • Use a Graph Network Subgraph ID target with Latest available version to follow someone else's Subgraph without indexing it yourself.

Retargeting an Endpoint Alias doesn't change your application's URL, so you can start with one Target type and change it later.

Next steps

Last updated