Skip to main content
Use the reference field declared by the operation, such as image, volume, vpc or iam_role. Where supported, the same field accepts a UUID, a Cloud Resource Name (CRN), or a name. Each field’s API description defines its accepted kinds and scope; a resource having a name does not mean every operation can resolve that name.

​
How a reference is classified

Classification uses the input syntax, before looking for a resource:
  1. A literal, case-sensitive crn: prefix selects CRN parsing. A malformed CRN is an error; it is never retried as a name.
  2. A 36-character UUID in 8-4-4-4-12 hexadecimal form selects UUID lookup. Hexadecimal letters may be upper- or lowercase.
  3. Everything else selects name validation and lookup for that resource kind.
Inputs are not trimmed. A missing UUID or CRN is never retried as a name. Resource names cannot start with crn: or use a UUID spelling, including compact, braced and URN UUID spellings. Each service also enforces its own name syntax. These reserved shapes keep names separate from identifiers.

​
Canonical identities

A reference chooses an existing resource. Responses return its canonical identity, not the spelling you submitted. Relationship bindings retain the resolved UUID; reusing a deleted resource’s name does not retarget an existing binding. A CRN has this shape:
The account slot is an account handle. Global services have an empty region slot. Organization-scoped IAM resources have empty region and account slots; your organization context still bounds access. Identical IAM CRN text in two organizations does not grant access across organizations. Regional flavors, platform-owned images and shared defaults use the platform account slot. For every resource with a unique, user-chosen name, that name is its CRN identity. Names and therefore CRNs are immutable. A mutable display label is a separate property: IAM user and organization names, account display names and security-key labels do not become name-based reference identities. Account identity uses its immutable handle. Resources without a unique user-chosen name use UUID identities where they expose resource CRNs. Examples include floating IPs, DNS records, database backups, load-balancer listeners and rules, IAM users and organizations, credentials, audit events and billing records. A DNS record’s owner name is protocol data and can occur on several records. A backup label or a floating IP address is not a resource name reference. Numbered secret versions and catalog/protocol tokens follow their endpoint’s explicit contract.

​
Parent-scoped CRNs

A child appends a type/identity pair to its parent’s complete CRN. The parent CRN is a literal prefix, preserving every ancestor:
The chain distinguishes children with the same name under different parents. Supply the complete ancestry; a flat subnet or snapshot name in a CRN is not a complete child identity. Named children use names; unnamed children use their UUIDs in the same chain. IAM inline policies append inline-policy/<name> to their principal CRN. Protocol payloads have explicit exceptions to structural pairs: bucket object keys remain opaque slash-bearing keys after the bucket name, and log-group names can themselves contain slashes. Policy wildcard expressions are policy patterns, not concrete request references.

​
Resource paths

Use the returned UUID in a resource path declared as a UUID, such as GET /v1/instances/{instance_id}. Do not put a name or slash-bearing CRN in that path. Protocol paths, including bucket names and database user/database names, retain the parameter types shown by their operations.

​
Resolution scopes

Compute and database network requests do not provide the VPC needed for a bare subnet lookup. Use a subnet UUID or complete nested CRN. Load-balancer creation provides a VPC and can resolve a subnet name in it. A subnet update can derive its VPC from the owned subnet. A reference never bypasses ownership, parent membership, readiness, trust or permission checks. Certificate CRNs use an empty region slot even though certificate requests use a regional endpoint. Copy canonical response CRNs instead of inferring their scope from a hostname.

​
Image names and versions

Image reference fields support these forms: Name and name:version lookups use the request architecture, defaulting to amd64 when omitted. A CRN supplies its own architecture and version; a UUID already identifies one build. Names consider your account and public platform images. Among usable matches, your account wins over the platform. An explicit CRN selects only its stated owner. Another customer’s images and private platform images are unavailable to you, even if you know their UUIDs. A current name can select a newer build on a later request. A UUID, version tag or full CRN pins a build; instance-pool templates store the resolved image UUID. Withdrawal does not redirect a pinned reference to a replacement. A withdrawn image returns IMAGE_NOT_FOUND; when end-of-life information is available, its message explains the withdrawal. Usable visible matches take precedence over withdrawal diagnostics. Treat the error code as stable and the message as text for a person.

​
Errors and protocol boundaries

For relationship resolution, malformed syntax, an unsupported reference kind, a wrong service/type or incomplete ancestry produces a validation error. The shared resolver also rejects a wrong region as invalid input. A missing target or foreign account is reported as not found. Services retain their documented resource-specific codes and permission errors; inspect the operation’s error responses. Do not retry another reference kind after an error. An exact collection filter is a selector, not a relationship lookup. A valid foreign or mismatched CRN selects no rows. Malformed or empty CRNs return 400; endpoint-specific validation details are listed below. An empty result is not a failed attempt to resolve a name. Region parameters use region codes such as sa-saopaulo-1, not UUIDs, CRNs or display names. Audit resource and actor selectors search historical UUID/CRN snapshots without requiring the target to still exist; bare names are not historical references. The audit collection’s crn selects the event itself. Object keys, upload/version tokens, DNS record content, OAuth client identifiers, trace/span identifiers, metric names, log-stream labels and literal IP targets retain their protocol meaning. Log-group and KMS reference fields still follow their declared resource contracts. In particular, S3 bucket encryption’s AES256 placeholder does not imply support for a KMS target.

