Duplicates and aliases

Overview

The API grew alongside the console, and in several places the same capability is reachable from more than one path. None of it is broken, but picking the wrong one costs you later — an alias can be withdrawn, and a scoped variant can quietly return a narrower set than you expected. This page lists every overlap worth knowing about, and what to use.

This is a documentation concern, not a deprecation schedule. Nothing here is being removed today. The one path explicitly marked deprecated in the reference is the /restart alias below.

True aliases — same handler, two paths

Reboot an instance

Path	Prefer
`POST /api/v1/compute/instances/{id}/reboot`	Yes
`POST /api/v1/compute/instances/{id}/restart`	No — marked deprecated

Both routes are served by the same code, so behaviour is identical. /reboot names what actually happens; /restart is a compatibility alias.

Don’t confuse either with POST /api/v1/networks/{id}/restart or POST /api/v1/vpcs/{vpcId}/restart, which restart network infrastructure. Those are unrelated operations that happen to share a verb.

Same data, two paths

Guest OS types

Path	Prefer
`GET /api/v1/ostypes`	Yes — canonical, and takes `id`, `osCategoryId` and `description` filters
`GET /api/v1/compute/instances/os-types`	No — convenience route with no filters

ISOs

Path	Prefer
`GET /api/v1/isos`	Yes — the full ISO surface, alongside register, upload and permissions
`GET /api/v1/compute/instances/isos`	No — the same list, shaped for the instance create flow

Path	Prefer
`GET`/`POST`/`DELETE` `/api/v1/tags/resources/{resourceType}/{resourceId}`	Yes — one code path for every resource type
`…/compute/instances/{id}/tags`	No
`…/networks/{id}/tags`	No
`…/vpcs/{id}/tags`	No
`…/compute/kubernetes/clusters/{id}/tags`	No

Overlapping capability, different conventions

Creating a network ACL

Two ways to create the same thing, and they don’t take the same input:

Path	Input	Notes
`POST /api/v1/network-acls`	JSON body	Prefer this. Sits with the rule endpoints under the same tag.
`POST /api/v1/vpcs/{vpcId}/acl-lists`	Query parameters `name`, `description`	Scopes to the VPC in the path.

Listing differs too: GET /api/v1/network-acls covers your ACLs, and GET /api/v1/vpcs/{vpcId}/acl-lists covers those for one VPC. Both are legitimate — just be deliberate about which you use, because the second returns a subset and looks like an empty account if you pass the wrong VPC.Rule management is only under /api/v1/network-acls/rules, so a create through the VPC path still sends you back there.

Internal load balancers

Path	Notes
`GET`/`POST` `/api/v1/loadbalancer/internal`	Prefer this. Sits with the rest of the load balancing surface.
`GET`/`POST` `/api/v1/networks/{id}/load-balancers`	The same internal load balancers, scoped to one network.
`DELETE /api/v1/networks/load-balancers/{lbId}`	Deletion lives only here — there is no `/loadbalancer/internal/{id}` sibling for it in the network flow.

These are internal load balancers. They are not the same thing as /api/v1/loadbalancer/rules, which manages public load balancer rules on a public address. The naming makes them look interchangeable and they are not.

Compute offerings

Path	Returns
`GET /api/v1/offerings/compute`	The offering catalogue, optionally filtered by `family`
`GET /api/v1/offerings/service`	The platform’s service offerings for your account

These are closely related views of the same catalogue. Use /compute when populating a deploy form.

GET /api/v1/offerings/compute accepts a zoneId parameter that has no effect — the result is not filtered by zone. Filter client-side if you need per-zone offerings.

Quota and limits

Five endpoints report on allowances:

Path	Scope
`GET /api/v1/tenants/my-limits`	Your own effective limits
`GET /api/v1/tenants/quota`	Quota for your organization context
`GET /api/v1/tenants/{tenantId}/limits`	One organization’s limits
`GET /api/v1/multi-regions/quota`	Region-group allowance
`GET /api/v1/onboarding/multi-region-quota`	The same allowance, during onboarding

For “am I about to hit a ceiling”, use GET /api/v1/tenants/my-limits. The others answer narrower questions, and the two region-group ones are only meaningful if region grouping is enabled for you.

Scoped variants — not duplicates

These look like duplication but each returns a genuinely different set. Using the wrong one gives you a wrong answer rather than an error, which makes them worth stating explicitly.

