@keboola/api-client 35.0.0 → 36.0.0

package/dist/{types-CBgLCkYe.d.ts → types-D6UmMa6E.d.ts}

@@ -36,30 +36,14 @@ type paths = {
     };
     /**
      * List apps
-     * @description Lists apps for the project, each including `production {desiredNumber, desiredId,
-     *     actualNumber, actualId}` and `undeployedChanges` (whether the production
-     *     deployment's config version differs from the app's current config version — a
-     *     future branch-HEAD comparison is not implemented yet).
+     * @description Lists apps for the project.
      */
     get: operations['listApps'];
     put?: never;
     /**
      * Create app
-     * @description Creates the app row plus its AppGroup CR (the product's Kubernetes object); the
-     *     app starts with `production: null` — its URL is reserved but publicly 404s until
-     *     a deployment is promoted. An optional `Idempotency-Key` header makes a retried
-     *     create return the same app instead of a duplicate Storage config, DB row, and
-     *     App CRD — `201` only on the request that actually created it, `200` on every
-     *     replay, so the status code alone tells a caller which happened without diffing
-     *     the body. A retry with no `Idempotency-Key` is always a genuine create (`201`):
-     *     nothing links it to the earlier request.
-     *
-     *     The Storage config this creates has no app content and only the platform's
-     *     default auth (`authorization.app_proxy` requiring a password nobody has set
-     *     yet, so the URL stays unopenable) — this endpoint reserves the app and its
-     *     config address, nothing more. Set `parameters` (what the app runs) and
-     *     `authorization.app_proxy` (who can open it) via the Storage API, on the config
-     *     named by the response's `componentId`/`branchId`/`configId`, before deploying.
+     * @description Creates the app. Production starts empty — the URL is reserved but publicly 404s
+     *     until a deployment is promoted.
      */
     post: operations['createApp'];
     delete?: never;
@@ -77,33 +61,19 @@ type paths = {
     };
     /**
      * Get app detail
-     * @description Same shape as the list entry, incl. `production {desiredNumber, desiredId,
-     *     actualNumber, actualId}` and `undeployedChanges`.
+     * @description Same shape as the list entry.
      */
     get: operations['getApp'];
     put?: never;
     post?: never;
     /**
      * Delete app
-     * @description Deletes the AppGroup CR, cascading to every deployment, Secret and pod owned by
-     *     it; rows are soft-deleted.
+     * @description Deletes the app and all its deployments.
      */
     delete: operations['deleteApp'];
     options?: never;
     head?: never;
