clean up deployments API surface

- Strip internal implementation details from public-facing Field
  descriptions and endpoint docstrings (adapter routing, provider
  snapshots, binding payloads, lazy sync)
- Rename flow_versions to flow_version_ids in DeploymentCreateRequest
  and DeploymentUpdateRequest for clarity
- Remove redundant match_limit query parameter from list_deployments;
  page size already caps results

Author: HzaRashid

src/backend/base/langflow/api/v1/deployments.py

@@ -6,21 +6,21 @@
 
 from fastapi import APIRouter, HTTPException, Query, status
 from lfx.services.deployment.schema import (
-    DeploymentCreateResult,
-    DeploymentStatusResult,
     DeploymentType,
-    DeploymentUpdateResult,
 )
 
-from langflow.api.utils import CurrentActiveUser, DbSession
+from langflow.api.utils import CurrentActiveUser, DbSession, DbSessionReadOnly
 from langflow.api.v1.schemas.deployments import (
     DeploymentCreateRequest,
+    DeploymentCreateResponse,
     DeploymentDuplicateParams,
     DeploymentDuplicateResponse,
     DeploymentGetResponse,
     DeploymentListResponse,
+    DeploymentStatusResponse,
     DeploymentTypeListResponse,
     DeploymentUpdateRequest,
+    DeploymentUpdateResponse,
     ExecutionCreateRequest,
     ExecutionCreateResponse,
     ExecutionStatusResponse,
@@ -36,7 +36,7 @@
 
 ProviderIdQuery = Annotated[
     UUID,
-    Query(description="The registered deployment provider account id."),
+    Query(description="Deployment provider account id."),
 ]
 
 # API provider-context contract matrix:
@@ -67,7 +67,9 @@ async def create_provider_account(
 @router.get("/providers", response_model=ProviderAccountListResponse, tags=["Deployment Providers"])
 async def list_provider_accounts(
     user: CurrentActiveUser,
-    db: DbSession,
+    db: DbSessionReadOnly,
+    page: Annotated[int, Query(ge=1)] = 1,
+    size: Annotated[int, Query(ge=1, le=50)] = 20,
 ):
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")
 
@@ -80,7 +82,7 @@ async def list_provider_accounts(
 async def get_provider_account(
     provider_id: UUID,
     user: CurrentActiveUser,
-    db: DbSession,
+    db: DbSessionReadOnly,
 ):
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")
 
@@ -117,7 +119,7 @@ async def update_provider_account(
 # ---------------------------------------------------------------------------
 
 
-@router.post("", response_model=DeploymentCreateResult, status_code=status.HTTP_201_CREATED)
+@router.post("", response_model=DeploymentCreateResponse, status_code=status.HTTP_201_CREATED)
 async def create_deployment(
     user: CurrentActiveUser,
     payload: DeploymentCreateRequest,
@@ -131,7 +133,7 @@ async def create_deployment(
 async def list_deployment_types(
     provider_id: ProviderIdQuery,
     user: CurrentActiveUser,
-    db: DbSession,
+    db: DbSessionReadOnly,
 ):
     """List deployment types for a provider account."""
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")
@@ -141,7 +143,9 @@ async def list_deployment_types(
 async def list_deployments(
     provider_id: ProviderIdQuery,
     user: CurrentActiveUser,
-    db: DbSession,
+    db: DbSessionReadOnly,
+    page: Annotated[int, Query(ge=1)] = 1,
+    size: Annotated[int, Query(ge=1, le=50)] = 20,
     deployment_type: Annotated[DeploymentType | None, Query()] = None,
     flow_version_ids: Annotated[
         list[str] | None,
@@ -152,18 +156,8 @@ async def list_deployments(
             )
         ),
     ] = None,
-    match_limit: Annotated[
-        int | None,
-        Query(
-            ge=1,
-            le=500,
-            description=(
-                "Optional cap on number of matching deployments returned per page when flow_version_ids are provided."
-            ),
-        ),
-    ] = None,
 ):
-    """List deployments for a provider account using lazy provider synchronization."""
+    """List deployments for a provider account."""
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")
 
 
@@ -178,20 +172,18 @@ async def create_deployment_execution(
     db: DbSession,
     user: CurrentActiveUser,
 ):
-    """Create a provider-agnostic deployment execution."""
+    """Create a deployment execution."""
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")
 
 
 @router.get("/executions/{execution_id}", response_model=ExecutionStatusResponse)
 async def get_deployment_execution(
     execution_id: str,
     provider_id: ProviderIdQuery,
-    deployment_id: Annotated[str, Query(description="Deployment id for execution polling.")],
-    deployment_type: Annotated[DeploymentType, Query(description="Deployment type for execution polling.")],
-    db: DbSession,
+    db: DbSessionReadOnly,
     user: CurrentActiveUser,
 ):
-    """Get provider-agnostic deployment execution state/output."""
+    """Get deployment execution status."""
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")
 
 
@@ -204,23 +196,23 @@ async def get_deployment_execution(
 async def get_deployment(
     deployment_id: str,
     user: CurrentActiveUser,
-    db: DbSession,
+    db: DbSessionReadOnly,
 ):
-    """Get a deployment and derive provider routing from persisted deployment metadata."""
+    """Get a deployment by id."""
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")
 
 
 @router.patch(
     "/{deployment_id}",
-    response_model=DeploymentUpdateResult,
+    response_model=DeploymentUpdateResponse,
 )
 async def update_deployment(
     deployment_id: str,
     payload: DeploymentUpdateRequest,
     db: DbSession,
     user: CurrentActiveUser,
 ):
-    """Update a deployment and derive provider routing from persisted deployment metadata."""
+    """Update a deployment."""
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")
 
 
@@ -230,7 +222,7 @@ async def delete_deployment(
     db: DbSession,
     user: CurrentActiveUser,
 ):
-    """Delete a deployment and derive provider routing from persisted deployment metadata."""
+    """Delete a deployment."""
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")
 
 
@@ -244,7 +236,7 @@ async def redeploy_deployment(
     db: DbSession,
     user: CurrentActiveUser,
 ):
-    """Redeploy a deployment and derive provider routing from persisted deployment metadata."""
+    """Redeploy a deployment."""
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")
 
 
@@ -259,18 +251,18 @@ async def duplicate_deployment(
     db: DbSession,
     user: CurrentActiveUser,
 ):
-    """Duplicate a deployment and derive provider routing from persisted deployment metadata."""
+    """Duplicate a deployment."""
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")
 
 
 @router.get(
     "/{deployment_id}/status",
-    response_model=DeploymentStatusResult,
+    response_model=DeploymentStatusResponse,
 )
 async def get_deployment_status(
     deployment_id: str,
-    db: DbSession,
+    db: DbSessionReadOnly,
     user: CurrentActiveUser,
 ):
-    """Get deployment health and derive provider routing from persisted deployment metadata."""
+    """Get deployment status."""
     raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail="Not implemented.")

src/backend/base/langflow/api/v1/schemas/deployments.py

@@ -52,8 +52,10 @@ def _normalize_optional_str(value: str | None) -> str | None:
 
 
 class ProviderAccountCreate(BaseModel):
+    model_config = {"extra": "forbid"}
+
     account_id: str | None = Field(default=None, min_length=1, description="Provider tenant/organization identifier.")
-    provider_key: str = Field(min_length=1, description="Deployment adapter routing key.")
+    provider_key: str = Field(min_length=1, description="Deployment provider key.")
     backend_url: str = Field(min_length=1, description="Deployment provider backend URL.")
     api_key: str = Field(min_length=1, description="Deployment provider API key.")
 
@@ -73,8 +75,10 @@ def normalize_account_id(cls, value: str | None) -> str | None:
 
 
 class ProviderAccountUpdate(BaseModel):
+    model_config = {"extra": "forbid"}
+
     account_id: str | None = Field(default=None, min_length=1, description="Provider tenant/organization identifier.")
-    provider_key: str | None = Field(default=None, min_length=1, description="Deployment adapter routing key.")
+    provider_key: str | None = Field(default=None, min_length=1, description="Deployment provider key.")
     backend_url: str | None = Field(default=None, min_length=1, description="Deployment provider backend URL.")
     api_key: str | None = Field(default=None, min_length=1, description="Deployment provider API key.")
 
@@ -127,15 +131,11 @@ class DeploymentGetResponse(DeploymentSummary):
     description: str | None = None
 
 
-class DeploymentListItem(BaseModel):
-    id: str
+class DeploymentListItem(DeploymentSummary):
+    """Extended deployment summary with list-specific fields."""
+
     resource_key: str
-    type: DeploymentType
-    name: str
     attached_count: int = Field(default=0, ge=0)
-    created_at: datetime | None = None
-    updated_at: datetime | None = None
-    provider_data: dict | None = None
 
 
 class DeploymentListResponse(BaseModel):
@@ -153,6 +153,30 @@ class ProviderAccountListResponse(BaseModel):
     total: int = Field(default=0, ge=0)
 
 
+class DeploymentCreateResponse(BaseModel):
+    """API response for deployment creation, wrapping service-layer fields."""
+
+    id: IdLike
+    name: str
+    description: str = ""
+    type: DeploymentType | None = None
+    provider_result: dict[str, Any] | None = None
+
+
+class DeploymentUpdateResponse(BaseModel):
+    """API response for deployment update."""
+
+    id: IdLike
+    provider_result: dict[str, Any] | None = None
+
+
+class DeploymentStatusResponse(BaseModel):
+    """API response for deployment status/health."""
+
+    id: IdLike
+    provider_data: dict[str, Any] | None = None
+
+
 class RedeployResponse(DeploymentOperationResult):
     pass
 
@@ -164,6 +188,8 @@ class DeploymentDuplicateResponse(DeploymentSummary):
 class DeploymentDuplicateParams(BaseModel):
     """Parameters for duplicating a deployment."""
 
+    model_config = {"extra": "forbid"}
+
     deployment_type: DeploymentType
 
 
@@ -191,6 +217,8 @@ def validate_ids(cls, values: list[str]) -> list[str]:
 class FlowVersionsPatch(BaseModel):
     """Add or remove flow version bindings on an existing deployment."""
 
+    model_config = {"extra": "forbid"}
+
     add: list[str] | None = Field(
         None,
         description="Flow version ids to attach to the deployment. Omit to leave unchanged.",
@@ -211,6 +239,11 @@ def validate_id_lists(cls, values: list[str] | None) -> list[str] | None:
     def validate_operations(self):
         add_values = self.add or []
         remove_values = self.remove or []
+
+        if not add_values and not remove_values:
+            msg = "At least one of 'add' or 'remove' must be provided."
+            raise ValueError(msg)
+
         overlap = set(add_values).intersection(remove_values)
         if overlap:
             ids = ", ".join(sorted(overlap))
@@ -225,26 +258,37 @@ def validate_operations(self):
 
 
 class DeploymentCreateRequest(BaseModel):
-    provider_id: UUID = Field(description="Deployment provider account id for adapter routing.")
-    spec: BaseDeploymentData = Field(description="The base metadata of the deployment.")
+    model_config = {"extra": "forbid"}
+
+    provider_id: UUID = Field(description="Deployment provider account id.")
+    spec: BaseDeploymentData = Field(description="Deployment metadata.")
     project_id: UUID | None = Field(
         default=None,
         description="Langflow Project id to persist the deployment under. Defaults to user's Starter Project.",
     )
-    flow_versions: FlowVersionsAttach | None = Field(
+    flow_version_ids: FlowVersionsAttach | None = Field(
         default=None,
-        description="Flow version ids used to build provider snapshots during deployment creation.",
+        description="Flow version ids to attach to the deployment.",
     )
-    config: ConfigItem | None = Field(default=None, description="Deployment config binding/create payload.")
+    config: ConfigItem | None = Field(default=None, description="Deployment configuration.")
 
 
 class DeploymentUpdateRequest(BaseModel):
+    model_config = {"extra": "forbid"}
+
     spec: BaseDeploymentDataUpdate | None = Field(default=None, description="Deployment metadata updates.")
-    flow_versions: FlowVersionsPatch | None = Field(
+    flow_version_ids: FlowVersionsPatch | None = Field(
         default=None,
-        description="Flow version attach/detach patch payload.",
+        description="Flow version attach/detach operations.",
     )
-    config: ConfigDeploymentBindingUpdate | None = Field(default=None, description="Deployment config binding patch.")
+    config: ConfigDeploymentBindingUpdate | None = Field(default=None, description="Deployment configuration update.")
+
+    @model_validator(mode="after")
+    def ensure_any_field_provided(self) -> DeploymentUpdateRequest:
+        if self.spec is None and self.flow_version_ids is None and self.config is None:
+            msg = "At least one of 'spec', 'flow_version_ids', or 'config' must be provided."
+            raise ValueError(msg)
+        return self
 
 
 # ---------------------------------------------------------------------------
@@ -253,21 +297,18 @@ class DeploymentUpdateRequest(BaseModel):
 
 
 class ExecutionCreateRequest(BaseModel):
-    provider_id: UUID = Field(description="Deployment provider account id for adapter routing.")
+    model_config = {"extra": "forbid"}
+
+    provider_id: UUID = Field(description="Deployment provider account id.")
     deployment_id: IdLike
-    deployment_type: DeploymentType
-    input: str | dict[str, Any] | None = None
     provider_input: dict[str, Any] | None = None
 
 
 class _ExecutionResponseBase(BaseModel):
     """Shared fields for execution responses."""
 
-    execution_id: str | None = None
+    execution_id: str
     deployment_id: IdLike
-    deployment_type: DeploymentType | None = None
-    status: str | None = None
-    output: str | dict[str, Any] | None = None
     provider_result: dict[str, Any] | None = None