Listing public addresses

Path	Returns
`GET /api/v1/public-ips`	Every address on your account
`GET /api/v1/vpcs/{vpcId}/public-ips`	Addresses belonging to one VPC
`GET /api/v1/networks/{id}/public-ips`	Addresses on one network tier
`GET /api/v1/vpcs/public-ips/available`	Addresses free to associate — a candidate list, not an inventory

Listing snapshots

Path	Returns
`GET /api/v1/volumes/snapshots`	Volume snapshots across the account
`GET /api/v1/volumes/{id}/snapshots`	Snapshots of one volume
`GET /api/v1/compute/instances/snapshots`	Instance snapshots across the account
`GET /api/v1/compute/instances/{id}/snapshots`	Snapshots of one instance

Volume snapshots and instance snapshots are different resources with different lifecycles, not two views of one thing. See Snapshots and VM Snapshots.

Listing instances

Four list endpoints, each with a different cost and shape:

Path	Use when
`GET /api/v1/compute/instances`	Default. Paged, filterable.
`GET /api/v1/compute/instances/with-metrics`	You need CPU and memory alongside each row. Heavier.
`GET /api/v1/compute/instances/summary`	You want a lightweight list with no paging — for a picker.
`GET /api/v1/compute/instances/all`	You want everything unpaged.

/all and /summary don’t page. On a large account they return one very large response, and there is no way to ask for less. Prefer the paged endpoint for anything that grows.

Egress rules

Three different enforcement points, all called “egress”:

Path	Applies to
`/api/v1/firewall/egress`	A public address
`/api/v1/networks/{id}/egress-rules`	A network tier
`/api/v1/security-groups/{id}/egress-rules`	A security group, on basic networking

These are not alternatives — they sit at different layers, and which one applies depends on how your account is networked. If you are using VPCs, you want the network tier and Network ACLs.

Fabric links

Path	Scope
`/api/v1/network/vpc-vpn`	VPC-to-VPC managed links — the customer-facing one
`/api/v1/network/region-vpn`	Region-level links underneath

Use /vpc-vpn unless you have a specific reason not to. See Fabric.

Repeated sub-resources

Comments (annotations) and tags appear on several resource types with identical shapes:

GET    /api/v1/{resource}/{id}/annotations
POST   /api/v1/{resource}/{id}/annotations
PUT    /api/v1/{resource}/annotations/{annotationId}/visibility

Present on volumes, networks, public IPs, VPCs and Kubernetes clusters.

Note the shape of the visibility route: the annotation id sits directly under the resource collection, not under a resource id. So it is /api/v1/volumes/annotations/{annotationId}/visibility, not /api/v1/volumes/{id}/annotations/{annotationId}/visibility.Only volumes expose a DELETE for an annotation. Elsewhere a comment cannot be removed once posted — see Comments.

Conventions

Pagination and envelopes.

Introduction

What is in scope, and what isn’t.

Asynchronous work

Following a mutation.

Errors

Reading a refusal.

Using the API

Endpoints

Duplicates and aliases

Overview

True aliases — same handler, two paths

Reboot an instance

Same data, two paths

Guest OS types

ISOs

Tags

Overlapping capability, different conventions

Creating a network ACL

Internal load balancers

Compute offerings

Quota and limits

Scoped variants — not duplicates

Listing public addresses

Listing snapshots

Listing instances

Egress rules

Fabric links

Repeated sub-resources

Conventions

Introduction

Asynchronous work

Errors

​Overview

​True aliases — same handler, two paths

​Reboot an instance

​Same data, two paths

​Guest OS types

​ISOs

​Tags

​Overlapping capability, different conventions

​Creating a network ACL

​Internal load balancers

​Compute offerings

​Quota and limits

​Scoped variants — not duplicates

​Listing public addresses

​Listing snapshots

​Listing instances

​Egress rules

​Fabric links

​Repeated sub-resources

​Related

Conventions

Introduction

Asynchronous work

Errors

Overview

True aliases — same handler, two paths

Reboot an instance

Same data, two paths

Guest OS types

ISOs

Tags

Overlapping capability, different conventions

Creating a network ACL

Internal load balancers

Compute offerings

Quota and limits

Scoped variants — not duplicates

Listing public addresses

Listing snapshots

Listing instances

Egress rules

Fabric links

Repeated sub-resources

Related