Acquiring an environment

Acquiring an environment applies some of your organization's tokens to it and gives the whole organization a year of access to every tag it has. Any member may acquire; there is no approval step. Access ends a year from the day it was acquired, and the environment can be acquired again once it has.

The price is in tokens and depends on the environment's type, the badge beside its name in the catalog. One price list applies to every organization, and the environment's own page shows the price before you commit to it.

From the catalog

Open the environment from the catalog. If your organization does not hold it yet, a card near the top of the page shows the price, how many tokens are available, and when the next of them lapse.

The Acquire control opens a confirmation: "Apply N of your organization's tokens for a year of access?" Nothing is applied until you press Confirm. Afterwards the page says the environment is acquired, the card shows an Access badge with the date access runs to, and the Pull it card below gives the command to run next. Back in the catalog list, each card your organization can pull carries the same Access badge.

If a request cannot be met, no tokens are applied and the page says why.

The page says	Why
Your organization already has access.	A live grant exists for this environment, whether from staff, a bundle, or an earlier acquisition.
Your organization does not have enough tokens available.	The price is more than what is available. See Tokens.
This environment has no price yet.	The current price list does not cover its type. It cannot be acquired until it does.
Your organization is suspended.	Nothing can be acquired while it is.

An environment your organization already holds, however it came to hold it, shows the Access badge and the date access runs to instead of a price.

From the API

The same action is available to scripts. It authenticates with a registry key, the regk_ key you docker login with, and acts for the organization that key belongs to. The host is the one this documentation is served from, not the registry host.

curl -X POST https://<host>/api/v1/acquisitions \
  -H "Authorization: Bearer $SAVANTENVS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"slug": "<environment-name>"}'

A successful acquisition answers 201 with the tokens applied, what is available afterwards, and when access ends:

{"ok": true, "cost": 4, "available": 36, "expiresAt": "2027-10-13T15:02:11.000Z"}

Repeating the request is safe. The second answers 409 with already_have_access and applies nothing, so a retry after a dropped connection cannot apply tokens twice.

Status	Body	Meaning
`201`	`{"ok": true, …}`	Acquired.
`409`	`{"ok": false, "reason": "already_have_access"}`	A live grant already exists.
`409`	`{"ok": false, "reason": "insufficient_tokens"}`	Not enough tokens available.
`409`	`{"ok": false, "reason": "unpriced"}`	No price for this environment's type yet.
`409`	`{"ok": false, "reason": "suspended"}`	The organization is suspended.
`404`	`{"ok": false, "reason": "not_found"}`	No environment by that name, or none you may acquire. The two are deliberately the same answer.
`401`	`{"error": "…"}`	The key is missing, wrong, revoked or expired.
`400`	`{"error": "slug is required"}`	The body had no `slug`.
`415`	`{"error": "…"}`	The body was not sent as `application/json`.

An acquisition made this way appears in the organization's token activity like any other, and the environment shows as held in the catalog from then on.

What acquiring does not change

Which tags you may pull is still decided by the registry, as Tags and entitlements describes; an acquired environment holds the pattern that matches every tag. Pulling costs no tokens, and a key issued before the acquisition pulls the new environment without being reissued.