feat(api): add async query parameter support

docs/advanced-features/http-api/index.md

@@ -9,10 +9,10 @@
 
 ## Endpoints
 
-|              **Name**              | **Method** | **Endpoint**  |          **Parameters**           |                           **Description**                            |
-|:----------------------------------:|:----------:|:-------------:|:---------------------------------:|:--------------------------------------------------------------------:|
-|     [Update](#http_api_update)     |   `POST`   | `/v1/update`  | [`image`](#image_parameter_usage) | Triggers container updates and returns JSON results of the operation |
-| [Metrics](../metrics-api/index.md) |   `GET`    | `/v1/metrics` |                                   |  Exposes Prometheus-compatible metrics for monitoring and alerting   |
+|              **Name**              | **Method** | **Endpoint**  |                           **Parameters**                            |                           **Description**                            |
+|:----------------------------------:|:----------:|:-------------:|:-------------------------------------------------------------------:|:--------------------------------------------------------------------:|
+|     [Update](#http_api_update)     |   `POST`   | `/v1/update`  | [`image`](#image_parameter_usage), [`async`](#asynchronous_updates) | Triggers container updates and returns JSON results of the operation |
+| [Metrics](../metrics-api/index.md) |   `GET`    | `/v1/metrics` |                                                                     |  Exposes Prometheus-compatible metrics for monitoring and alerting   |
 
 !!! Note
     Endpoints enforce HTTP method restrictions using method-based routing.
@@ -69,9 +69,11 @@
 | Status Code | Description                                                                               |
 |:-----------:|:------------------------------------------------------------------------------------------|
 |     200     | Update completed successfully                                                             |
+|     202     | Update triggered successfully and running asynchronously (with `?async=true`)             |
 |     401     | Invalid or missing authentication token                                                   |
 |     429     | Another update is already in progress (full updates only) or the request was rate limited |
 |     500     | Internal server error during request processing                                           |
+|     503     | Client cancelled while waiting on update lock (targeted updates only)                     |
 
 #### Error Response Format
 
@@ -107,7 +109,42 @@
 
 This behavior ensures that full updates (which may be resource-intensive) are not queued up, while targeted updates (which are typically faster) can wait for their turn.
 
-##### Example 429 Response
+#### Asynchronous Updates
+
+The `/v1/update` endpoint supports an `async` query parameter to trigger updates without waiting for completion. This is useful for CI environments or automation that needs to fire-and-forget without maintaining a long-lived connection.
+
+##### Asynchronous Update Trigger
+
+Adding the `?async=true` parameter to a POST request causes the handler to spawn the update in a background goroutine and return immediately with HTTP 202 Accepted.
+
+```bash
+curl -X POST -H "Authorization: Bearer mytoken" localhost:8080/v1/update?async=true
+```
+
+Response:
+
+```http
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+```
+
+Equivalent example for a targeted async update:
+
+```bash
+curl -X POST -H "Authorization: Bearer mytoken" "localhost:8080/v1/update?image=foo/bar:latest&async=true"
+```
+
+The same concurrency behavior applies to async requests: full updates return 429 if another update is already in progress, while targeted updates block until the lock is available before spawning the async goroutine.
+
+##### Status Codes for Async Requests
+
+| Status Code | Description                                                                               |
+|:-----------:|:------------------------------------------------------------------------------------------|
+|     202     | Update triggered successfully and running asynchronously                                  |
+|     401     | Invalid or missing authentication token                                                   |
+|     429     | Another update is already in progress (full updates only) or the request was rate limited |
+|     500     | Internal server error during request processing                                           |
+|     503     | Client cancelled while waiting on update lock (targeted updates only)                     |
 
 The following example shows what happens when a full update is requested while another update is already running:
 

pkg/api/update/doc.go

@@ -1,5 +1,5 @@
 // Package update provides an HTTP API handler for triggering Watchtower container updates.
-// It manages update requests with concurrency control and image targeting.
+// It manages update requests with concurrency control, image targeting, and asynchronous execution.
 //
 // Key components:
 //   - Handler: Processes HTTP requests to trigger updates with lock-based synchronization.
@@ -16,5 +16,5 @@
 //
 // The package uses a channel-based lock for concurrency, supports both targeted and
 // full updates with different lock acquisition strategies, and integrates with logrus
-// for logging requests.
+// for logging requests. Asynchronous execution is supported via the "async" query parameter.
 package update