Environments
An app's environments, each with its own store. A deploy to an environment that doesn't exist yet creates it.
List
https://api.akter.dev/v1/organizations/{organization}/apps/{app}/environmentsList an app's environments in name order, a page at a time, with their status.
Path parameters
appstringrequiredAn app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
organizationstringrequiredAn organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
Query parameters
cursorstringThe nextCursor of the previous page.
limitintegerAt most this many items, 1 to 100. Defaults to 50.
Response 200EnvironmentPage
itemsEnvironment[]requireditems[].createdAtstringrequireditems[].fromEnvironmentOriginWhere a branched environment came from: the environment and its Ready snapshot whose data it started with.
items[].from.environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
items[].from.snapshotstringrequiredA named snapshot of an environment, such as before-migration, unique within the environment. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
items[].hostnamestringThe hostname an app's environment answers on over HTTPS, such as shop--prod--acme.akter.run. An environment keeps the hostname its first published deploy got.
items[].namestringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
items[].promotionPromotionMoving an app's hostname to an environment. The environment that served it is fenced first: its hosts give up their shards and it turns read-only. Then the hostname moves, and the promoted environment's held timers, outbox and jobs start.
items[].promotion.environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
items[].promotion.fencedstringThe environment that served the hostname before. It stays read-only, with its data, until deleted.
items[].promotion.hostnamestringThe hostname an app's environment answers on over HTTPS, such as shop--prod--acme.akter.run. An environment keeps the hostname its first published deploy got.
items[].promotion.missingWritesstringrequiredThe catch, stated for this promote: which writes the promoted environment does not have and where they stay.
items[].promotion.reasonstringWhy a Failed promote moved nothing.
items[].promotion.routestringrequiredThe environment whose hostname moves: the one a branch came from, or the environment itself when it is promoted back.
items[].promotion.status"Promoting" | "Promoted" | "Failed"requiredPromoting: the environment that served the hostname is being fenced, so nothing moved yet. Promoted: the hostname serves this environment. Failed: nothing moved; reason says why, and promoting again retries.
items[].quietbooleanTrue while its timers, outbox and jobs are held, not dropped: a branch until it is promoted, and an environment a promote fenced. Calls are still served.
items[].readOnlybooleanTrue once a promote moved its hostname to another environment: its store takes no writes and no builds, and keeps its data until deleted. Deploys to it go to the environment now serving its hostname, or are refused once none does. Promote it to move the hostname back.
items[].reasonstringWhy a Failed branch was not made.
items[].status"Branching" | "Ready" | "Failed" | "Retired"requiredBranching: its store is being made from a snapshot. Ready: deploys land on it, unless it is read-only. Failed: its branch was not made; reason says why, and it can only be deleted. Retired: it was deleted, so it serves nothing and takes no deploys; its data is kept but never reattached, and it keeps its name.
items[].storagestringSet on a branch: it lives on the disk of the environment it came from, which Archil measures once with its branches, so its storage is billed with that disk. A deleted branch's data stays on that disk, counting against the store's ceilings, until the disk is deleted.
nextCursorstringPass as cursor for the next page.
Errors
401UnauthorizedError403ForbiddenError404NotFoundError | FeatureNotEnabledError503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError
Create
https://api.akter.dev/v1/organizations/{organization}/apps/{app}/environmentsCreate an empty environment; its store is made by its first deploy. With from, branch it instead from a Ready snapshot of another environment: it starts Branching, then Ready with the snapshot's data and quiet (it serves calls on its own hostname, but its timers, outbox and jobs are held until it is promoted); branching needs the branch right. A name already in use fails with AlreadyExistsError, and one held by a retired environment with InUseError (environmentRetired); a snapshot that is not Ready fails with InUseError (snapshotNotReady).
Path parameters
appstringrequiredAn app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
organizationstringrequiredAn organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
Request bodyCreateEnvironment
fromEnvironmentOriginBranch the new environment from a Ready snapshot: it starts with the snapshot's data, quiet, until it is promoted.
from.environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
from.snapshotstringrequiredA named snapshot of an environment, such as before-migration, unique within the environment. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
namestringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
Response 201Environment
createdAtstringrequiredfromEnvironmentOriginWhere a branched environment came from: the environment and its Ready snapshot whose data it started with.
from.environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
from.snapshotstringrequiredA named snapshot of an environment, such as before-migration, unique within the environment. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
hostnamestringThe hostname an app's environment answers on over HTTPS, such as shop--prod--acme.akter.run. An environment keeps the hostname its first published deploy got.
namestringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
promotionPromotionMoving an app's hostname to an environment. The environment that served it is fenced first: its hosts give up their shards and it turns read-only. Then the hostname moves, and the promoted environment's held timers, outbox and jobs start.
promotion.environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
promotion.fencedstringThe environment that served the hostname before. It stays read-only, with its data, until deleted.
promotion.hostnamestringThe hostname an app's environment answers on over HTTPS, such as shop--prod--acme.akter.run. An environment keeps the hostname its first published deploy got.
promotion.missingWritesstringrequiredThe catch, stated for this promote: which writes the promoted environment does not have and where they stay.
promotion.reasonstringWhy a Failed promote moved nothing.
promotion.routestringrequiredThe environment whose hostname moves: the one a branch came from, or the environment itself when it is promoted back.
promotion.status"Promoting" | "Promoted" | "Failed"requiredPromoting: the environment that served the hostname is being fenced, so nothing moved yet. Promoted: the hostname serves this environment. Failed: nothing moved; reason says why, and promoting again retries.
quietbooleanTrue while its timers, outbox and jobs are held, not dropped: a branch until it is promoted, and an environment a promote fenced. Calls are still served.
readOnlybooleanTrue once a promote moved its hostname to another environment: its store takes no writes and no builds, and keeps its data until deleted. Deploys to it go to the environment now serving its hostname, or are refused once none does. Promote it to move the hostname back.
reasonstringWhy a Failed branch was not made.
status"Branching" | "Ready" | "Failed" | "Retired"requiredBranching: its store is being made from a snapshot. Ready: deploys land on it, unless it is read-only. Failed: its branch was not made; reason says why, and it can only be deleted. Retired: it was deleted, so it serves nothing and takes no deploys; its data is kept but never reattached, and it keeps its name.
storagestringSet on a branch: it lives on the disk of the environment it came from, which Archil measures once with its branches, so its storage is billed with that disk. A deleted branch's data stays on that disk, counting against the store's ceilings, until the disk is deleted.
Errors
401UnauthorizedError403ForbiddenError404NotFoundError | FeatureNotEnabledError409AlreadyExistsError | InUseError503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError
Get
https://api.akter.dev/v1/organizations/{organization}/apps/{app}/environments/{environment}Read one environment: its status and, once a deploy published, its hostname.
Path parameters
appstringrequiredAn app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
organizationstringrequiredAn organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
Response 200Environment
createdAtstringrequiredfromEnvironmentOriginWhere a branched environment came from: the environment and its Ready snapshot whose data it started with.
from.environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
from.snapshotstringrequiredA named snapshot of an environment, such as before-migration, unique within the environment. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
hostnamestringThe hostname an app's environment answers on over HTTPS, such as shop--prod--acme.akter.run. An environment keeps the hostname its first published deploy got.
namestringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
promotionPromotionMoving an app's hostname to an environment. The environment that served it is fenced first: its hosts give up their shards and it turns read-only. Then the hostname moves, and the promoted environment's held timers, outbox and jobs start.
promotion.environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
promotion.fencedstringThe environment that served the hostname before. It stays read-only, with its data, until deleted.
promotion.hostnamestringThe hostname an app's environment answers on over HTTPS, such as shop--prod--acme.akter.run. An environment keeps the hostname its first published deploy got.
promotion.missingWritesstringrequiredThe catch, stated for this promote: which writes the promoted environment does not have and where they stay.
promotion.reasonstringWhy a Failed promote moved nothing.
promotion.routestringrequiredThe environment whose hostname moves: the one a branch came from, or the environment itself when it is promoted back.
promotion.status"Promoting" | "Promoted" | "Failed"requiredPromoting: the environment that served the hostname is being fenced, so nothing moved yet. Promoted: the hostname serves this environment. Failed: nothing moved; reason says why, and promoting again retries.
quietbooleanTrue while its timers, outbox and jobs are held, not dropped: a branch until it is promoted, and an environment a promote fenced. Calls are still served.
readOnlybooleanTrue once a promote moved its hostname to another environment: its store takes no writes and no builds, and keeps its data until deleted. Deploys to it go to the environment now serving its hostname, or are refused once none does. Promote it to move the hostname back.
reasonstringWhy a Failed branch was not made.
status"Branching" | "Ready" | "Failed" | "Retired"requiredBranching: its store is being made from a snapshot. Ready: deploys land on it, unless it is read-only. Failed: its branch was not made; reason says why, and it can only be deleted. Retired: it was deleted, so it serves nothing and takes no deploys; its data is kept but never reattached, and it keeps its name.
storagestringSet on a branch: it lives on the disk of the environment it came from, which Archil measures once with its branches, so its storage is billed with that disk. A deleted branch's data stays on that disk, counting against the store's ceilings, until the disk is deleted.
Errors
401UnauthorizedError403ForbiddenError404NotFoundError | FeatureNotEnabledError503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError
Delete
https://api.akter.dev/v1/organizations/{organization}/apps/{app}/environments/{environment}Delete an environment: it stops serving, its hosts leave, and it is listed as Retired. Its data is kept but never reattached, and it keeps its name, so no new environment can take it. Fails while a domain points at it, while it serves another environment's hostname after a promote, and while it has branches that are not deleted (InUseError environmentHasBranches, naming them as branches). A deleted branch's storage is reclaimed only with the disk of the environment it came from, so it keeps counting and being billed until then. An API key needs a person's approval token in the akter-approval header.
Path parameters
appstringrequiredAn app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
organizationstringrequiredAn organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
Response 202Environment
createdAtstringrequiredfromEnvironmentOriginWhere a branched environment came from: the environment and its Ready snapshot whose data it started with.
from.environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
from.snapshotstringrequiredA named snapshot of an environment, such as before-migration, unique within the environment. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
hostnamestringThe hostname an app's environment answers on over HTTPS, such as shop--prod--acme.akter.run. An environment keeps the hostname its first published deploy got.
namestringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
promotionPromotionMoving an app's hostname to an environment. The environment that served it is fenced first: its hosts give up their shards and it turns read-only. Then the hostname moves, and the promoted environment's held timers, outbox and jobs start.
promotion.environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
promotion.fencedstringThe environment that served the hostname before. It stays read-only, with its data, until deleted.
promotion.hostnamestringThe hostname an app's environment answers on over HTTPS, such as shop--prod--acme.akter.run. An environment keeps the hostname its first published deploy got.
promotion.missingWritesstringrequiredThe catch, stated for this promote: which writes the promoted environment does not have and where they stay.
promotion.reasonstringWhy a Failed promote moved nothing.
promotion.routestringrequiredThe environment whose hostname moves: the one a branch came from, or the environment itself when it is promoted back.
promotion.status"Promoting" | "Promoted" | "Failed"requiredPromoting: the environment that served the hostname is being fenced, so nothing moved yet. Promoted: the hostname serves this environment. Failed: nothing moved; reason says why, and promoting again retries.
quietbooleanTrue while its timers, outbox and jobs are held, not dropped: a branch until it is promoted, and an environment a promote fenced. Calls are still served.
readOnlybooleanTrue once a promote moved its hostname to another environment: its store takes no writes and no builds, and keeps its data until deleted. Deploys to it go to the environment now serving its hostname, or are refused once none does. Promote it to move the hostname back.
reasonstringWhy a Failed branch was not made.
status"Branching" | "Ready" | "Failed" | "Retired"requiredBranching: its store is being made from a snapshot. Ready: deploys land on it, unless it is read-only. Failed: its branch was not made; reason says why, and it can only be deleted. Retired: it was deleted, so it serves nothing and takes no deploys; its data is kept but never reattached, and it keeps its name.
storagestringSet on a branch: it lives on the disk of the environment it came from, which Archil measures once with its branches, so its storage is billed with that disk. A deleted branch's data stays on that disk, counting against the store's ceilings, until the disk is deleted.
Errors
401UnauthorizedError403ForbiddenError404NotFoundError | FeatureNotEnabledError409InUseError428ConfirmationRequiredError503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError
Promote
https://api.akter.dev/v1/organizations/{organization}/apps/{app}/environments/{environment}/promoteWrites made after the snapshot are not in the promoted environment, and promoting an environment back drops the writes the environment it replaces took; both stay in the environment that gets fenced. Promote moves the app's hostname to this environment: the environment that served it is fenced first (its hosts give up their shards and it turns read-only, with its data, until deleted), then the hostname moves and this environment's held timers, outbox and jobs start. Deploys keep naming the environment whose hostname moved, and go to the environment now serving it; this environment takes no deploys by its own name while it serves another's hostname (InUseError environmentPromoted, naming that one as route). A branch takes the hostname of the environment it came from; promoting that environment back undoes it. It answers Promoting until the fence holds; asking again answers the same promotion, and missingWrites names what this promote leaves out. Needs the branch right; an API key needs a person's approval token in the akter-approval header.
Path parameters
appstringrequiredAn app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
organizationstringrequiredAn organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
Response 202Promotion
environmentstringrequiredAn environment of an app, such as prod or pr-42. Each environment has its own store. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.
fencedstringThe environment that served the hostname before. It stays read-only, with its data, until deleted.
hostnamestringThe hostname an app's environment answers on over HTTPS, such as shop--prod--acme.akter.run. An environment keeps the hostname its first published deploy got.
missingWritesstringrequiredThe catch, stated for this promote: which writes the promoted environment does not have and where they stay.
reasonstringWhy a Failed promote moved nothing.
routestringrequiredThe environment whose hostname moves: the one a branch came from, or the environment itself when it is promoted back.
status"Promoting" | "Promoted" | "Failed"requiredPromoting: the environment that served the hostname is being fenced, so nothing moved yet. Promoted: the hostname serves this environment. Failed: nothing moved; reason says why, and promoting again retries.
Errors
401UnauthorizedError403ForbiddenError404NotFoundError | FeatureNotEnabledError409InUseError428ConfirmationRequiredError503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError