vertracloud-api 0.3.2__tar.gz → 0.3.3__tar.gz

{vertracloud_api-0.3.2 → vertracloud_api-0.3.3}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.3.3](https://github.com/vertracloud/sdk-api-py/compare/v0.3.2...v0.3.3) (2026-10-30)
+
+
+### Features
+
+* add locked_deploy_settings to applications ([6294bc1](https://github.com/vertracloud/sdk-api-py/commit/6294bc11ae5e1471ef68c997dbf875c8efdd4a69))
+* add templates and stacks resources ([f638dde](https://github.com/vertracloud/sdk-api-py/commit/f638dde5c4df10070f5a0485fa5e3f1fafae02d1))
+
 ## [0.3.2](https://github.com/vertracloud/sdk-api-py/compare/v0.3.1...v0.3.2) (2026-10-25)
 
 

{vertracloud_api-0.3.2 → vertracloud_api-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vertracloud-api
-Version: 0.3.2
+Version: 0.3.3
 Summary: Official Python SDK for the public API of Vertra Cloud, a Brazilian application hosting platform (PaaS).
 Project-URL: Homepage, https://vertracloud.app
 Project-URL: Documentation, https://docs.vertracloud.app/sdks
@@ -22,7 +22,7 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/vertracloud-api.svg)](https://pypi.org/project/vertracloud-api/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Official Python SDK for the [Vertra Cloud](https://vertracloud.app) public API: apps, databases, snapshots, account, workspaces and billing — one typed method per route.
+Official Python SDK for the [Vertra Cloud](https://vertracloud.app) public API: apps, databases, templates, stacks, snapshots, account, workspaces and billing — one typed method per route.
 
 - Python 3.10+, fully typed (`py.typed`), with `TypedDict` payloads.
 - Zero dependencies outside the standard library.
@@ -76,7 +76,7 @@ client = VertraClient(
 
 ### Per-call options
 
-Methods on apps, databases and images take a keyword-only `workspace_id`; downloads, uploads and streams also take `timeout`:
+Methods on apps, databases, images, templates and stacks take a keyword-only `workspace_id`; downloads, uploads and streams also take `timeout`:
 
 ```python
 # Act on a resource that belongs to a workspace
@@ -264,6 +264,52 @@ client.images.update(image["id"], {"description": None})
 client.images.delete(image["id"], confirm_name="meu-projeto")  # {"deleted_apps": [...]}
 ```
 
+### Templates
+
+A template describes what to create: one application, or a stack with applications, databases and a Blob folder. `deploy` returns a job right away; follow it with `deploys.events` (Server-Sent Events) or read `deploys.get`. A job that fails is undone as a whole.
+
+```python
+page = client.templates.list(category="bots", sort="popular")
+
+job = client.templates.deploy(
+    "n8n",
+    {"name": "my-n8n", "inputs": {"admin_email": "me@example.com"}},
+    idempotency_key="deploy-my-n8n-1",  # repeating the call returns the same job
+)
+
+events = client.templates.deploys.events(job["id"])
+for event in events:  # heartbeats are skipped; the loop ends when the API sends `end`
+    print(event["status"], event["current_step"])
+job = client.templates.deploys.get(job["id"])  # outputs are read here, never on the stream
+```
+
+`idempotency_key` is sent as the `Idempotency-Key` header and never goes in the body: the same key with the same request returns the same job, the same key with another request fails with `IDEMPOTENCY_KEY_CONFLICT`. Outputs marked `once` come back on the first read of a finished job and are empty afterwards.
+
+Private templates: `create` and `new_version` take the manifest and one ZIP per service that runs code (`sources={"web": zip_bytes}`); `from_app` and `from_stack` save what you already run (read `app_draft` / `stack_draft` first to review the variables). `share_links` creates, lists and revokes links; `share` previews, uses, copies or reports what a link gives. `updates` reads and runs the update of an app or stack that came from a template, and detaches it. `validate` checks a manifest without creating anything; the findings of a refused one are in `err.manifest_issues`.
+
+An application that came from an open template stops receiving versions when its code is changed. The calls that change code (`apps.files.write`, `move`, `delete`, `upload` and `apps.deploys.webhook.create`) fail with `TEMPLATE_DETACH_CONFIRMATION_REQUIRED` until you pass `confirm_detach=True` (in the body of `move` and `webhook.create`); `err.detach_action` tells which action asked for it.
+
+### Stacks
+
+A stack groups applications, databases and Blob folders, and keeps the connection variables of each application up to date. Changes that alter variables or certificates return `restart_required` and `apps_to_restart`: an application reads them only when it starts, so the restart is yours to ask for. The same notice comes back from `databases.credentials.certificate.reset` and `password.reset`.
+
+```python
+change = client.stacks.create(
+    {
+        "name": "shop",
+        "members": [
+            {"resource_type": "application", "resource_id": app_id},
+            {"resource_type": "database", "resource_id": db_id},
+        ],
+        "bindings": [{"app_id": app_id, "database_id": db_id}],
+    }
+)
+if change["restart_required"]:
+    print("restart:", change["apps_to_restart"])
+```
+
+`delete` needs `confirm_name` equal to the stack name; mode `dissolve` removes only the stack, `delete_all` deletes the members too. `members`, `bindings` and `snapshots` group the routes of members, connections and whole-stack snapshots; `connection` returns code to connect an app to what it is linked to. Move a stack or a template to a workspace with `workspaces.stacks` and `workspaces.templates`. The error codes of both areas are constants in `vertracloud.errcodes`.
+
 ### Database versions
 
 ```python
@@ -291,6 +337,8 @@ except VertraAPIError as err:
     print(err.status, err.code, err)
 ```
 
+A few errors carry a structured `details`; tolerant properties read them and give an empty value for any other error: `err.issues` (`DOCKERFILE_REFUSED`), `err.manifest_issues` (`TEMPLATE_MANIFEST_INVALID`), `err.secret_files` (`TEMPLATE_SECRET_IN_SOURCE`), `err.update_blocked` (`TEMPLATE_UPDATE_BLOCKED`) and `err.detach_action` (`TEMPLATE_DETACH_CONFIRMATION_REQUIRED`).
+
 Other subclasses: `AuthenticationError` (401), `ScopeDeniedError` (403 — including a missing key scope) and `ValidationError` (400/422). The error codes are listed in the [API reference](https://docs.vertracloud.app/api-reference/introduction).
 
 ### Testing your code
@@ -308,9 +356,11 @@ client = VertraClient(api_key="test", transport=my_fake_transport)
 | Apps | `client.apps` (+ `.deploys`, `.releases`, `.domains`, `.network`, `.envs`, `.files`) | 43 |
 | Databases | `client.databases` (+ `.credentials`) | 14 |
 | Custom images | `client.images` | 12 |
+| Templates | `client.templates` (+ `.deploys`, `.share_links`, `.share`, `.updates`) | 32 |
+| Stacks | `client.stacks` (+ `.members`, `.bindings`, `.snapshots`) | 20 |
 | Snapshots | `client.snapshots` | 5 |
 | Account | `client.account` (+ `.sessions`, `.folders`, `.favorites`) | 10 |
-| Workspaces | `client.workspaces` (+ `.members`, `.roles`, `.invites`, `.action_requests`, `.apps`, `.databases`, `.folders`, `.favorites`) | 30 |
+| Workspaces | `client.workspaces` (+ `.members`, `.roles`, `.invites`, `.action_requests`, `.apps`, `.databases`, `.templates`, `.stacks`, `.folders`, `.favorites`) | 34 |
 | Billing | `client.billing` (+ `.orders`) | 7 |
 | Blob Storage | `client.blob` (+ `.shares`, `.rules`, `.domains`) | own host |
 

{vertracloud_api-0.3.2 → vertracloud_api-0.3.3}/README.md

@@ -3,7 +3,7 @@
 [![PyPI](https://img.shields.io/pypi/v/vertracloud-api.svg)](https://pypi.org/project/vertracloud-api/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Official Python SDK for the [Vertra Cloud](https://vertracloud.app) public API: apps, databases, snapshots, account, workspaces and billing — one typed method per route.
+Official Python SDK for the [Vertra Cloud](https://vertracloud.app) public API: apps, databases, templates, stacks, snapshots, account, workspaces and billing — one typed method per route.
 
 - Python 3.10+, fully typed (`py.typed`), with `TypedDict` payloads.
 - Zero dependencies outside the standard library.
@@ -57,7 +57,7 @@ client = VertraClient(
 
 ### Per-call options
 
-Methods on apps, databases and images take a keyword-only `workspace_id`; downloads, uploads and streams also take `timeout`:
+Methods on apps, databases, images, templates and stacks take a keyword-only `workspace_id`; downloads, uploads and streams also take `timeout`:
 
 ```python
 # Act on a resource that belongs to a workspace
@@ -245,6 +245,52 @@ client.images.update(image["id"], {"description": None})
 client.images.delete(image["id"], confirm_name="meu-projeto")  # {"deleted_apps": [...]}
 ```
 
+### Templates
+
+A template describes what to create: one application, or a stack with applications, databases and a Blob folder. `deploy` returns a job right away; follow it with `deploys.events` (Server-Sent Events) or read `deploys.get`. A job that fails is undone as a whole.
+
+```python
+page = client.templates.list(category="bots", sort="popular")
+
+job = client.templates.deploy(
+    "n8n",
+    {"name": "my-n8n", "inputs": {"admin_email": "me@example.com"}},
+    idempotency_key="deploy-my-n8n-1",  # repeating the call returns the same job
+)
+
+events = client.templates.deploys.events(job["id"])
+for event in events:  # heartbeats are skipped; the loop ends when the API sends `end`
+    print(event["status"], event["current_step"])
+job = client.templates.deploys.get(job["id"])  # outputs are read here, never on the stream
+```
+
+`idempotency_key` is sent as the `Idempotency-Key` header and never goes in the body: the same key with the same request returns the same job, the same key with another request fails with `IDEMPOTENCY_KEY_CONFLICT`. Outputs marked `once` come back on the first read of a finished job and are empty afterwards.
+
+Private templates: `create` and `new_version` take the manifest and one ZIP per service that runs code (`sources={"web": zip_bytes}`); `from_app` and `from_stack` save what you already run (read `app_draft` / `stack_draft` first to review the variables). `share_links` creates, lists and revokes links; `share` previews, uses, copies or reports what a link gives. `updates` reads and runs the update of an app or stack that came from a template, and detaches it. `validate` checks a manifest without creating anything; the findings of a refused one are in `err.manifest_issues`.
+
+An application that came from an open template stops receiving versions when its code is changed. The calls that change code (`apps.files.write`, `move`, `delete`, `upload` and `apps.deploys.webhook.create`) fail with `TEMPLATE_DETACH_CONFIRMATION_REQUIRED` until you pass `confirm_detach=True` (in the body of `move` and `webhook.create`); `err.detach_action` tells which action asked for it.
+
+### Stacks
+
+A stack groups applications, databases and Blob folders, and keeps the connection variables of each application up to date. Changes that alter variables or certificates return `restart_required` and `apps_to_restart`: an application reads them only when it starts, so the restart is yours to ask for. The same notice comes back from `databases.credentials.certificate.reset` and `password.reset`.
+
+```python
+change = client.stacks.create(
+    {
+        "name": "shop",
+        "members": [
+            {"resource_type": "application", "resource_id": app_id},
+            {"resource_type": "database", "resource_id": db_id},
+        ],
+        "bindings": [{"app_id": app_id, "database_id": db_id}],
+    }
+)
+if change["restart_required"]:
+    print("restart:", change["apps_to_restart"])
+```
+
+`delete` needs `confirm_name` equal to the stack name; mode `dissolve` removes only the stack, `delete_all` deletes the members too. `members`, `bindings` and `snapshots` group the routes of members, connections and whole-stack snapshots; `connection` returns code to connect an app to what it is linked to. Move a stack or a template to a workspace with `workspaces.stacks` and `workspaces.templates`. The error codes of both areas are constants in `vertracloud.errcodes`.
+
 ### Database versions
 
 ```python
@@ -272,6 +318,8 @@ except VertraAPIError as err:
     print(err.status, err.code, err)
 ```
 
+A few errors carry a structured `details`; tolerant properties read them and give an empty value for any other error: `err.issues` (`DOCKERFILE_REFUSED`), `err.manifest_issues` (`TEMPLATE_MANIFEST_INVALID`), `err.secret_files` (`TEMPLATE_SECRET_IN_SOURCE`), `err.update_blocked` (`TEMPLATE_UPDATE_BLOCKED`) and `err.detach_action` (`TEMPLATE_DETACH_CONFIRMATION_REQUIRED`).
+
 Other subclasses: `AuthenticationError` (401), `ScopeDeniedError` (403 — including a missing key scope) and `ValidationError` (400/422). The error codes are listed in the [API reference](https://docs.vertracloud.app/api-reference/introduction).
 
 ### Testing your code
@@ -289,9 +337,11 @@ client = VertraClient(api_key="test", transport=my_fake_transport)
 | Apps | `client.apps` (+ `.deploys`, `.releases`, `.domains`, `.network`, `.envs`, `.files`) | 43 |
 | Databases | `client.databases` (+ `.credentials`) | 14 |
 | Custom images | `client.images` | 12 |
+| Templates | `client.templates` (+ `.deploys`, `.share_links`, `.share`, `.updates`) | 32 |
+| Stacks | `client.stacks` (+ `.members`, `.bindings`, `.snapshots`) | 20 |
 | Snapshots | `client.snapshots` | 5 |
 | Account | `client.account` (+ `.sessions`, `.folders`, `.favorites`) | 10 |
-| Workspaces | `client.workspaces` (+ `.members`, `.roles`, `.invites`, `.action_requests`, `.apps`, `.databases`, `.folders`, `.favorites`) | 30 |
+| Workspaces | `client.workspaces` (+ `.members`, `.roles`, `.invites`, `.action_requests`, `.apps`, `.databases`, `.templates`, `.stacks`, `.folders`, `.favorites`) | 34 |
 | Billing | `client.billing` (+ `.orders`) | 7 |
 | Blob Storage | `client.blob` (+ `.shares`, `.rules`, `.domains`) | own host |
 

{vertracloud_api-0.3.2 → vertracloud_api-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vertracloud-api"
-version = "0.3.2"
+version = "0.3.3"
 description = "Official Python SDK for the public API of Vertra Cloud, a Brazilian application hosting platform (PaaS)."
 readme = "README.md"
 license = "MIT"

{vertracloud_api-0.3.2 → vertracloud_api-0.3.3}/src/vertracloud/__init__.py

@@ -1,5 +1,6 @@
 """Typed Python client for the Vertra Cloud public API (`import vertracloud`)."""
 
+from . import errcodes
 from .client import VertraClient, __version__
 from .errors import (
     AppBuildFailedError,
@@ -12,6 +13,7 @@ from .errors import (
     VertraAPIError,
     WaitTimeoutError,
 )
+from .resources.templates import TemplateDeployEventStream
 from .sse import SseEvent, SseStream
 from .transport import Response, Transport, UrllibTransport
 
@@ -29,6 +31,8 @@ __all__ = [
     "RateLimitError",
     "SseEvent",
     "SseStream",
+    "TemplateDeployEventStream",
+    "errcodes",
     "Transport",
     "UrllibTransport",
     "Response",

{vertracloud_api-0.3.2 → vertracloud_api-0.3.3}/src/vertracloud/client.py

@@ -16,7 +16,7 @@ from .sse import SseStream
 from .transport import Response, Transport, UrllibTransport
 from .types import JsonValue
 
-__version__ = "0.3.2"  # x-release-please-version
+__version__ = "0.3.3"  # x-release-please-version
 
 DEFAULT_BASE_URL = "https://api.vertracloud.app"
 DEFAULT_BLOB_BASE_URL = "https://blob.vertracloud.app/v1"
@@ -138,11 +138,15 @@ class VertraClient:
         from .resources.databases import DatabasesResource
         from .resources.images import ImagesResource
         from .resources.snapshots import SnapshotsResource
+        from .resources.stacks import StacksResource
+        from .resources.templates import TemplatesResource
         from .resources.workspaces import WorkspacesResource
 
         self.apps = AppsResource(self)
         self.databases = DatabasesResource(self)
         self.images = ImagesResource(self)
+        self.templates = TemplatesResource(self)
+        self.stacks = StacksResource(self)
         self.snapshots = SnapshotsResource(self)
         self.account = AccountResource(self)
         self.workspaces = WorkspacesResource(self)

vertracloud_api-0.3.3/src/vertracloud/errcodes.py

@@ -0,0 +1,65 @@
+"""Error codes of the template and stack routes, as found in `VertraAPIError.code`.
+
+Compare with the constants instead of retyping the strings::
+
+    from vertracloud import errcodes
+
+    try:
+        client.templates.deploy("n8n", {"name": "my-n8n"})
+    except VertraAPIError as err:
+        if err.code == errcodes.TEMPLATE_RAM_INSUFFICIENT:
+            ...
+"""
+
+from __future__ import annotations
+
+# -- templates
+TEMPLATE_NOT_FOUND = "TEMPLATE_NOT_FOUND"
+TEMPLATE_VERSION_NOT_FOUND = "TEMPLATE_VERSION_NOT_FOUND"
+TEMPLATE_SLUG_TAKEN = "TEMPLATE_SLUG_TAKEN"
+TEMPLATE_MANIFEST_INVALID = "TEMPLATE_MANIFEST_INVALID"  # `VertraAPIError.manifest_issues`
+TEMPLATE_INPUT_INVALID = "TEMPLATE_INPUT_INVALID"  # `details.issues` lists the questions
+TEMPLATE_SOURCE_REQUIRED = "TEMPLATE_SOURCE_REQUIRED"
+TEMPLATE_SECRET_IN_SOURCE = "TEMPLATE_SECRET_IN_SOURCE"  # `VertraAPIError.secret_files`
+TEMPLATE_GITHUB_MANIFEST_NOT_FOUND = "TEMPLATE_GITHUB_MANIFEST_NOT_FOUND"
+TEMPLATE_PLAN_REQUIRED = "TEMPLATE_PLAN_REQUIRED"
+TEMPLATE_RAM_INSUFFICIENT = "TEMPLATE_RAM_INSUFFICIENT"
+TEMPLATE_IMAGE_SLOTS_EXHAUSTED = "TEMPLATE_IMAGE_SLOTS_EXHAUSTED"
+TEMPLATE_CLOSED = "TEMPLATE_CLOSED"
+TEMPLATE_SETTING_LOCKED = "TEMPLATE_SETTING_LOCKED"
+TEMPLATE_PRIVATE_LIMIT_REACHED = "TEMPLATE_PRIVATE_LIMIT_REACHED"
+TEMPLATE_DEPLOY_IN_PROGRESS = "TEMPLATE_DEPLOY_IN_PROGRESS"
+TEMPLATE_DEPLOY_FAILED = "TEMPLATE_DEPLOY_FAILED"  # the deploy was undone; `details.step` is the step that failed
+TEMPLATE_DEPLOY_NOT_FOUND = "TEMPLATE_DEPLOY_NOT_FOUND"
+IDEMPOTENCY_KEY_CONFLICT = "IDEMPOTENCY_KEY_CONFLICT"
+IMAGE_TEMPLATE_ONLY = "IMAGE_TEMPLATE_ONLY"
+IMAGE_IN_USE = "IMAGE_IN_USE"  # `details.templates` lists the ids of the templates that use the image
+TEMPLATE_SAVE_NOT_ALLOWED = "TEMPLATE_SAVE_NOT_ALLOWED"
+TEMPLATE_UPDATE_BLOCKED = "TEMPLATE_UPDATE_BLOCKED"  # `VertraAPIError.update_blocked`
+TEMPLATE_DEPRECATED = "TEMPLATE_DEPRECATED"
+TEMPLATE_VERSION_NOT_SELECTABLE = "TEMPLATE_VERSION_NOT_SELECTABLE"
+TEMPLATE_DETACH_CONFIRMATION_REQUIRED = "TEMPLATE_DETACH_CONFIRMATION_REQUIRED"  # `VertraAPIError.detach_action`
+TEMPLATE_ROLLBACK_REQUIRES_DATA = "TEMPLATE_ROLLBACK_REQUIRES_DATA"
+TEMPLATE_STORAGE_UNAVAILABLE = "TEMPLATE_STORAGE_UNAVAILABLE"
+MANAGED_ENV_READONLY = "MANAGED_ENV_READONLY"
+
+# -- share links
+SHARE_LINK_NOT_FOUND = "SHARE_LINK_NOT_FOUND"
+SHARE_LINK_REVOKED = "SHARE_LINK_REVOKED"
+SHARE_LINK_EXPIRED = "SHARE_LINK_EXPIRED"
+SHARE_LINK_EXHAUSTED = "SHARE_LINK_EXHAUSTED"
+
+# -- stacks
+STACK_NOT_FOUND = "STACK_NOT_FOUND"
+STACK_MEMBER_CONFLICT = "STACK_MEMBER_CONFLICT"
+STACK_MEMBER_NOT_FOUND = "STACK_MEMBER_NOT_FOUND"
+STACK_BINDING_NOT_FOUND = "STACK_BINDING_NOT_FOUND"
+STACK_NETWORK_MODE_UNAVAILABLE = "STACK_NETWORK_MODE_UNAVAILABLE"
+STACK_SERVICE_LOCKED = "STACK_SERVICE_LOCKED"
+STACK_NAME_MISMATCH = "STACK_NAME_MISMATCH"
+STACK_TRANSFORM_EMPTY = "STACK_TRANSFORM_EMPTY"
+STACK_BLOB_PREFIX_TAKEN = "STACK_BLOB_PREFIX_TAKEN"
+
+# -- API keys restricted to a Blob folder, or managed by the platform
+BLOB_PREFIX_DENIED = "BLOB_PREFIX_DENIED"
+API_KEY_MANAGED = "API_KEY_MANAGED"

{vertracloud_api-0.3.2 → vertracloud_api-0.3.3}/src/vertracloud/errors.py

@@ -45,6 +45,41 @@ class VertraAPIError(Exception):
             return []
         return [item for item in raw if isinstance(item, dict)]
 
+    def _details_for(self, code: str) -> dict[str, Any] | None:
+        if self.code != code or not isinstance(self.details, dict):
+            return None
+        return self.details
+
+    @property
+    def manifest_issues(self) -> list[dict[str, Any]]:
+        """Findings of a `TEMPLATE_MANIFEST_INVALID` error: the objects in `details.issues` (`{path, code, message}`).
+        Tolerant like `issues`: any other error gives `[]`."""
+        details = self._details_for("TEMPLATE_MANIFEST_INVALID")
+        raw = details.get("issues") if details else None
+        return [item for item in raw if isinstance(item, dict)] if isinstance(raw, list) else []
+
+    @property
+    def secret_files(self) -> list[str]:
+        """Paths of a `TEMPLATE_SECRET_IN_SOURCE` error: the files of the code sent to become a template that hold
+        a secret. Any other error gives `[]`."""
+        details = self._details_for("TEMPLATE_SECRET_IN_SOURCE")
+        raw = details.get("files") if details else None
+        return [item for item in raw if isinstance(item, str)] if isinstance(raw, list) else []
+
+    @property
+    def update_blocked(self) -> dict[str, Any] | None:
+        """Reason of a `TEMPLATE_UPDATE_BLOCKED` error (`{reason, details?}`); `None` for any other error."""
+        return self._details_for("TEMPLATE_UPDATE_BLOCKED")
+
+    @property
+    def detach_action(self) -> str | None:
+        """Action of a `TEMPLATE_DETACH_CONFIRMATION_REQUIRED` error (`files.write`, `deploy.code`,
+        `deploy.github` or `commit`): repeat the call with `confirm_detach=True` to detach the app from its template.
+        `None` for any other error."""
+        details = self._details_for("TEMPLATE_DETACH_CONFIRMATION_REQUIRED")
+        action = details.get("action") if details else None
+        return action if isinstance(action, str) else None
+
 
 class AuthenticationError(VertraAPIError):
     """401 — invalid key or user not found (`API_KEY_INVALID`, `USER_NOT_FOUND`)."""

{vertracloud_api-0.3.2 → vertracloud_api-0.3.3}/src/vertracloud/resources/apps.py

@@ -73,7 +73,8 @@ class AppDeploysWebhookResource:
         )
 
     def create(self, app_id: str, body: CreateWebhookBody, *, workspace_id: str | None = None) -> APIWebhookUrl:
-        """POST /v1/apps/:id/deploys/webhook — scope `apps:write`."""
+        """POST /v1/apps/:id/deploys/webhook — scope `apps:write`. `body["confirm_detach"]` confirms that linking
+        GitHub detaches an app of an open template from it (`TEMPLATE_DETACH_CONFIRMATION_REQUIRED` otherwise)."""
         return self._c.request_json(
             "POST",
             f"/v1/apps/{encode_path_param(app_id)}/deploys/webhook",
@@ -335,9 +336,22 @@ class AppFilesResource:
         content: str | None = None,
         last_modified: str | None = None,
         workspace_id: str | None = None,
+        confirm_detach: bool = False,
     ) -> None:
-        """PUT /v1/apps/:id/files — scope `apps:files`. Response is void."""
-        body = {"path": path, "content": content, "last_modified": last_modified, "workspace_id": workspace_id}
+        """PUT /v1/apps/:id/files — scope `apps:files`. Response is void.
+
+        An app that came from an open template stops receiving versions of it when its code is changed: without
+        `confirm_detach=True` the call fails with `TEMPLATE_DETACH_CONFIRMATION_REQUIRED` and changes nothing
+        (`VertraAPIError.detach_action` says which action); with it the change is made and the app is detached.
+        Ignored for an app that does not come from a template. The same applies to `move`, `delete`, `upload`
+        and `deploys.webhook.create`."""
+        body = {
+            "path": path,
+            "content": content,
+            "last_modified": last_modified,
+            "workspace_id": workspace_id,
+            "confirm_detach": True if confirm_detach else None,
+        }
         return self._c.request_json(
             "PUT",
             f"/v1/apps/{encode_path_param(app_id)}/files",
@@ -345,7 +359,8 @@ class AppFilesResource:
         )
 
     def move(self, app_id: str, body: MoveFileBody, *, workspace_id: str | None = None) -> None:
-        """PATCH /v1/apps/:id/files — scope `apps:files`. Body: `{path, to, workspace_id?}`."""
+        """PATCH /v1/apps/:id/files — scope `apps:files`. Body: `{path, to, workspace_id?, confirm_detach?}`
+        (see `write` for `confirm_detach`)."""
         merged = {**body, "workspace_id": workspace_id or body.get("workspace_id")}
         return self._c.request_json(
             "PATCH",
@@ -353,9 +368,10 @@ class AppFilesResource:
             json_body={k: v for k, v in merged.items() if v is not None},
         )
 
-    def delete(self, app_id: str, *, path: str, workspace_id: str | None = None) -> None:
-        """DELETE /v1/apps/:id/files — scope `apps:files`. Body: `{path, workspace_id?}`."""
-        body = {"path": path, "workspace_id": workspace_id}
+    def delete(self, app_id: str, *, path: str, workspace_id: str | None = None, confirm_detach: bool = False) -> None:
+        """DELETE /v1/apps/:id/files — scope `apps:files`. Body: `{path, workspace_id?, confirm_detach?}`
+        (see `write` for `confirm_detach`)."""
+        body = {"path": path, "workspace_id": workspace_id, "confirm_detach": True if confirm_detach else None}
         return self._c.request_json(
             "DELETE",
             f"/v1/apps/{encode_path_param(app_id)}/files",
@@ -372,6 +388,7 @@ class AppFilesResource:
         path: str | None = None,
         message: str | None = None,
         workspace_id: str | None = None,
+        confirm_detach: bool = False,
         timeout: float | None = None,
     ) -> APIAppFileUploadResponse:
         """POST /v1/apps/:id/files/upload — scope `apps:files`. Multipart, field `file`;
@@ -379,6 +396,7 @@ class AppFilesResource:
         `path` is the destination folder inside the app (omitted or empty means the root);
         a ZIP is extracted into it, any other file is written to `path/<filename>`.
         `message` (up to 500 characters) is the commit message shown in the release history.
+        `confirm_detach=True` is sent as the query `confirm_detach=true` (see `write`).
         Returns `app_id` and `updated_at`; ZIP uploads also include dependency metadata."""
         fields = [MultipartField("file", file, filename=filename)]
         if message is not None:
@@ -387,7 +405,12 @@ class AppFilesResource:
             "POST",
             f"/v1/apps/{encode_path_param(app_id)}/files/upload",
             fields=fields,
-            query={"restart": restart, "path": path, "workspace_id": workspace_id},
+            query={
+                "restart": restart,
+                "path": path,
+                "workspace_id": workspace_id,
+                "confirm_detach": True if confirm_detach else None,
+            },
             timeout=timeout if timeout is not None else LARGE_PAYLOAD_TIMEOUT,
         )
 
@@ -502,7 +525,9 @@ class AppsResource:
         """POST /v1/apps/image — scope `apps:write`. JSON. Creates an app that runs from a custom
         image, which must be ready (`images.get(...)["status"] == "success"`). Replies 202 with
         `status: "building"` and `custom_image` filled in; follow the build as with `create`.
-        `web: False` makes an app without traffic; `subdomain` and `port` need `web: True`.
+        `web: False` makes an app without traffic; `subdomain` and `port` need `web: True`. An image that
+        belongs to a template (a platform image or a `template_copy`) fails with `IMAGE_TEMPLATE_ONLY`: use the
+        template instead.
         Doc: https://docs.vertracloud.app/api-reference/endpoint/apps/create-from-image
         """
         return self._c.request_json("POST", "/v1/apps/image", json_body=body)

{vertracloud_api-0.3.2 → vertracloud_api-0.3.3}/src/vertracloud/resources/databases.py

@@ -8,6 +8,7 @@ from ..client import encode_path_param
 from ..types import (
     APIDatabase,
     APIDatabaseCertificate,
+    APIDatabaseCertificateReset,
     APIDatabasePasswordReset,
     APIDatabaseStatus,
     APIDatabaseStatusShort,
@@ -36,8 +37,10 @@ class DatabaseCertificateResource:
             timeout=timeout,
         )
 
-    def reset(self, db_id: str, *, workspace_id: str | None = None) -> None:
-        """POST /v1/databases/:id/credentials/certificate/reset — scope `databases:credentials`."""
+    def reset(self, db_id: str, *, workspace_id: str | None = None) -> APIDatabaseCertificateReset:
+        """POST /v1/databases/:id/credentials/certificate/reset — scope `databases:credentials`. Besides the new
+        certificate, the answer lists the apps of stacks connected to the database that must restart to read it
+        (`restart_required`, `apps_to_restart`)."""
         return self._c.request_json(
             "POST",
             f"/v1/databases/{encode_path_param(db_id)}/credentials/certificate/reset",
@@ -50,7 +53,9 @@ class DatabasePasswordResource:
         self._c = client
 
     def reset(self, db_id: str, *, workspace_id: str | None = None) -> APIDatabasePasswordReset:
-        """POST /v1/databases/:id/credentials/reset — scope `databases:credentials`."""
+        """POST /v1/databases/:id/credentials/reset — scope `databases:credentials`. The answer also lists the apps
+        of stacks connected to the database that must restart to read the new password (`restart_required`,
+        `apps_to_restart`)."""
         return self._c.request_json(
             "POST", f"/v1/databases/{encode_path_param(db_id)}/credentials/reset", query={"workspace_id": workspace_id}
         )

{vertracloud_api-0.3.2 → vertracloud_api-0.3.3}/src/vertracloud/resources/images.py

@@ -7,6 +7,10 @@ is `success` or `failed`.
 
 `workspace_id` is a keyword-only query parameter on the routes that act on an existing image and
 on `list`. Without it the call acts on the caller's own images, as the apps routes do.
+
+An image that came from a template (`kind == "template_copy"`, or a platform image) cannot be renamed, rebuilt,
+linked to GitHub or committed to: those calls fail with `IMAGE_TEMPLATE_ONLY`. Deleting an image that is the
+source of one of your private templates fails with `IMAGE_IN_USE`.
 """
 
 from __future__ import annotations