Akter

Environments

An app's environments, each with its own store. A deploy to an environment that doesn't exist yet creates it.

List⁠

GEThttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/environments
environments.listBearer token

List an app's environments in name order, a page at a time, with their status.

Path parameters

  • appstringrequired

    An 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.

  • organizationstringrequired

    An 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

  • cursorstring

    The nextCursor of the previous page.

  • limitinteger

    At most this many items, 1 to 100. Defaults to 50.

Response 200EnvironmentPage

  • itemsEnvironment[]required
  • items[].createdAtstringrequired
  • items[].fromEnvironmentOrigin

    Where a branched environment came from: the environment and its Ready snapshot whose data it started with.

  • items[].from.environmentstringrequired

    An 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.snapshotstringrequired

    A 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[].hostnamestring

    The 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[].namestringrequired

    An 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[].promotionPromotion

    Moving 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.environmentstringrequired

    An 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.fencedstring

    The environment that served the hostname before. It stays read-only, with its data, until deleted.

  • items[].promotion.hostnamestring

    The 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.missingWritesstringrequired

    The catch, stated for this promote: which writes the promoted environment does not have and where they stay.

  • items[].promotion.reasonstring

    Why a Failed promote moved nothing.

  • items[].promotion.routestringrequired

    The 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"required

    Promoting: 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[].quietboolean

    True 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[].readOnlyboolean

    True 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[].reasonstring

    Why a Failed branch was not made.

  • items[].status"Branching" | "Ready" | "Failed" | "Retired"required

    Branching: 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[].storagestring

    Set 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.

  • nextCursorstring

    Pass as cursor for the next page.

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Create⁠

POSThttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/environments
environments.createBearer token

Create 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

  • appstringrequired

    An 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.

  • organizationstringrequired

    An 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

  • fromEnvironmentOrigin

    Branch the new environment from a Ready snapshot: it starts with the snapshot's data, quiet, until it is promoted.

  • from.environmentstringrequired

    An 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.snapshotstringrequired

    A 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.

  • namestringrequired

    An 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

  • createdAtstringrequired
  • fromEnvironmentOrigin

    Where a branched environment came from: the environment and its Ready snapshot whose data it started with.

  • from.environmentstringrequired

    An 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.snapshotstringrequired

    A 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.

  • hostnamestring

    The 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.

  • namestringrequired

    An 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.

  • promotionPromotion

    Moving 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.environmentstringrequired

    An 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.fencedstring

    The environment that served the hostname before. It stays read-only, with its data, until deleted.

  • promotion.hostnamestring

    The 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.missingWritesstringrequired

    The catch, stated for this promote: which writes the promoted environment does not have and where they stay.

  • promotion.reasonstring

    Why a Failed promote moved nothing.

  • promotion.routestringrequired

    The environment whose hostname moves: the one a branch came from, or the environment itself when it is promoted back.

  • promotion.status"Promoting" | "Promoted" | "Failed"required

    Promoting: 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.

  • quietboolean

    True 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.

  • readOnlyboolean

    True 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.

  • reasonstring

    Why a Failed branch was not made.

  • status"Branching" | "Ready" | "Failed" | "Retired"required

    Branching: 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.

  • storagestring

    Set 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

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 409AlreadyExistsError | InUseError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Get⁠

GEThttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/environments/{environment}
environments.getBearer token

Read one environment: its status and, once a deploy published, its hostname.

Path parameters

  • appstringrequired

    An 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.

  • organizationstringrequired

    An 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.

  • environmentstringrequired

    An 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

  • createdAtstringrequired
  • fromEnvironmentOrigin

    Where a branched environment came from: the environment and its Ready snapshot whose data it started with.

  • from.environmentstringrequired

    An 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.snapshotstringrequired

    A 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.

  • hostnamestring

    The 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.

  • namestringrequired

    An 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.

  • promotionPromotion

    Moving 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.environmentstringrequired

    An 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.fencedstring

    The environment that served the hostname before. It stays read-only, with its data, until deleted.

  • promotion.hostnamestring

    The 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.missingWritesstringrequired

    The catch, stated for this promote: which writes the promoted environment does not have and where they stay.

  • promotion.reasonstring

    Why a Failed promote moved nothing.

  • promotion.routestringrequired

    The environment whose hostname moves: the one a branch came from, or the environment itself when it is promoted back.

  • promotion.status"Promoting" | "Promoted" | "Failed"required

    Promoting: 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.

  • quietboolean

    True 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.

  • readOnlyboolean

    True 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.

  • reasonstring

    Why a Failed branch was not made.

  • status"Branching" | "Ready" | "Failed" | "Retired"required

    Branching: 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.

  • storagestring

    Set 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

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Delete⁠

DELETEhttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/environments/{environment}
environments.deleteBearer token

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

  • appstringrequired

    An 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.

  • organizationstringrequired

    An 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.

  • environmentstringrequired

    An 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

  • createdAtstringrequired
  • fromEnvironmentOrigin

    Where a branched environment came from: the environment and its Ready snapshot whose data it started with.

  • from.environmentstringrequired

    An 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.snapshotstringrequired

    A 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.

  • hostnamestring

    The 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.

  • namestringrequired

    An 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.

  • promotionPromotion

    Moving 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.environmentstringrequired

    An 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.fencedstring

    The environment that served the hostname before. It stays read-only, with its data, until deleted.

  • promotion.hostnamestring

    The 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.missingWritesstringrequired

    The catch, stated for this promote: which writes the promoted environment does not have and where they stay.

  • promotion.reasonstring

    Why a Failed promote moved nothing.

  • promotion.routestringrequired

    The environment whose hostname moves: the one a branch came from, or the environment itself when it is promoted back.

  • promotion.status"Promoting" | "Promoted" | "Failed"required

    Promoting: 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.

  • quietboolean

    True 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.

  • readOnlyboolean

    True 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.

  • reasonstring

    Why a Failed branch was not made.

  • status"Branching" | "Ready" | "Failed" | "Retired"required

    Branching: 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.

  • storagestring

    Set 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

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 409InUseError
  • 428ConfirmationRequiredError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Promote⁠

POSThttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/environments/{environment}/promote
environments.promoteBearer tokenSafe to retryAsks a person to confirm

Writes 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

  • appstringrequired

    An 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.

  • organizationstringrequired

    An 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.

  • environmentstringrequired

    An 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

  • environmentstringrequired

    An 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.

  • fencedstring

    The environment that served the hostname before. It stays read-only, with its data, until deleted.

  • hostnamestring

    The 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.

  • missingWritesstringrequired

    The catch, stated for this promote: which writes the promoted environment does not have and where they stay.

  • reasonstring

    Why a Failed promote moved nothing.

  • routestringrequired

    The environment whose hostname moves: the one a branch came from, or the environment itself when it is promoted back.

  • status"Promoting" | "Promoted" | "Failed"required

    Promoting: 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

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 409InUseError
  • 428ConfirmationRequiredError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError