feat(control-plane): version all API routes under /api/v2

clients/lci/src/api.rs

@@ -181,7 +181,7 @@ impl ApiClient {
     pub fn new(http: reqwest::Client, base: impl Into<String>, token: impl Into<String>) -> Self {
         Self {
             http,
-            base: base.into(),
+            base: base.into().trim_end_matches('/').to_string(),
             token: std::sync::Arc::new(tokio::sync::RwLock::new(token.into())),
         }
     }

clients/lci/src/config.rs

@@ -9,7 +9,7 @@ use directories::ProjectDirs;
 use std::path::PathBuf;
 
 /// Default control-plane base URL (prod). Override with `CONTROL_PLANE_URL`.
-pub const DEFAULT_API_URL: &str = "https://code-intelligence-api.ai.camer.digital";
+pub const DEFAULT_API_URL: &str = "https://code-intelligence-api.ai.camer.digital/api/v2";
 /// Default OIDC issuer (Keycloak realm). Override with `OIDC_ISSUER`.
 pub const DEFAULT_ISSUER: &str = "https://auth.verif.fyi/realms/camer-digital";
 /// Default public client id. Override with `OIDC_CLIENT_ID`.

docs/adr/0109-api-v2-route-versioning.md

@@ -0,0 +1,45 @@
+# ADR-0109: Version all control-plane routes under `/api/v2`
+
+- **Status:** Accepted
+- **Date:** 2026-07-28
+- **Deciders:** @stephane-segning, @leghadjeu-christian
+
+## Context
+
+Every route in the control plane was registered at the root path with no version prefix. Three
+different auth models (OIDC-gated dashboard routes, shared-bearer runner-internal routes, and
+admin routes) shared one flat, unversioned namespace. There was no mechanism to introduce a
+breaking API change without affecting all consumers simultaneously.
+
+## Decision
+
+All consumer-facing routes are nested under `/api/v2` using Axum's `.nest()`. The router is
+split into two functions:
+
+- `api_v2_router()` — returns all versioned routes as a `Router<AppState>`
+- `app()` — mounts the versioned sub-router plus the infra probes
+
+Health probes (`/healthz`, `/readyz`) and `/metrics` stay at root because they are consumed by
+Kubernetes and Prometheus respectively, not by API clients.
+
+The `/api/v2` prefix is carried in the env var, not appended by client constructors. Both internal
+and external clients trim trailing slashes and use the value as-is. The Helm chart values are
+updated to include the prefix:
+
+- `apps/web`: `controlPlaneUrl()` uses `AUTH_BACKEND_URL` as-is — chart sets `…:8080/api/v2`
+- `lci` CLI: `ApiClient::new()` trims trailing slashes — `api_url` must include `/api/v2`
+- `agent-clients`: `ControlPlaneClient::new()` trims trailing slashes — `CONTROL_PLANE_INTERNAL_URL` must include `/api/v2`
+
+This is consistent: every consumer has one place (the env var or config value) where the full API
+base is set. The Helm chart update is in the companion PR (ADORSYS-GIS/ai-helm).
+
+The cutover is hard — old flat paths return 404 immediately after deployment. The chart update
+must be deployed in the same window as the new image.
+
+## Consequences
+
+- The single `api_v2_router()` function is the canonical list of all versioned routes; adding a
+  route requires touching one place.
+- Operators must ensure `CONTROL_PLANE_INTERNAL_URL` and `AUTH_BACKEND_URL` include `/api/v2`.
+  The chart default values are updated in the companion Helm PR (ADORSYS-GIS/ai-helm#817).
+- Local dev env vars must also be updated if set explicitly (e.g. `CONTROL_PLANE_URL=http://localhost:8080/api/v2`).

services/agent-clients/src/control_plane/mod.rs

@@ -181,7 +181,7 @@ pub struct ControlPlaneClient {
 impl ControlPlaneClient {
     pub fn new(base_url: impl Into<String>, token: impl Into<String>) -> Self {
         Self {
-            base_url: base_url.into(),
+            base_url: base_url.into().trim_end_matches('/').to_string(),
             token: token.into(),
             http: reqwest::Client::new(),
         }

services/control-plane/src/http/webhook.rs

@@ -2675,7 +2675,7 @@ mod tests {
         });
         let body = Bytes::from(serde_json::to_vec(&payload).unwrap());
 
-        let response = gitlab_webhook_body(state, 1001, headers, body).await;
+        let response = gitlab_webhook_body(state, 2001, headers, body).await;
         assert_eq!(response.status(), StatusCode::ACCEPTED);
 
         let (preset, entry_point): (String, String) = sqlx::query_as(
@@ -2768,7 +2768,7 @@ mod tests {
         });
         let body = Bytes::from(serde_json::to_vec(&payload).unwrap());
 
-        let response = gitlab_webhook_body(state, 1001, headers, body).await;
+        let response = gitlab_webhook_body(state, 2002, headers, body).await;
         assert_eq!(response.status(), StatusCode::ACCEPTED);
 
         let preset: String = sqlx::query_scalar(

services/control-plane/src/main.rs

@@ -318,12 +318,9 @@ fn db_readiness(has_pool: bool, ping_ok: bool, allow_no_db: bool) -> DbReadiness
     }
 }
 
-fn app(state: AppState) -> Router {
+fn api_v2_router() -> Router<AppState> {
     Router::new()
-        .route("/healthz", get(liveness))
-        .route("/readyz", get(readiness))
-        .route("/metrics", get(metrics_endpoint))
-        // Path-scoped webhook ingress — one route per forge, no header-sniffing.
+        // Webhook ingress: path-scoped per forge, no header-sniffing.
         .route(
             "/webhook/github",
             post(webhook::github_webhook).layer(DefaultBodyLimit::max(webhook::MAX_BODY_BYTES)),
@@ -448,6 +445,14 @@ fn app(state: AppState) -> Router {
             "/internal/tasks/{id}/propose-pr",
             post(internal::propose_pr).layer(DefaultBodyLimit::max(32 * 1024 * 1024)),
         )
+}
+
+fn app(state: AppState) -> Router {
+    Router::new()
+        .route("/healthz", get(liveness))
+        .route("/readyz", get(readiness))
+        .route("/metrics", get(metrics_endpoint))
+        .nest("/api/v2", api_v2_router())
         .layer(axum::middleware::from_fn(track_http_metrics))
         .with_state(state)
 }