​
Exact lists

Where declared, name and crn are exact predicates combined with AND, with ownership, parent and other filters applied before pagination. name=web-* does not mean a prefix search. An omitted filter differs from an explicitly empty one: name= retains an empty predicate, and crn= follows the endpoint-specific validation below. Never remove an empty filter and retry, because that would broaden the request. Top-level subnet and route-table name lists require vpc; interface name lists require subnet (and vpc when that subnet is itself a bare name). Snapshot name lists require volume. A complete child CRN supplies its own ancestry, but any additional parent filter must agree. Instance NIC lists instead match interface names within that instance’s bindings, so duplicate names from different subnets can yield multiple matches. A declared name selector need not identify a unique resource. IAM display-name lists, DNS record owner names, and image names across architectures/versions can match several rows. DNS zone names are lowercased for matching. Lists of unnamed resources that declare name return no matches for it: this includes floating IPs, routes, security-group rules, database backups and load-balancer child resources. Database engine/parameter catalogs have no resource CRN and match no CRN selector; storage volume-type names are exact display labels (SSD, NVMe), with token-based catalog CRNs. Secret versions expose numbered child CRNs and no name filter. include_deleted can make a secret name match multiple identities.

​
List validation details

Malformed syntax and empty CRN selectors return 400 on resource collections below, including log groups, IAM, KMS and secrets. Valid foreign identities and mismatched name/CRN predicates return an empty collection, not a relationship-not-found error. Strict ancestry validation in compute, network, storage, database, IAM, KMS and secrets also rejects incomplete child chains. DNS record and certificate lists parse syntax first and treat a structurally parseable but incompatible kind or ancestry as an empty match. Certificate lists reject an invalid certificate-name segment. Secret-version lists reject invalid version numbers, including zero and noncanonical numbers such as 01. Parent path authorization still applies to nested lists. Exact selectors do not turn an inaccessible parent into a successful empty collection.

​
Collection operations

Each link below gives the operation’s exact parameters, response shape and pagination contract. “Protocol” means use that operation’s documented selectors; it has no generic resource name/crn pair.

​
Fetch one resource by any reference

Classify the input using the rules above. For a UUID, call the resource’s UUID GET operation directly. For a name or CRN, query its collection with the matching exact filter and required parent scope. Follow pagination until you can establish whether exactly one resource matches. Zero matches means no visible match; multiple matches require a more specific scope or canonical CRN. Never choose the first row arbitrarily. Use the returned id for subsequent UUID-path calls. If that GET returns not found, the resource may have been deleted between calls. These are HTTP request targets; sign each request using your normal authentication and account context. Query values must be URL-encoded.
For the exact instance name web-01:
For its CRN, encode colons and slashes in the query value:
After exactly one match, use that response’s UUID in Get instance. For a subnet name, include the VPC scope, for example /v1/subnets?vpc=production&name=private; for a snapshot name, use /v1/snapshots?volume=data&name=daily. Image relationship tags are not literal image-list names: query name and architecture with all_versions=true, then match the returned version and apply the documented caller/platform precedence. There is no public version query parameter. A full image CRN selects the pinned identity; use all_versions=true when looking through superseded builds. Protocol collections and resources without a UUID GET use their operation’s own retrieval contract.

​
Released CLI

CLI v0.13.0 accepts a reference for get on resources with a list and a get operation. Configure your profile and selected account as described in CLI; replace the example identities with your resources.
A bare subnet name without --vpc is refused with 400, name requires the resource's parent filter. A complete child CRN supplies its ancestry. Parent IDs that are positional arguments remain IDs; use the command’s --help for its scope flags. The reference getter does not change other verbs: delete, start and other ID-taking commands still need the returned ID. Relationship flags such as instance create --image have their own documented reference contracts.

​
Released Go SDK

Use github.com/basaltic-sh/sdk-go v0.15.0. Configure credentials, account and region through BASALTIC_ACCESS_KEY_ID, BASALTIC_SECRET_ACCESS_KEY, BASALTIC_ACCOUNT_ID and BASALTIC_REGION. This example reads the same instance by its three reference forms and reads a subnet with its VPC scope:
GetInstanceByReference and GetSubnetByReference call the UUID getter for a UUID and the exact collection filter for a name or CRN. No match is a not-found error; multiple matches produce AmbiguousReferenceError. Neither retries a different reference kind. The final scope argument may be nil when no parent or additional filter is needed. Use the returned ID with ordinary SDK methods such as GetInstance and StartInstance. The released clients have no database commands or database SDK package. Use the database page’s HTTP examples for those operations. Image relationship name:version tags are not generic getter names; use the image-list procedure above to select a build.