-    /**
-     * Update app settings
-     * @description Updates plain product settings. Per the `/v2` design rule (see API description),
-     *     operations with side effects beyond a plain attribute write — promote, unpublish,
-     *     suspend, resume — are separate action-verb endpoints, not part of this `PATCH`.
-     *
-     *     No patchable field exists yet: `name` and `description` are create-only (see
-     *     `AppCreateRequest`) and live in the app's Storage configuration, not on the App
-     *     row, so there is nothing here to rename them into. Sending either is rejected as
-     *     an unknown field (`422`), not silently accepted — the only currently valid body is
-     *     `{}`. Additional fields will land here as the `/v2` surface grows.
-     */
-    patch: operations['patchApp'];
+    patch?: never;
     trace?: never;
   };
   '/apps/{appId}/unpublish': {
@@ -117,11 +87,8 @@ type paths = {
     put?: never;
     /**
      * Unpublish app
-     * @description Sets `production` to none — routing is dropped and the app's URL 404s.
-     *     Idempotent: unpublishing an already-unpublished app is a no-op, and so is
-     *     unpublishing an app that has no App CRD at all (never deployed via `/v2`) — from a
-     *     caller's perspective "no App CRD" and "an App CRD with nothing published" are the
-     *     same fact, so both return `204` rather than one of them 409ing.
+     * @description Sets `production` to none — routing is dropped and the app's URL 404s. The app won't automatically wake up
+     *     in incoming traffic until other Deployment is promoted.
      */
     post: operations['unpublishApp'];
     delete?: never;
@@ -142,12 +109,12 @@ type paths = {
     /**
      * Suspend app
      * @description Sleeps the app's currently serving member now, instead of waiting for the idle
-     *     timer, and disarms wake-on-request: unlike idle auto-suspend, a visitor hitting
-     *     the app's URL afterwards gets a 503 rather than triggering a wakeup. Stays
-     *     suspended until an explicit `resume`. Idempotent: suspending an already-suspended
-     *     app is a no-op; returns `409` if the app has no serving member to suspend.
+     *     timer. Wake-on-request stays armed: a visitor hitting the app's URL afterwards
+     *     wakes it, exactly as after an idle auto-suspend. Idempotent: suspending an
+     *     already-suspended app is a no-op; returns `409` if the app has no serving member
+     *     to suspend.
      *
-     *     The returned App's `state` becomes `SUSPENDED` — immediately, not on the next
+     *     The returned App's `state` becomes `suspended` — immediately, not on the next
      *     list/get poll.
      */
     post: operations['suspendApp'];
@@ -173,9 +140,9 @@ type paths = {
      *     resuming an already-running app is a no-op; returns `409` if the app has no
      *     serving member to resume.
      *
-     *     The returned App's `state` is `STARTING` immediately after resuming an app that
+     *     The returned App's `state` is `starting` immediately after resuming an app that
      *     was actually stopped — the operator has not confirmed the member serving yet at
-     *     the instant this call returns — settling to `RUNNING` once it does.
+     *     the instant this call returns — settling to `running` once it does.
      */
     post: operations['resumeApp'];
     delete?: never;
@@ -204,8 +171,9 @@ type paths = {
      *     `apps:proxy` scope (or an equivalent ServiceAccount token). A Storage API token is
      *     not accepted here, unlike `PATCH /apps/{appId}`.
      *
-     *     Idempotent by nature: re-reporting the same or an older timestamp has no side effect
-     *     beyond overwriting the stored value, so no `Idempotency-Key` is needed.
+     *     Monotonic: a timestamp older than the one already stored is ignored rather than applied,
+     *     so an out-of-order or retried call can never move the heartbeat backwards and make an
+     *     active app read as idle sooner than it really is.
      */
     post: operations['recordAppActivity'];
     delete?: never;
@@ -224,9 +192,9 @@ type paths = {
     /**
      * Get app password
      * @description Returns the app's current password for its `password`-type auth provider. `null`
-     *     if none has been minted yet — that happens on the app's first deployment (see
-     *     `POST .../deployments`) or on demand via `POST .../reset-password`. Mirrors
-     *     `/v1`'s `GET /apps/{appId}/password`.
+     *     if none has been minted yet. A non-null value does not mean the app currently uses
+     *     password auth — it can outlive a later switch away from it. Do not use its presence
+     *     or absence to infer the app's current auth configuration.
      */
     get: operations['getAppPassword'];
     put?: never;
@@ -237,7 +205,7 @@ type paths = {
     patch?: never;
     trace?: never;
   };
-  '/apps/{appId}/reset-password': {
+  '/apps/{appId}/password/reset': {
     parameters: {
       query?: never;
       header?: never;
@@ -248,11 +216,8 @@ type paths = {
     put?: never;
     /**
      * Reset app password
-     * @description Mints a new password, replacing any existing one. Not idempotent by design: the
-     *     minted value is unpredictable, so there is no target state a retry could
-     *     re-declare — each call always generates a fresh secret. `400` if the app's config
-     *     has no `password`-type auth provider (nothing to reset). The new password is not
-     *     returned here; fetch it with `GET .../password` immediately after.
+     * @description Mints a new password, replacing any existing one, and returns it. Each call always
+     *     generates a fresh secret.
      */
     post: operations['resetAppPassword'];
     delete?: never;
@@ -270,20 +235,16 @@ type paths = {
     };
     /**
      * List runs
-     * @description Runs of this app, newest first — app-wide, mirroring `/v1`'s paths. The rollup is
-     *     what you want when something is wrong and you do not yet know which deployment to
-     *     look at; each run carries its own `deploymentId`, and `deploymentId=` narrows the
-     *     list once you do.
+     * @description Runs of this app, newest first, across every deployment.
      *
      *     This is where a failed deployment's cause lives: a run carries `failureReason` and
-     *     `startupLogs`. A deployment reported `FAILED` has an explanation here. One reported
-     *     `PENDING` does not, and that is not an omission — nothing upstream records a cause
+     *     `startupLogs`. A deployment reported `failed` has an explanation here. One reported
+     *     `pending` does not, and that is not an omission — nothing upstream records a cause
      *     for a container that never executed.
      *
      *     `since`/`until` filter on `createdAt`, not `startedAt`: `createdAt` is stamped
      *     before any compute exists, so it is the only timestamp every run has, including one
-     *     that never started. Filtering on `startedAt` would silently drop exactly the runs
-     *     this endpoint exists to explain. `offset`/`limit` page through the filtered window,
+     *     that never started. `offset`/`limit` page through the filtered window,
      *     not the full history — pass `since`/`until` and page until the response is shorter
      *     than `limit` to know you have the whole window, rather than an arbitrary slice of a
      *     larger, unbounded one.
@@ -306,7 +267,7 @@ type paths = {
     };
     /**
      * Get run detail
-     * @description A single run. Addressed under the app rather than under its deployment, matching `/v1`: a run id is unique on its own, so nesting it would add a path segment carrying no information and force a caller holding an id from the app-wide list to find its deployment first.
+     * @description A single run detail.
      */
     get: operations['getRun'];
     put?: never;
@@ -326,33 +287,18 @@ type paths = {
     };
     /**
      * List deployments
-     * @description Full deployment history including retired (`archived: true`) deployments —
-     *     rows outlive their Kubernetes CRs.
+     * @description Deployment history. Returns only live deployments by default — set
+     *     `archived=true` to list deleted ones instead. A deleted deployment can no
+     *     longer run or be promoted, but stays listed here.
      */
     get: operations['listDeployments'];
     put?: never;
     /**
      * Create deployment (deploy)
-     * @description Deploys the current config version / branch HEAD as a new immutable deployment.
-     *     `promote: true` by default — deploying also promotes to production unless
-     *     explicitly disabled, in which case the deployment is staged for a later
-     *     promotion and never runs in the meantime. The deployment id is minted synchronously (deterministic
-     *     Kubernetes CR name); the display `number` is allocated from a per-app DB
-     *     sequence, also returned synchronously — an optional `Idempotency-Key` header
-     *     makes a retried deploy return the same row instead of a duplicate: `202` only on
-     *     the request that actually created it, `200` on every replay. A request with no
-     *     `Idempotency-Key` is always a genuine deploy (`202`): nothing links it to an
-     *     earlier request, so it can never be recognised as a replay.
-     *
-     *     Nothing here validates app content: a config with no `parameters` builds
-     *     (`buildState: PREBUILT`) and promotes successfully, then crashes on every run.
-     *     Content lives in the Storage config named by the app's `componentId`/
-     *     `branchId`/`configId`, set via the Storage API — not this request.
-     *
-     *     If the app's config has a `password`-type auth provider and the app has no
-     *     password yet, this call mints one — the same lazy, one-time generation `/v1`
-     *     does when an app with simple auth is first started. Fetch it with
-     *     `GET .../password`; a later deployment never rotates it.
+     * @description Deploys the current config version / branch HEAD as a new immutable deployment,
+     *     or a specific past version via `configVersion`. `promote: true` by default —
+     *     deploying also promotes to production unless explicitly disabled, in which case
+     *     the deployment is staged for a later promotion and never runs in the meantime.
      */
     post: operations['createDeployment'];
     delete?: never;
@@ -370,27 +316,19 @@ type paths = {
     };
     /**
      * Get deployment detail
-     * @description Deployment detail; served from the DB projection. The row is written
-     *     synchronously before the create request returns, so there is no window
-     *     where it is missing (read-your-writes) and no Kubernetes CR fallback.
+     * @description Deployment detail.
      */
     get: operations['getDeployment'];
     put?: never;
     post?: never;
     /**
-     * Retire deployment
-     * @description **Retires, does not erase** — deletes the member CR and its rendered-config
-     *     Secret immediately (credential hygiene); the row stays in history marked
-     *     `archived: true` and is re-materializable. Deployments have no `PATCH`/`PUT` —
-     *     they are immutable; retirement is a lifecycle transition, not a mutation. `409`
-     *     if this deployment's id is named production by either `production.desiredId` or
-     *     `production.actualId` on the app (promote or roll back to another deployment, or
-     *     unpublish, before retiring it) — a promotion in flight can leave those two
-     *     different for a while, and retiring the one not currently named `desiredId` is
-     *     just as unsafe as retiring the one not currently named `actualId`, since either
-     *     one is still something the app depends on. Idempotent: retiring an already
-     *     `archived` deployment is a no-op. Row hard-deletion happens only via app
-     *     deletion.
+     * Delete deployment
+     * @description **Deletes, does not erase** — stops the deployment; it stays in history marked `archived: true` and can
+     *     still be listed, but can no longer be promoted.
+     *
+     *     Deployment can't be deleted when it acts as the current app production deployment
+     *     (`production.desiredDeploymentId` or `production.actualDeploymentId`). Promote or roll back to another
+     *     deployment, or unpublish, before deleting it.
      */
     delete: operations['deleteDeployment'];
     options?: never;
@@ -410,27 +348,20 @@ type paths = {
     /**
      * Promote deployment (promote / rollback)
      * @description Makes this deployment production. Rollback is the same action applied to an
-     *     older deployment — every repoint is audited. Promoting an `archived` deployment
-     *     is allowed (it is re-materialized first).
-     *
-     *     Promotion is **declarative**: this records the intent and returns. The operator
-     *     validates by starting the target deployment — including when the app is
-     *     suspended — and switches the route only once that deployment is serving. A
-     *     target that fails to start never becomes production, and the deployment that was
-     *     already serving keeps serving. There is deliberately no readiness precondition:
-     *     a deployment cannot become ready until it has been asked to be production.
+     *     older deployment. `409` if the deployment has been deleted (`archived: true`)
+     *     — deploy it again to get a new, promotable deployment.
      *
-     *     Idempotent: re-declaring the deployment that is already production is a no-op.
-     *     Authorized separately from plain app settings.
+     *     There is deliberately **no readiness precondition**: a deployment only becomes
+     *     ready by being promoted — nothing runs it before that — so requiring readiness
+     *     first would be circular. Promotion records the intent and returns; the
+     *     platform then validates it by starting the target, even when the app is
+     *     suspended. On success the app is left running: promoting a suspended app
+     *     resumes it. If that fails, the app is left `PromotionBlocked` and production
+     *     keeps serving what it was already serving.
      *
-     *     `runState`/`buildState` are not inputs to this decision — a `FAILED`,
-     *     non-archived deployment is promoted exactly like any other non-archived one, by
-     *     whether it is already production, not by why it stopped running. Re-declaring it
-     *     while it is still `production.desired`/`.actual` is the no-op above (`204`).
-     *     Re-declaring it while it is **not** currently production — rolled back away from,
-     *     or never promoted — repoints `production.desired` (`202`) and the operator starts
-     *     it, which from the outside looks like restarting a failed deployment; it is the
-     *     same repoint any not-yet-run deployment gets, not special-cased recovery.
+     *     Safe to retry: re-declaring the deployment that is already production always returns
+     *     `202`, whether or not anything actually changed — it also always ensures the app is
+     *     running, so re-declaring the current deployment on a suspended app resumes it.
      */
     post: operations['promoteDeployment'];
     delete?: never;
@@ -448,16 +379,10 @@ type paths = {
     };
     /**
      * Tail app logs
-     * @description Streams recent container output of the app's currently serving member — the same
-     *     member `promote` most recently switched traffic to, resolved by the operator from
-     *     the App CRD's serving pointer, not looked up by this service. Mirrors `/v1`'s
-     *     `GET /apps/{appId}/logs/tail`.
+     * @description Streams recent container output of the app's currently serving deployment.
      *
      *     `since` and `lines` are mutually exclusive filters on where the tail starts;
-     *     omitting both returns the log from its start. `404` if the app has no App CRD at
-     *     all (never deployed via `/v2`); `400` (`apps.appNotRunning`) if it has one but
-     *     nothing is currently serving — both are "there is nothing to tail right now",
-     *     distinguished only by whether the app was ever deployed.
+     *     omitting both returns the log from its start.
      */
     get: operations['tailAppLogs'];
     put?: never;
@@ -477,10 +402,8 @@ type paths = {
     };
     /**
      * Download app logs
-     * @description The full container output of the app's currently serving member, as a file
-     *     download. Same underlying call as `tail` with neither `since` nor `lines` set —
-     *     no separate retention or size limit applies. Mirrors `/v1`'s
-     *     `GET /apps/{appId}/logs/download`.
+     * @description The full container output of the app's currently serving deployment, as a file
+     *     download.
      */
     get: operations['downloadAppLogs'];
     put?: never;
@@ -500,17 +423,10 @@ type paths = {
     };
     /**
      * Tail deployment logs
-     * @description Streams recent container output of this specific deployment's own member — not
-     *     resolved through the app's serving pointer, so this works for a deployment that
-     *     is not (or never was) production, e.g. a candidate that failed to promote. The
-     *     operator streams directly from the deployment's Sandbox CR, which is named after
-     *     the deployment id.
+     * @description Streams recent container output of this specific deployment.
      *
      *     `since` and `lines` are mutually exclusive filters on where the tail starts;
-     *     omitting both returns the log from its start. `404` if the app or the deployment
-     *     doesn't exist (or the deployment belongs to a different app); `400`
-     *     (`apps.deploymentNotRunning`) if the deployment exists but has nothing currently
-     *     running to read logs from.
+     *     omitting both returns the log from its start.
      */
     get: operations['tailDeploymentLogs'];
     put?: never;
@@ -530,9 +446,7 @@ type paths = {
     };
     /**
      * Download deployment logs
-     * @description The full container output of this specific deployment's own member, as a file
-     *     download — same underlying call as `tail` with neither `since` nor `lines` set.
-     *     Not resolved through the app's serving pointer; see `tail` for why that matters.
+     * @description The full container output of this specific deployment, as a file download.
      */
     get: operations['downloadDeploymentLogs'];
     put?: never;
@@ -554,10 +468,9 @@ type paths = {
      * Get app's Git repository
      * @description Returns details of the Git repository configured in the app's config
      *     (`parameters.dataApp.git`). For a managed Git repository both `sshUrl` and
-     *     `httpsUrl` are returned, fetched from the upstream git-service. For an
-     *     externally configured repository only the URL matching the configured protocol
-     *     is returned and the other field is `null`; any embedded credentials are
-     *     stripped.
+     *     `httpsUrl` are returned. For an externally configured repository only the URL
+     *     matching the configured protocol is returned and the other field is `null`;
+     *     any embedded credentials are stripped.
      */
     get: operations['getAppGitRepo'];
     put?: never;
@@ -586,11 +499,8 @@ type paths = {
      * Create credential for the app's managed Git repository
      * @description Creates a credential (SSH key or HTTP token) for the app's managed Git
      *     repository. For `http_token` credentials, the response includes a one-time
-     *     `secret` that is never returned again — not on subsequent reads, and not on an
-     *     `Idempotency-Key` replay of this request. Requires an admin Storage API token.
-     *     An optional `Idempotency-Key` header makes a retried create return the existing
-     *     credential instead of a duplicate: `201` only on the request that actually
-     *     created it, `200` on every replay.
+     *     `secret` that is never returned again — not on subsequent reads. Requires an
+     *     admin Storage API token.
      */
     post: operations['createAppGitRepoCredential'];
     delete?: never;
@@ -617,8 +527,7 @@ type paths = {
     post?: never;
     /**
      * Revoke and remove a credential
-     * @description Revokes a credential on git-service and soft-deletes the local row. Tolerates
-     *     git-service `404` as already-removed. Requires an admin Storage API token.
+     * @description Revokes the credential. Requires an admin Storage API token.
      */
     delete: operations['deleteAppGitRepoCredential'];
     options?: never;
@@ -629,120 +538,78 @@ type paths = {
 };
 type components = {
   schemas: {
-    /** @description Flat error shape used by every v2 endpoint, matching the v1 convention (e.g. 404 → `{"error": "App \"123\" not found"}`). */
+    /** @description Flat error shape used by every `/v2` endpoint, e.g. `{"error": "App \"123\" not found"}`. */
     ErrorResponse: {
       error?: string;
     };
     App: {
       id: string;
       projectId: string;
-      /**
-       * @description Together with `branchId` and `configId`, the Storage address of this app's configuration. The app's **name** and **description** — both set once at creation via `AppCreateRequest` and never editable afterwards — live there and are deliberately not copied onto this response — pointing at where they authoritatively live keeps them correct by construction. Resolve labels for a page of apps with one bulk `listComponentConfigurations` call.
-       *     The app's **content** (`parameters` — what it runs) and **auth** (`authorization.app_proxy` — who can open it) live there too, for the same reason: `/v2` manages apps and deployments, not their configuration. A newly created app's config has neither — no content, and an auth block that requires a password nobody has set — until configured via the Storage API.
-       */
+      /** @description Together with `branchId` and `configId`, addresses the app's Storage configuration, which holds its name, description, content (`parameters`) and auth (`authorization.app_proxy`). */
       componentId: string;
-      /** @description `null` on an app created through `/v1` without a branch. Apps created through `/v2` always resolve the project's default branch at creation, so this is never null for them. */
+      /** @description The dev branch this app's Storage configuration lives in. */
       branchId: string | null;
       configId: string;
-      /** @description The app's current configuration revision. */
-      configVersion: string;
       /** @enum {string|null} */
       type?: 'streamlit' | 'python-js' | null;
-      /**
-       * @description Apps created through `/v2` are always `prod`; `dev` occurs only on an app created through `/v1` in dev mode and later adopted.
-       * @enum {string}
-       */
-      mode?: 'prod' | 'dev';
       /**
        * Format: url
-       * @description Production URL — stable, unchanged by promote/rollback.
-       *     Mirrored from the operator, which derives the address and publishes it on the App resource; it is not computed here, so it cannot disagree with where the app actually answers. `null` only in the window between creating an app and the first state-sync pass picking the address up, so a freshly created app can report `null` here for a short time.
-       *     Null does not mean "not deployed" — check `production` for that. A URL is reserved from creation and 404s publicly until something is promoted to it.
+       * @description Production URL — stable, unchanged by promote/rollback. May briefly be `null` right after creation. Does not mean "not deployed" — check `production` for that; the URL is reserved from creation and 404s publicly until something is promoted to it.
        */
       url: string | null;
-      /**
-       * @description Always present. `null` on all four fields means the app has never been deployed (URL reserved, publicly 404s). Carries both the display number and the id for each of `desired`/`actual` because `promote`/`retire` take a deployment id, not a number — a client holding only the number would have to fetch the deployment list just to find the id it needs to act.
-       *     `desired` and `actual` differ while a promotion is in flight — the operator only moves `actual` once the newly desired deployment reports ready — and this is the supported way to detect that in progress, independently of `state`, which deliberately does not encode it. See `App.state`'s own description.
-       */
+      /** @description Always present. `null` on both fields means the app has never been deployed (URL reserved, publicly 404s). The two fields differ while a promotion is in progress — see `App.state` for how to read that alongside it. */
       production: {
-        /** @description Deployment number most recently asked to be production. */
-        desiredNumber?: number | null;
-        /** @description Id of the deployment most recently asked to be production — pass this to `promote`/`retire`, not `desiredNumber`. */
-        desiredId?: string | null;
-        /** @description Deployment number actually serving production traffic right now, per the AppGroup controller's convergence status. */
-        actualNumber?: number | null;
-        /** @description Id of the deployment actually serving production traffic right now — pass this to `promote`/`retire`, not `actualNumber`. */
-        actualId?: string | null;
-      };
-      /** @description Whether the production deployment's config version differs from the app's current config version. A future branch-HEAD comparison is not implemented yet. */
-      undeployedChanges?: boolean;
+        /** @description Id of the deployment most recently asked to be production — pass this to `promote`, or delete it instead. */
+        desiredDeploymentId?: string | null;
+        /** @description Id of the deployment actually serving production traffic right now. */
+        actualDeploymentId?: string | null;
+      };
       /**
-       * @description Is this app's production currently serving traffic, and if not, why? Answers
-       *     exactly that one question — not "is my code healthy" (that's a deployment's
-       *     own `runState`, which can be `FAILED` while this stays `RUNNING`, because an
-       *     older, still-serving deployment and the newest built one are different
-       *     things at the same instant) and not "will a request wake it" alone (both
-       *     `SLEEPING` and `SUSPENDED` are stopped; only the label tells you which).
+       * @description Whether this app's production is currently serving traffic, and if not, why.
+       *     Does not encode rollout progress: a promotion can be in flight while this
+       *     stays `running`, or while it is `notDeployed`. Compare `production`'s
+       *     `desiredDeploymentId` against `actualDeploymentId` to check that separately.
        *
-       *     Deliberately does NOT encode rollout progress — whether a promotion is in
-       *     flight is an orthogonal question to whether production is serving, and this
-       *     field answers only the latter. A promotion can be started from an app that is
-       *     currently `RUNNING` (the old deployment keeps serving throughout) just as much
-       *     as from one that is `SUSPENDED`/`SLEEPING`/`NOT_DEPLOYED` (nothing serves until
-       *     the new one comes up), so "is a promotion in progress" cannot be read off this
-       *     field's value under any reading of it. To detect one, compare `production`'s
-       *     `desiredId`/`desiredNumber` against `actualId`/`actualNumber`: while they
-       *     differ, the deployment named `desired` has been asked for but the one named
-       *     `actual` is still what traffic actually reaches (or nothing is serving yet, if
-       *     `actual` is still `null`). A client that needs both facts — is production
-       *     serving, and is a rollout in progress — must read both `state` and `production`;
-       *     neither can be derived from the other.
-       *
-       *     | Value | Meaning for a caller |
+       *     | Value | Meaning |
        *     |---|---|
-       *     | `NOT_DEPLOYED` | No `/v2` deployment has ever been promoted to this app's production. Its URL is reserved and publicly 404s. Also shown for an app that only runs via `/v1` and was never adopted into the deployments model — `production` is `{null, null}` for it too, for the same reason. |
-       *     | `STARTING` | Production is named but not yet confirmed serving — right after a first `promote`/`resume`, during a normal startup, or a promotion in flight where nothing was already serving beforehand (`production.actualId` was `null` going in). |
-       *     | `RUNNING` | Production is named and serving. Normal and healthy — including for the entire duration of a blue/green promotion started from a `RUNNING` app: the old, still-`actual` deployment keeps serving traffic throughout, so this stays `RUNNING` rather than dropping to `STARTING` for the length of the rollout. Compare `production.desiredId`/`actualId` if you need to know whether that rollout is still in progress. |
-       *     | `SLEEPING` | Stopped, but **will** wake on the next request — apps-proxy's wake-on-request path is still armed. This is the NORMAL, expected condition for an idle data app between visits, not an outage; do not alert on it. Produced by idle auto-suspend, which patches only the workload state and deliberately leaves wake-on-request armed. No idle-auto-suspend mechanism exists for a purely `/v2`-created app yet (deferred, not built) — today this is reachable only for a `/v1`-adopted app still picked up by the legacy idle-suspend job, the same way `Deployment.buildState`'s non-`PREBUILT` values are not reachable until builds land. |
-       *     | `SUSPENDED` | Stopped and will **not** wake on the next request — a visitor gets a `503` instead. Produced only by an explicit `POST .../suspend`; cleared only by `POST .../resume`. This is the field this whole enum exists to make distinguishable from `SLEEPING`: before it, both looked identical from the outside, and the only way to tell them apart was `POST .../resume` and inspecting `202` vs `204` — a write used as a read, which could itself wake a sleeping app. |
-       *
-       *     Mirrored from the App CRD (`spec.state`, `spec.autoRestartEnabled`,
-       *     `status.currentState`, `status.production`) by the same background sync that
-       *     mirrors `production`, so reading it costs no extra cluster call — including on
-       *     `GET /apps`, which would otherwise be one cluster round trip per row. The one
-       *     exception: `suspend`/`resume`/`promote`/`unpublish` write this field
-       *     themselves, immediately, in the same call that changes it, so the App they
-       *     return is never one sync cycle stale about its own action.
-       *
-       *     Deliberately not `Stopping`, even though the App CRD's `status.currentState`
-       *     names a fourth value: verified against the operator's product-role
-       *     controller, which never publishes it for a product App — its derivation has
-       *     exactly three branches. Also deliberately not `FAILED` — see above.
+       *     | `notDeployed` | Nothing has ever been promoted. The URL is reserved and publicly 404s. |
+       *     | `starting` | Production is named but not yet confirmed serving. |
+       *     | `running` | Production is named and serving. Normal and healthy. |
+       *     | `suspended` | Stopped, but wakes on the next request. Normal for an idle app between visits, not an outage. |
+       *     | `disabled` | Stopped by a failure and will not auto-wake; a visitor sees the restart-disabled page. Cleared only by an explicit start. |
        * @enum {string}
        */
-      state: 'NOT_DEPLOYED' | 'STARTING' | 'RUNNING' | 'SLEEPING' | 'SUSPENDED';
+      state: 'notDeployed' | 'starting' | 'running' | 'suspended' | 'disabled';
     };
-    /** @description Minimal shape — additional fields may be added as the `/v2` surface grows. Deliberately excludes app content and auth: both are Storage API concerns, configured after creation on the config named by the response's `componentId`/`branchId`/`configId` — content via `parameters`, auth via `authorization.app_proxy`. */
+    /** @description Every `/v2`-created app is `prod`, so there is no `mode` field. Additional fields may be added as the surface grows. */
     AppCreateRequest: {
-      /** @description Create-only: stored in the app's Storage configuration (see `App.componentId`) and never copied onto the `App` response. There is no way to rename it after creation — `AppPatchRequest` carries no field for it. */
+      /** @description The dev branch to create the app's Storage configuration in. `null` resolves to the project's default branch — see `App.branchId` for what ends up stored. */
+      branchId: string | null;
+      /** @description Create-only: stored in the app's Storage configuration (see `App.componentId`) and never copied onto the `App` response. There is no way to rename it after creation — `/v2` has no update endpoint for an app's plain settings yet. */
       name: string;
       /**
-       * @description App type. Only data-app types are supported by `/v2/apps` — workspace types (e.g. `snowflake`, `bigquery`) are created via `/apps`, not this endpoint.
+       * @description App type.
        * @enum {string}
        */
       type: 'streamlit' | 'python-js';
       /** @description Create-only, same as `name` — stored in the app's Storage configuration (see `App.componentId`) and never copied onto the `App` response or editable afterwards. */
       description?: string | null;
+      /** @description Initial `parameters`/`authorization.app_proxy` content for the app's Storage configuration, same shape as the config itself. Defaults to `{}` — see the operation description for what an app has until this or a later Storage API call sets it. */
+      config?: {
+        [key: string]: unknown;
+      };
+      /**
+       * @description If `true`, a managed Git repository is provisioned via the Git Service and linked to the app. Repo creation failure aborts app creation (best-effort rollback). The linked repo is deleted when the app is deleted.
+       * @default false
+       */
+      useManagedGitRepo: boolean;
     };
-    /** @description No patchable field exists yet — `name` and `description` are create-only (see `AppCreateRequest`), so the only currently valid body is `{}`; sending either is rejected as an unknown field (`422`), not silently ignored. Additional fields may be added here as the `/v2` surface grows. Promotion, unpublishing, suspend, and resume are separate action-verb endpoints, not part of this shape. */
-    AppPatchRequest: Record<string, never>;
     Deployment: {
-      /** @description Deployment id — also the deterministic Kubernetes CR name. */
+      /**
+       * Format: uuid
+       * @description Deployment id (UUIDv7), assigned when the deployment is created.
+       */
       id: string;
-      /** @description Display/sort number, allocated from a per-app DB sequence. */
-      number: number;
-      /** @description Storage config id this deployment was created from. Paired with `configVersion` below because a version number alone cannot be resolved via the Storage API without knowing which config it belongs to — the pairing mirrors `GET /apps/{appId}`, whose own `configId`/`configVersion` describe the app's *current* config rather than what a specific deployment was pinned to. */
-      configId: string;
       /** @description Storage config version pinned at deploy time. Resolved fresh from Storage on every `POST .../deployments` call, so it can differ from the app's own `configVersion` (which only reflects the config as of app creation). */
       configVersion: string;
       /** @description Git commit the deployment's code was built from. Always `null` today: no /v2 app type builds from a git-managed source yet, so nothing ever resolves a commit SHA to attach here. Present as a field now so a future git-backed build path has nowhere else to put it. */
@@ -751,75 +618,45 @@ type components = {
        * @description Backend size, pinned per version at deploy time from the config's `runtime.backend.size` (falling back to `parameters.size`). `null` when the config named no size, or named one that is not a recognised value — in both cases the platform default applies.
        * @enum {string|null}
        */
-      size?: 'micro' | 'tiny' | 'small' | 'medium' | 'large' | 'external' | null;
+      runtimeSize?: 'micro' | 'tiny' | 'small' | 'medium' | 'large' | 'external' | null;
       /**
        * @description Does a runnable artifact exist for this deployment?
        *
-       *     Only `PREBUILT` occurs today, and it is a fact rather than a placeholder: a
+       *     Only `ready` occurs today, and it is a fact rather than a placeholder: a
        *     deployment is created with `source.image`, so an image is supplied and the
        *     platform builds nothing. The remaining values become reachable when builds
-       *     land and a deployment can name a commit or branch instead. `PREBUILT` does
+       *     land and a deployment can name a commit or branch instead. `ready` does
        *     not become obsolete then — supplying a ready image stays legitimate, so it
        *     stops being the only value rather than becoming a wrong one.
        *
-       *     `FAILED` here means no artifact was produced, so the deployment can never
+       *     `failed` here means no artifact was produced, so the deployment can never
        *     run. That is a different problem, with a different fix, from a run failure.
        * @enum {string}
        */
-      buildState: 'PREBUILT' | 'PENDING' | 'BUILDING' | 'BUILT' | 'FAILED';
+      buildState: 'pending' | 'building' | 'ready' | 'failed';
       /**
-       * @description Is there a live workload for this deployment right now, and is it healthy?
-       *
-       *     * `NEVER_RUN` — nothing ever started it. Deployments are created stopped and
-       *       only become running once promoted, so this is the normal state of a staged
-       *       deployment, not a stall.
-       *     * `PENDING` — a run was requested but nothing is executing yet: pulling an
-       *       image, waiting to be scheduled, or unable to be placed at all.
-       *     * `STARTING` — a container is executing but not ready yet.
-       *     * `RUNNING` — up and ready.
-       *     * `STOPPING` / `STOPPED` — shutting down, or stopped having run before.
-       *     * `FAILED` — the workload crashed, could not start, or hit a terminal
-       *       dependency error. `GET /apps/{appId}/runs` carries the cause.
-       *
-       *     **Known limitation.** A promoted deployment blocked by a *platform* failure —
-       *     an image that cannot be pulled, a pod that cannot be scheduled — stays
-       *     `PENDING` indefinitely with no reason attached and no automatic resolution.
-       *     Its container never executes, so nothing records a workload failure. This is
-       *     accepted behaviour, not a transient state to wait out: a `PENDING` that is
-       *     not advancing, with the app's `production.desiredId` naming this deployment's
-       *     `id` while `production.actualId` names another, is what it looks like.
-       *     Production is unaffected — the previously promoted deployment keeps serving.
-       *
-       *     This axis says nothing about whether the deployment is production. That is a
-       *     property of the app's pointer, not of the version, and lives on the app as
-       *     `production.desiredId` / `production.actualId` (plus their `Number` twins).
+       * @description Whether this deployment currently has a live, healthy workload.
        *
-       *     **Deriving a single headline status**, for clients that want one. Apply in
-       *     order, first match wins — recorded here so every client agrees rather than
-       *     inventing its own rule:
-       *
-       *     | condition | headline |
+       *     | Value | Meaning |
        *     |---|---|
-       *     | `buildState == FAILED` | build failed |
-       *     | `buildState in (PENDING, BUILDING)` | building |
-       *     | `runState == FAILED` | failed |
-       *     | `runState in (PENDING, STARTING)` | starting |
-       *     | `runState == RUNNING` | running |
-       *     | `runState == STOPPING` | stopping |
-       *     | `runState == STOPPED` | stopped |
-       *     | `runState == NEVER_RUN` | ready — built, idle, promotable |
+       *     | `neverRun` | Created but never promoted — normal for a staged deployment. |
+       *     | `pending` | Requested but not yet executing (pulling an image, scheduling). |
+       *     | `starting` | Executing but not ready yet. |
+       *     | `running` | Up and healthy. |
+       *     | `stopping` / `stopped` | Shutting down, or stopped after running. |
+       *     | `failed` | Crashed, failed to start, or hit a terminal error — see `GET /apps/{appId}/runs` for the cause. |
        *
-       *     Not published as a field: with `buildState` fixed at `PREBUILT`, it would be
-       *     a pure function of `runState` and so a rename of the field beside it. It
-       *     becomes worth shipping once builds make `buildState` vary.
+       *     **Caveat:** a platform-level failure (image can't be pulled, no schedulable
+       *     node) can leave a deployment stuck at `pending` indefinitely instead of
+       *     reaching `failed`.
        * @enum {string}
        */
-      runState: 'NEVER_RUN' | 'PENDING' | 'STARTING' | 'RUNNING' | 'STOPPING' | 'STOPPED' | 'FAILED';
-      /** @description `true` once retired (member CR + rendered-config Secret deleted); the row remains in history and is re-materializable. */
+      runState: 'neverRun' | 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'failed';
+      /** @description `true` once deleted — its running resources and credentials are gone and it can no longer be promoted — but it remains in history. */
       archived: boolean;
       /**
        * Format: date-time
-       * @description When the deployment was retired; `null` while `archived` is `false`.
+       * @description When the deployment was deleted; `null` while `archived` is `false`.
        */
       archivedAt: string | null;
       /**
@@ -828,26 +665,23 @@ type components = {
        */
       createdAt: string;
     };
-    /** @description A single execution of a deployment. Shares every field with `/v1`'s run payload except `deploymentId`, which `/v1` does not carry: `/v1` has no concept of deployments, so unlike the rest of this shape it does not travel back there. This is a deliberate, permanent divergence — not drift to "fix" by adding `deploymentId` to `/v1` or by removing it here. */
+    /** @description A single execution of a deployment. */
     Run: {
       /** Format: uuid */
       id: string;
       appId: string;
-      /** @description The deployment this run belongs to. `null` for a run that belongs to the app itself rather than to a deployment (a `/v1`-style run), which is why it is nullable rather than required-and-present. */
+      /** @description The deployment this run belongs to. `null` for a run that belongs to the app itself rather than to one of its deployments, and for one recorded before runs carried a subject. */
       deploymentId: string | null;
-      /**
-       * @description Lower-case, unlike the `UPPER_SNAKE` of a deployment's `buildState` and `runState`. That is deliberate, not an oversight: this field is shared with `/v1`'s run payload, and changing the casing on the `/v2` copy alone would fork the two. If it is ever normalised, both surfaces move together.
-       * @enum {string|null}
-       */
+      /** @enum {string|null} */
       state?: 'starting' | 'running' | 'failed' | 'finished' | null;
       /**
        * Format: date-time
-       * @description When the run was opened — stamped before any compute exists, so `now - createdAt` on a deployment still reported `PENDING` is how long it has failed to start.
+       * @description When the run was opened — stamped before any compute exists, so `now - createdAt` on a deployment still reported `pending` is how long it has failed to start.
        */
       createdAt?: string | null;
       /**
        * Format: date-time
-       * @description When the run's workload became ready — stamped only once a Pod matching this run reports `Ready`. A run that never got that far keeps `null` here for good, so `startedAt: null` means "no compute ever became healthy", not "no information". It is not a failure signal on its own: a run can end `failed` with `startedAt: null` and still carry a classified `failureReason`.
+       * @description When the run's workload became ready to serve traffic. A run that never got that far keeps `null` here for good, so `startedAt: null` means "no compute ever became healthy", not "no information". It is not a failure signal on its own: a run can end `failed` with `startedAt: null` and still carry a classified `failureReason`.
        */
       startedAt?: string | null;
       /** Format: date-time */
@@ -860,14 +694,13 @@ type components = {
       /**
        * @description Why the run failed, when it did. The cause a failed deployment points at. Set at the moment a cause is attributed and never updated afterwards.
        *     A cause is recorded whenever one can be attributed, which happens on both sides of the container ever executing: **before compute** — configuration, decryption, storage-token and workspace failures — and **after the container has executed** — a startup probe that never passed, a startup deadline exceeded. So a classified failure says nothing about how far the run got: plenty of them never started at all.
-       *     **The one gap is a container that never executed for a platform reason** — `ImagePullBackOff`, `CreateContainerError`, a Pod that cannot be scheduled. Such a run keeps its `createdAt`, never gets a `startedAt`, and never gets a `failureReason`; it stays open indefinitely rather than being closed as failed. That is deliberate — platform problems are left to recover once the platform issue is fixed — and it is the same gap a deployment stuck at `runState: PENDING` is the visible form of. A run left open this way is never billed: billing needs `startedAt`, and there is no fallback to `createdAt`.
-       *     Absence therefore means "no cause was attributable", not "look again later" — for the platform case nothing further will ever arrive. Runs predating the field are also unclassified.
+       *     Absence therefore means "no cause was attributable", not "look again later". Runs predating the field are also unclassified.
        *     Both members are present whenever the object is, but either may be `null`. Branch on `reason`, not on `message`.
        */
       failureReason?: {
         /**
-         * @description Short, stable, machine-readable identifier, intended as a UI i18n key — the member to switch on when headlining a failure. The value set is owned by the operator and is not enumerated here, so a client must keep a default branch for identifiers it does not know.
-         *     Stable, but **coarser than the names suggest**: one identifier is deliberately reused across related causes rather than split, because each value is an i18n key a client has to learn before it can be emitted. Do not infer the precise cause from `reason` alone — `message` carries the actionable detail, and two failures sharing a `reason` need not share a remedy.
+         * @description Short, stable, machine-readable identifier — the member to switch on when headlining a failure. The value set is owned by the platform and is not enumerated here, so a client must keep a default branch for identifiers it does not know.
+         *     Stable, but **coarser than the names suggest**: one identifier is deliberately reused across related causes rather than split, because each value is one a client has to learn before it can be handled. Do not infer the precise cause from `reason` alone — `message` carries the actionable detail, and two failures sharing a `reason` need not share a remedy.
          */
         reason?: string | null;
         /** @description Human-readable description of the failure, free of internal resource names and cluster-internal detail. Safe to show verbatim. */
@@ -877,10 +710,12 @@ type components = {
     };
     DeploymentCreateRequest: {
       /**
-       * @description If true (the default), this deployment is also promoted to production. Set `false` to stage a release now and promote it later: the deployment is created and its config version pinned immutably, but nothing starts it and it is not reachable — a staged deployment only ever runs once promoted, at which point the operator validates it by starting it and switches the route only if it becomes healthy.
+       * @description If true (the default), this deployment is also promoted to production and started right away. Set `false` to stage a release now and promote it later: the deployment is created and its config version pinned immutably, but nothing starts it and it is not reachable — a staged deployment only ever runs once promoted, at which point it is started and put on the route only if it becomes healthy.
        * @default true
        */
       promote: boolean;
+      /** @description Pins this deployment to a specific Storage config version instead of whatever is newest at the moment of the request. Omit to deploy the latest version. */
+      configVersion?: string | null;
     };
     CreateCredentialRequest: {
       /** @enum {string} */
@@ -980,9 +815,7 @@ interface operations {
   createApp: {
     parameters: {
       query?: never;
-      header?: {
-        'Idempotency-Key'?: string;
-      };
+      header?: never;
       path?: never;
       cookie?: never;
     };
@@ -992,15 +825,6 @@ interface operations {
       };
     };
     responses: {
-      /** @description OK — an `Idempotency-Key` replay; the app already existed and nothing was created. */
-      200: {
-        headers: {
-          [name: string]: unknown;
-        };
-        content: {
-          'application/json': components['schemas']['App'];
-        };
-      };
       /** @description Created */
       201: {
         headers: {
@@ -1039,8 +863,8 @@ interface operations {
           'application/json': components['schemas']['App'];
         };
       };
-      /** @description Forbidden — the app belongs to a different project than the token's. */
-      403: {
+      /** @description Bad Request */
+      400: {
         headers: {
           [name: string]: unknown;
         };
@@ -1073,8 +897,8 @@ interface operations {
         };
         content?: never;
       };
-      /** @description Forbidden — the app belongs to a different project than the token's. */
-      403: {
+      /** @description Bad Request */
+      400: {
         headers: {
           [name: string]: unknown;
         };
@@ -1089,7 +913,7 @@ interface operations {
       };
     };
   };
-  patchApp: {
+  unpublishApp: {
     parameters: {
       query?: never;
       header?: never;
@@ -1098,13 +922,9 @@ interface operations {
       };
       cookie?: never;
     };
-    requestBody: {
-      content: {
-        'application/json': components['schemas']['AppPatchRequest'];
-      };
-    };
+    requestBody?: never;
     responses: {
-      /** @description OK */
+      /** @description OK — already unpublished (with or without an App CRD); no-op, returns the app unchanged */
       200: {
         headers: {
           [name: string]: unknown;
@@ -1113,33 +933,6 @@ interface operations {
           'application/json': components['schemas']['App'];
         };
       };
-      /** @description Forbidden — the app belongs to a different project than the token's. */
-      403: {
-        headers: {
-          [name: string]: unknown;
-        };
-        content?: never;
-      };
-      /** @description Not Found */
-      404: {
-        headers: {
-          [name: string]: unknown;
-        };
-        content?: never;
-      };
-    };
-  };
-  unpublishApp: {
-    parameters: {
-      query?: never;
-      header?: never;
-      path: {
-        appId: string;
-      };
-      cookie?: never;
-    };
-    requestBody?: never;
-    responses: {
       /** @description Accepted — production is being unset */
       202: {
         headers: {
@@ -1149,8 +942,8 @@ interface operations {
           'application/json': components['schemas']['App'];
         };
       };
-      /** @description No Content — already unpublished (with or without an App CRD); no-op */
-      204: {
+      /** @description Forbidden — the app belongs to a different project than the token's. */
+      403: {
         headers: {
           [name: string]: unknown;
         };
@@ -1176,6 +969,15 @@ interface operations {
     };
     requestBody?: never;
     responses: {
+      /** @description OK — already suspended; no-op, returns the app unchanged */
+      200: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          'application/json': components['schemas']['App'];
+        };
+      };
       /** @description Accepted — suspend is being applied */
       202: {
         headers: {
@@ -1185,8 +987,8 @@ interface operations {
           'application/json': components['schemas']['App'];
         };
       };
-      /** @description No Content — already suspended; no-op */
-      204: {
+      /** @description Forbidden — the app belongs to a different project than the token's. */
+      403: {
         headers: {
           [name: string]: unknown;
         };
@@ -1221,6 +1023,15 @@ interface operations {
     };
     requestBody?: never;
     responses: {
+      /** @description OK — already running; no-op, returns the app unchanged */
+      200: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content: {
+          'application/json': components['schemas']['App'];
+        };
+      };
       /** @description Accepted — resume is being applied */
       202: {
         headers: {
@@ -1230,8 +1041,8 @@ interface operations {
           'application/json': components['schemas']['App'];
         };
       };
-      /** @description No Content — already running; no-op */
-      204: {
+      /** @description Forbidden — the app belongs to a different project than the token's. */
+      403: {
         headers: {
           [name: string]: unknown;
         };
@@ -1287,7 +1098,7 @@ interface operations {
         };
         content?: never;
       };
-      /** @description Forbidden */
+      /** @description Forbidden — the token is valid but lacks the `apps:proxy` scope. A Storage API token is rejected here whatever its project, unlike every other endpoint on this app. */
       403: {
         headers: {
           [name: string]: unknown;
@@ -1367,7 +1178,9 @@ interface operations {
           [name: string]: unknown;
         };
         content: {
-          'application/json': components['schemas']['App'];
+          'application/json': {
+            password: string;
+          };
         };
       };
       /** @description Bad Request — the app's config has no `password`-type auth provider. */
@@ -1375,9 +1188,7 @@ interface operations {
         headers: {
           [name: string]: unknown;
         };
-        content: {
-          'application/json': components['schemas']['ErrorResponse'];
-        };
+        content?: never;
       };
       /** @description Forbidden — the app belongs to a different project than the token's. */
       403: {
@@ -1398,7 +1209,7 @@ interface operations {
   listRuns: {
     parameters: {
       query?: {
-        /** @description Restrict to runs of a single deployment. */
+        /** @description Restrict to runs of a single deployment. Runs recorded before runs carried a subject have none and are never returned by this filter. */
         deploymentId?: string;
         /** @description Restrict to runs with `createdAt >= since` (RFC 3339 / ISO-8601, e.g. `2026-01-01T00:00:00+00:00`). */
         since?: string;
@@ -1434,7 +1245,7 @@ interface operations {
           'application/json': components['schemas']['ErrorResponse'];
         };
       };
-      /** @description Forbidden — the token belongs to a different project */
+      /** @description Forbidden — the app belongs to a different project than the token's. */
       403: {
         headers: {
           [name: string]: unknown;
@@ -1473,7 +1284,7 @@ interface operations {
           'application/json': components['schemas']['Run'];
         };
       };
-      /** @description Forbidden — the token belongs to a different project */
+      /** @description Forbidden — the app belongs to a different project than the token's. */
       403: {
         headers: {
           [name: string]: unknown;
@@ -1493,7 +1304,12 @@ interface operations {
   };
   listDeployments: {
     parameters: {
-      query?: never;
+      query?: {
+        /** @description `false` (the default) lists live deployments only. `true` lists deleted deployments only. */
+        archived?: boolean;
+        offset?: number;
+        limit?: number;
+      };
       header?: never;
       path: {
         appId: string;
@@ -1511,6 +1327,13 @@ interface operations {
           'application/json': components['schemas']['Deployment'][];
         };
       };
+      /** @description Bad Request — the app belongs to a different project than the token's, or `archived`, `offset` or `limit` is not valid. */
+      400: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content?: never;
+      };
       /** @description Not Found */
       404: {
         headers: {
@@ -1523,9 +1346,7 @@ interface operations {
   createDeployment: {
     parameters: {
       query?: never;
-      header?: {
-        'Idempotency-Key'?: string;
-      };
+      header?: never;
       path: {
         appId: string;
       };
@@ -1537,8 +1358,8 @@ interface operations {
       };
     };
     responses: {
-      /** @description OK — an `Idempotency-Key` replay; the deployment already existed and nothing was created. */
-      200: {
+      /** @description Accepted — deployment created. It starts at `buildState: ready`, `runState: neverRun`; promoting it is what causes it to run. */
+      202: {
         headers: {
           [name: string]: unknown;
         };
@@ -1546,14 +1367,12 @@ interface operations {
           'application/json': components['schemas']['Deployment'];
         };
       };
-      /** @description Accepted — deployment created. It starts at `buildState: PREBUILT`, `runState: NEVER_RUN`; promoting it is what causes it to run. */
-      202: {
+      /** @description Bad Request — the app belongs to a different project than the token's, or `configVersion` names a version that does not exist for this app's config. */
+      400: {
         headers: {
           [name: string]: unknown;
         };
-        content: {
-          'application/json': components['schemas']['Deployment'];
-        };
+        content?: never;
       };
       /** @description Not Found */
       404: {
@@ -1585,6 +1404,13 @@ interface operations {
           'application/json': components['schemas']['Deployment'];
         };
       };
+      /** @description Bad Request — the app belongs to a different project than the token's. */
+      400: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content?: never;
+      };
       /** @description Not Found */
       404: {
         headers: {
@@ -1606,20 +1432,27 @@ interface operations {
     };
     requestBody?: never;
     responses: {
-      /** @description Accepted — the member CR and its rendered-config Secret are being deleted */
+      /** @description Accepted — the deployment is being deleted; its running resources and credentials are being torn down */
       202: {
         headers: {
           [name: string]: unknown;
         };
         content?: never;
       };
-      /** @description No Content — already archived; no-op */
+      /** @description No Content — already deleted; no-op */
       204: {
         headers: {
           [name: string]: unknown;
         };
         content?: never;
       };
+      /** @description Bad Request — the app belongs to a different project than the token's. */
+      400: {
+        headers: {
+          [name: string]: unknown;
+        };
+        content?: never;
+      };
       /** @description Not Found */
       404: {
         headers: {
@@ -1627,7 +1460,7 @@ interface operations {
         };
         content?: never;
       };
-      /** @description Conflict — this deployment's id is named production.desiredId or production.actualId on the app. */
+      /** @description Conflict — this deployment's id is named production.desiredDeploymentId or production.actualDeploymentId on the app. */
       409: {
         headers: {
           [name: string]: unknown;
@@ -1650,7 +1483,7 @@ interface operations {
     };
     requestBody?: never;
     responses: {
-      /** @description Accepted — the intent was recorded. The operator validates and switches the route asynchronously; `production.desiredId`/`desiredNumber` and `production.actualId`/`actualNumber` on the app differ until it converges, and the deployment's own `runState` reports a target that failed to start. */
+      /** @description Accepted — the promotion happens asynchronously. Watch the app's `production.desiredDeploymentId` and `production.actualDeploymentId` to see its progress. */
       202: {
         headers: {
           [name: string]: unknown;
@@ -1659,8 +1492,8 @@ interface operations {
           'application/json': components['schemas']['App'];
         };
       };
-      /** @description No Content — already production; no-op */
-      204: {
+      /** @description Bad Request — the app belongs to a different project than the token's. */
+      400: {
         headers: {
           [name: string]: unknown;
         };
@@ -1673,7 +1506,7 @@ interface operations {
         };
         content?: never;
       };
-      /** @description Conflict — the app has no App CRD (it was never deployed via /v2). */
+      /** @description Conflict — either the app was never deployed via /v2, or this deployment has been deleted (`archived: true`). */
       409: {
         headers: {
           [name: string]: unknown;
@@ -1707,7 +1540,7 @@ interface operations {
           'text/plain': string;
         };
       };
-      /** @description Bad Request — the app has an App CRD but no currently serving member (`apps.appNotRunning`). */
+      /** @description Bad Request — the app has an App CRD but no currently serving deployment (`apps.appNotRunning`). */
       400: {
         headers: {
           [name: string]: unknown;
@@ -1752,7 +1585,7 @@ interface operations {
           'text/plain': string;
         };
       };
-      /** @description Bad Request — the app has an App CRD but no currently serving member (`apps.appNotRunning`). */
+      /** @description Bad Request — the app has an App CRD but no currently serving deployment (`apps.appNotRunning`). */
       400: {
         headers: {
           [name: string]: unknown;
@@ -1961,9 +1794,7 @@ interface operations {
   createAppGitRepoCredential: {
     parameters: {
       query?: never;
-      header?: {
-        'Idempotency-Key'?: string;
-      };
+      header?: never;
       path: {
         appId: string;
       };
@@ -1975,15 +1806,6 @@ interface operations {
       };
     };
     responses: {
-      /** @description OK — an `Idempotency-Key` replay; the credential already existed and nothing was created. */
-      200: {
-        headers: {
-          [name: string]: unknown;
-        };
-        content: {
-          'application/json': components['schemas']['CreatedCredential'];
-        };
-      };
       /** @description Created */
       201: {
         headers: {
@@ -2115,10 +1937,11 @@ type RunId = OpenapiPathType<paths['/apps/{appId}/runs/{runId}']['get']>['runId'
 type CredentialId = OpenapiPathType<paths['/apps/{appId}/git-repo/credentials/{credentialId}']['get']>['credentialId'];
 type GetAppsQuery = OpenapiQueryType<paths['/apps']['get']>;
 type GetAppRunsQuery = OpenapiQueryType<paths['/apps/{appId}/runs']['get']>;
+type GetDeploymentsQuery = OpenapiQueryType<paths['/apps/{appId}/deployments']['get']>;
 type GetLogsTailQuery = OpenapiQueryType<paths['/apps/{appId}/logs/tail']['get']>;
 type CreateAppBody = OpenapiBodyType<paths['/apps']['post']>;
 type CreateDeploymentBody = OpenapiBodyType<paths['/apps/{appId}/deployments']['post']>;
 type CreateCredentialBody = OpenapiBodyType<paths['/apps/{appId}/git-repo/credentials']['post']>;
 //#endregion
-export { components as S, DeploymentRunState as _, AppRun as a, GetLogsTailQuery as b, CreateCredentialBody as c, Credential as d, CredentialId as f, DeploymentId as g, DeploymentBuildState as h, AppPassword as i, CreateDeploymentBody as l, Deployment as m, AppGitRepo as n, AppState as o, CredentialList as p, AppId as r, CreateAppBody as s, App as t, CreatedCredential as u, GetAppRunsQuery as v, RunId as x, GetAppsQuery as y };
-//# sourceMappingURL=types-CBgLCkYe.d.ts.map
+export { components as C, RunId as S, DeploymentRunState as _, AppRun as a, GetDeploymentsQuery as b, CreateCredentialBody as c, Credential as d, CredentialId as f, DeploymentId as g, DeploymentBuildState as h, AppPassword as i, CreateDeploymentBody as l, Deployment as m, AppGitRepo as n, AppState as o, CredentialList as p, AppId as r, CreateAppBody as s, App as t, CreatedCredential as u, GetAppRunsQuery as v, GetLogsTailQuery as x, GetAppsQuery as y };
+//# sourceMappingURL=types-D6UmMa6E.d.ts.map