From 7e1ff67265288d0711876ff6fe35a401a918c01f Mon Sep 17 00:00:00 2001
From: Michael Leone <mleone@coreweave.com>
Date: Tue, 31 Mar 2026 16:33:36 -0400
Subject: [PATCH] feat(api): adds order to list deploymentVersions * adds order
 param when listing deploymentVersions with a default value

---
 apps/api/openapi/lib/openapi.libsonnet         | 12 ++++++++++++
 apps/api/openapi/openapi.json                  | 18 ++++++++++++++++--
 .../openapi/paths/deploymentversions.jsonnet   |  1 +
 .../src/routes/v1/workspaces/deployments.ts    |  9 +++++++--
 apps/api/src/types/openapi.ts                  |  6 ++++--
 5 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/apps/api/openapi/lib/openapi.libsonnet b/apps/api/openapi/lib/openapi.libsonnet
index 57b09a92af..f206d6a835 100644
--- a/apps/api/openapi/lib/openapi.libsonnet
+++ b/apps/api/openapi/lib/openapi.libsonnet
@@ -51,6 +51,18 @@
     },
   },
 
+  orderParam():: {
+    name: 'order',
+    'in': 'query',
+    required: false,
+    description: 'Sort order for results',
+    schema: {
+      type: 'string',
+      enum: ['asc', 'desc'],
+      default: 'desc',
+    },
+  },
+
   celParam():: {
     name: 'cel',
     'in': 'query',
diff --git a/apps/api/openapi/openapi.json b/apps/api/openapi/openapi.json
index 3ad5907722..8a46ee07b5 100644
--- a/apps/api/openapi/openapi.json
+++ b/apps/api/openapi/openapi.json
@@ -4784,6 +4784,20 @@
                      "minimum": 0,
                      "type": "integer"
                   }
+               },
+               {
+                  "description": "Sort order for results",
+                  "in": "query",
+                  "name": "order",
+                  "required": false,
+                  "schema": {
+                     "default": "desc",
+                     "enum": [
+                        "asc",
+                        "desc"
+                     ],
+                     "type": "string"
+                  }
                }
             ],
             "responses": {
@@ -8647,7 +8661,7 @@
                "required": true
             },
             "responses": {
-               "202": {
+               "201": {
                   "content": {
                      "application/json": {
                         "schema": {
@@ -8655,7 +8669,7 @@
                         }
                      }
                   },
-                  "description": "Accepted response"
+                  "description": "Resource created successfully"
                },
                "400": {
                   "content": {
diff --git a/apps/api/openapi/paths/deploymentversions.jsonnet b/apps/api/openapi/paths/deploymentversions.jsonnet
index c848ba5a12..3004b59814 100644
--- a/apps/api/openapi/paths/deploymentversions.jsonnet
+++ b/apps/api/openapi/paths/deploymentversions.jsonnet
@@ -10,6 +10,7 @@ local openapi = import '../lib/openapi.libsonnet';
         openapi.deploymentIdParam(),
         openapi.limitParam(),
         openapi.offsetParam(),
+        openapi.orderParam(),
       ],
       responses: openapi.paginatedResponse(openapi.schemaRef('DeploymentVersion'))
                  + openapi.notFoundResponse()
diff --git a/apps/api/src/routes/v1/workspaces/deployments.ts b/apps/api/src/routes/v1/workspaces/deployments.ts
index 3fd21e02c9..227785f19c 100644
--- a/apps/api/src/routes/v1/workspaces/deployments.ts
+++ b/apps/api/src/routes/v1/workspaces/deployments.ts
@@ -3,7 +3,7 @@ import { ApiError, asyncHandler } from "@/types/api.js";
 import { Router } from "express";
 import { v4 as uuidv4 } from "uuid";
 
-import { and, count, eq, inArray, takeFirst } from "@ctrlplane/db";
+import { and, asc, count, desc, eq, inArray, takeFirst } from "@ctrlplane/db";
 import { db } from "@ctrlplane/db/client";
 import {
   enqueueDeploymentPlan,
@@ -291,6 +291,7 @@ const listDeploymentVersions: AsyncTypedHandler<
   const { deploymentId } = req.params;
   const limit = req.query.limit ?? 50;
   const offset = req.query.offset ?? 0;
+  const order = req.query.order ?? "desc";
 
   const [countResult] = await db
     .select({ total: count() })
@@ -303,7 +304,11 @@ const listDeploymentVersions: AsyncTypedHandler<
     .select()
     .from(schema.deploymentVersion)
     .where(eq(schema.deploymentVersion.deploymentId, deploymentId))
-    .orderBy(schema.deploymentVersion.createdAt)
+    .orderBy(
+      order === "asc"
+        ? asc(schema.deploymentVersion.createdAt)
+        : desc(schema.deploymentVersion.createdAt),
+    )
     .limit(limit)
     .offset(offset);
 
diff --git a/apps/api/src/types/openapi.ts b/apps/api/src/types/openapi.ts
index f737765ac3..3cf230ba95 100644
--- a/apps/api/src/types/openapi.ts
+++ b/apps/api/src/types/openapi.ts
@@ -3143,6 +3143,8 @@ export interface operations {
                 limit?: number;
                 /** @description Number of items to skip */
                 offset?: number;
+                /** @description Sort order for results */
+                order?: "asc" | "desc";
             };
             header?: never;
             path: {
@@ -5595,8 +5597,8 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Accepted response */
-            202: {
+            /** @description Resource created successfully */
+            201: {
                 headers: {
                     [name: string]: unknown;
                 };