Akter

Deploys

Deploys put a Ready build live in one of an app's environments.

List⁠

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

List an app's deploys, a page at a time.

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 200DeployPage

  • itemsDeploy[]required
  • items[].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.

  • items[].buildstringrequired

    An opaque id that starts with bld_.

  • items[].createdAtstringrequired
  • items[].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[].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[].idstringrequired

    An opaque id that starts with dep_.

  • items[].notices("Queued" | "Building" | "Rolling" | "Live" | "NotServing" | "RollingBack" | "RolledBack")[]required
  • items[].reasonobject | object | object | object | object | object

    Why a NotServing deploy isn't serving: the control plane never answered, no host, no host up, the app failed to load (the first line of its message, without paths or credentials, at most 1,024 characters), the environment already holds as many hosts as its ceiling allows and a new one waits for a release, or shards without a serving, published owner.

  • items[].rollbackReasonRollbackReason

    Why a RolledBack deploy rolled back: the build edits a migration the live build applied or another deploy held the environment, the build wasn't ready, its bytes didn't match its digest, it was built with an Akter release these hosts don't serve, the app's disk was unavailable, the app's disk or hostname changed under it, a link in the disk's .akter folder leads outside the disk, a newer deploy published first, or Akter failed to publish it. New codes may be added.

  • items[].rollbackReason.code"build-refused" | "build-not-ready" | "build-mismatch" | "build-unsupported" | "store-unavailable" | "target-changed" | "link-outside-disk" | "superseded" | "failed"required
  • items[].status"Queued" | "Building" | "Rolling" | "Live" | "NotServing" | "RollingBack" | "RolledBack"required

    Where the deploy is in its lifecycle. Live, NotServing and RolledBack are final. NotServing means the build was published but not every shard had a serving host within 15 minutes; a new deploy replaces it.

  • items[].urlstring

    https://<hostname>, where the app answers once this deploy has published its build.

  • 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}/deploys
deploys.createBearer token

Start deploying a Ready build to an environment. It answers at once; read the deploy until its status is Live, NotServing or RolledBack. Fails while another deploy of the environment is running. A deploy to an environment that doesn't exist yet creates it, and one to an environment being deleted fails with InUseError.

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 bodyCreateDeploy

  • buildstringrequired

    An opaque id that starts with bld_.

  • 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 202Deploy

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

  • buildstringrequired

    An opaque id that starts with bld_.

  • createdAtstringrequired
  • 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.

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

  • idstringrequired

    An opaque id that starts with dep_.

  • notices("Queued" | "Building" | "Rolling" | "Live" | "NotServing" | "RollingBack" | "RolledBack")[]required
  • reasonobject | object | object | object | object | object

    Why a NotServing deploy isn't serving: the control plane never answered, no host, no host up, the app failed to load (the first line of its message, without paths or credentials, at most 1,024 characters), the environment already holds as many hosts as its ceiling allows and a new one waits for a release, or shards without a serving, published owner.

  • rollbackReasonRollbackReason

    Why a RolledBack deploy rolled back: the build edits a migration the live build applied or another deploy held the environment, the build wasn't ready, its bytes didn't match its digest, it was built with an Akter release these hosts don't serve, the app's disk was unavailable, the app's disk or hostname changed under it, a link in the disk's .akter folder leads outside the disk, a newer deploy published first, or Akter failed to publish it. New codes may be added.

  • rollbackReason.code"build-refused" | "build-not-ready" | "build-mismatch" | "build-unsupported" | "store-unavailable" | "target-changed" | "link-outside-disk" | "superseded" | "failed"required
  • status"Queued" | "Building" | "Rolling" | "Live" | "NotServing" | "RollingBack" | "RolledBack"required

    Where the deploy is in its lifecycle. Live, NotServing and RolledBack are final. NotServing means the build was published but not every shard had a serving host within 15 minutes; a new deploy replaces it.

  • urlstring

    https://<hostname>, where the app answers once this deploy has published its build.

Errors

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

Get⁠

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

Read one deploy, with its status and the notices it has passed through.

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.

  • deploystringrequired

    An opaque id that starts with dep_.

Response 200Deploy

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

  • buildstringrequired

    An opaque id that starts with bld_.

  • createdAtstringrequired
  • 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.

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

  • idstringrequired

    An opaque id that starts with dep_.

  • notices("Queued" | "Building" | "Rolling" | "Live" | "NotServing" | "RollingBack" | "RolledBack")[]required
  • reasonobject | object | object | object | object | object

    Why a NotServing deploy isn't serving: the control plane never answered, no host, no host up, the app failed to load (the first line of its message, without paths or credentials, at most 1,024 characters), the environment already holds as many hosts as its ceiling allows and a new one waits for a release, or shards without a serving, published owner.

  • rollbackReasonRollbackReason

    Why a RolledBack deploy rolled back: the build edits a migration the live build applied or another deploy held the environment, the build wasn't ready, its bytes didn't match its digest, it was built with an Akter release these hosts don't serve, the app's disk was unavailable, the app's disk or hostname changed under it, a link in the disk's .akter folder leads outside the disk, a newer deploy published first, or Akter failed to publish it. New codes may be added.

  • rollbackReason.code"build-refused" | "build-not-ready" | "build-mismatch" | "build-unsupported" | "store-unavailable" | "target-changed" | "link-outside-disk" | "superseded" | "failed"required
  • status"Queued" | "Building" | "Rolling" | "Live" | "NotServing" | "RollingBack" | "RolledBack"required

    Where the deploy is in its lifecycle. Live, NotServing and RolledBack are final. NotServing means the build was published but not every shard had a serving host within 15 minutes; a new deploy replaces it.

  • urlstring

    https://<hostname>, where the app answers once this deploy has published its build.

Errors

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