From ef8ed88da4683dea90100b2193af736139d52d5d Mon Sep 17 00:00:00 2001
From: Bryce <blewis@cycle.io>
Date: Thu, 8 Jan 2026 07:54:12 -0800
Subject: [PATCH 1/3] build all builds endpoint

---
 platform/api.yml                           |  4 +-
 platform/paths/stacks/builds/allBuilds.yml | 59 ++++++++++++++++++++++
 2 files changed, 62 insertions(+), 1 deletion(-)
 create mode 100644 platform/paths/stacks/builds/allBuilds.yml

diff --git a/platform/api.yml b/platform/api.yml
index a88fffe7..f7a45239 100644
--- a/platform/api.yml
+++ b/platform/api.yml
@@ -734,6 +734,8 @@ paths:
     $ref: "./paths/stacks/tasks.yml"
 
   ## Stack Builds
+  "/v1/stacks/builds":
+    $ref: "./paths/stacks/builds/allBuilds.yml"
   "/v1/stacks/builds/{buildId}":
     $ref: "./paths/stacks/builds/lookup.yml"
   "/v1/stacks/{stackId}/builds":
@@ -805,4 +807,4 @@ webhooks:
             schema:
               type: array
               items:
-                $ref: ../components/schemas/monitoring/events/Event.yml
\ No newline at end of file
+                $ref: ../components/schemas/monitoring/events/Event.yml
diff --git a/platform/paths/stacks/builds/allBuilds.yml b/platform/paths/stacks/builds/allBuilds.yml
new file mode 100644
index 00000000..3aa4d0b1
--- /dev/null
+++ b/platform/paths/stacks/builds/allBuilds.yml
@@ -0,0 +1,59 @@
+get:
+  operationId: "getAllStackBuilds"
+  summary: List Builds
+  description: Requires the `stacks-view` capability.
+  tags:
+    - Stack Builds
+  parameters:
+    - name: meta
+      in: query
+      required: false
+      description:
+        A comma separated list of meta values. Meta values will show up under a resource's
+        `meta` field. In the case of applying a meta to a collection of resources, each
+        resource will have it's own relevant meta data. In some rare cases, meta may not
+        apply to individual resources, and may appear in the root document. These will be
+        clearly labeled.
+      schema:
+        type: array
+        items:
+          type: string
+          enum:
+            - containers_count
+    - name: filter
+      in: query
+      # Deep nested arrays are undefined https://github.com/OAI/OpenAPI-Specification/issues/1706
+      style: deepObject
+      required: false
+      description: |
+        ## Filter Field 
+        The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for.
+      schema:
+        type: object
+        properties:
+          search:
+            type: string
+            description: |
+              `filter[search]=value` search for a value associated with a field on the given Stack Build(s).
+          state:
+            type: string
+            description: |
+              `filter[state]=value1,value2` state filtering will allow you to filter by the Stack Build's current state.
+    - $ref: ../../../../components/parameters/SortParam.yml
+    - $ref: ../../../../components/parameters/PageParam.yml
+  responses:
+    200:
+      description: Returns a list of Stack Builds.
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - data
+            properties:
+              data:
+                type: array
+                items:
+                  $ref: ../../../../components/schemas/stacks/builds/StackBuild.yml
+    default:
+      $ref: ../../../../components/responses/errors/DefaultError.yml

From 57627da39c3f9a6a48c3f904c9389f8a1ea815ea Mon Sep 17 00:00:00 2001
From: Bryce <blewis@cycle.io>
Date: Thu, 8 Jan 2026 07:55:04 -0800
Subject: [PATCH 2/3] update summary

---
 platform/paths/stacks/builds/allBuilds.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/platform/paths/stacks/builds/allBuilds.yml b/platform/paths/stacks/builds/allBuilds.yml
index 3aa4d0b1..0f209df0 100644
--- a/platform/paths/stacks/builds/allBuilds.yml
+++ b/platform/paths/stacks/builds/allBuilds.yml
@@ -1,6 +1,6 @@
 get:
   operationId: "getAllStackBuilds"
-  summary: List Builds
+  summary: List All Builds
   description: Requires the `stacks-view` capability.
   tags:
     - Stack Builds

From 40ea38cfda829aa7abb48fc4e74b6b1bc70ff4e4 Mon Sep 17 00:00:00 2001
From: Bryce <blewis@cycle.io>
Date: Thu, 8 Jan 2026 09:09:39 -0800
Subject: [PATCH 3/3] cleanup comments

---
 platform/api.yml                                           | 2 +-
 .../paths/stacks/builds/{allBuilds.yml => all-builds.yml}  | 7 +++++--
 2 files changed, 6 insertions(+), 3 deletions(-)
 rename platform/paths/stacks/builds/{allBuilds.yml => all-builds.yml} (91%)

diff --git a/platform/api.yml b/platform/api.yml
index f7a45239..edc9d82b 100644
--- a/platform/api.yml
+++ b/platform/api.yml
@@ -735,7 +735,7 @@ paths:
 
   ## Stack Builds
   "/v1/stacks/builds":
-    $ref: "./paths/stacks/builds/allBuilds.yml"
+    $ref: "./paths/stacks/builds/all-builds.yml"
   "/v1/stacks/builds/{buildId}":
     $ref: "./paths/stacks/builds/lookup.yml"
   "/v1/stacks/{stackId}/builds":
diff --git a/platform/paths/stacks/builds/allBuilds.yml b/platform/paths/stacks/builds/all-builds.yml
similarity index 91%
rename from platform/paths/stacks/builds/allBuilds.yml
rename to platform/paths/stacks/builds/all-builds.yml
index 0f209df0..58bf98db 100644
--- a/platform/paths/stacks/builds/allBuilds.yml
+++ b/platform/paths/stacks/builds/all-builds.yml
@@ -1,7 +1,10 @@
 get:
   operationId: "getAllStackBuilds"
   summary: List All Builds
-  description: Requires the `stacks-view` capability.
+  description: |
+    Fetches all stack builds regardless of their association to a stack.
+
+    Requires the `stacks-view` capability.
   tags:
     - Stack Builds
   parameters:
@@ -43,7 +46,7 @@ get:
     - $ref: ../../../../components/parameters/PageParam.yml
   responses:
     200:
-      description: Returns a list of Stack Builds.
+      description: Returns a list of stack builds.
       content:
         application/json:
           schema: