Skip to main content
Creating and managing aliases requires API version 2026-07 or later and is available through the REST API. Reading through an alias works on any API version, including the current SDKs.
Create, list, describe, repoint, and delete namespace aliases in an index. Each operation is a single REST call to your index host. To swap the data an application reads with no downtime, see Swap a namespace. You need a project role that can manage namespaces, such as DataPlaneEditor, ProjectOwner, or ProjectManager. Managing aliases needs the same access as managing namespaces directly.

​
Operations

Each alias is returned as {name, target_namespace, created_at, updated_at}. updated_at advances on every repoint.

​
Errors

Every rejection carries a machine-readable reason in details[0].reason. SDKs and agents branch on the reason, not the message text. You also get a reason when a request addresses an alias name where it shouldn’t:

​
Create an alias

Specify a name for the alias and the target_namespace it points at. The target must be an existing, ready namespace in the same index. A namespace that’s still initializing, importing, or restoring is refused. If a create returns a 409 with reason ALIAS_ALREADY_EXISTS and details[0].metadata.target_namespace matches the target you asked for, an earlier call already succeeded and the alias is live, so a retry can treat it as done. A different target is a real conflict.
curl

​
List aliases

List the aliases in an index to see what each one targets.
curl
The response lists the aliases in the index, ordered by name, with a total_count. When more aliases remain, the response includes a pagination.next token. Pass it as paginationToken on the next request to get the following page. Use limit to set the page size, and filter the list by prefix and target_namespace.
curl

​
Describe an alias

Describe a single alias to see its current target and when it last changed.
curl
Create, describe, and repoint return the alias object:
curl

​
Repoint an alias

Point the alias at a different namespace. The repoint is atomic, and when the call returns success, all reads resolve to the new target. Repointing to a namespace that doesn’t exist or isn’t ready is rejected, and the alias keeps its current target.
curl

​
Delete an alias

Deleting an alias never touches the target namespace or its data. A delete that returns a 404 means the alias is already gone, so a retry can safely treat it as done.
Any application still reading through the alias name will start getting empty results, not an error. Move your readers to the namespace name, or to a different alias, before you delete.
curl

​
See also