From 28f60ccea589408dcf70b8514946b077608aaea2 Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Wed, 20 May 2026 12:53:02 -0700
Subject: [PATCH] spec(assets): add cursor pagination params to GET /api/assets

Add 'after' query param and 'next_cursor' response field for keyset
pagination. Matches the cloud Go implementation (BE-893) so frontend
sees a unified contract across runtimes. Offset/limit remain as a
deprecated fallback.
---
 openapi.yaml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/openapi.yaml b/openapi.yaml
index 2658b9b86..d75b84b43 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -1517,6 +1517,19 @@ paths:
           schema:
             type: integer
             default: 0
+          description: |
+            Deprecated in favor of `after` cursor pagination. When both are
+            supplied, `after` wins and `offset` is ignored.
+        - name: after
+          in: query
+          schema:
+            type: string
+          description: |
+            Opaque cursor for keyset pagination. Pass the `next_cursor` value
+            from a previous response to fetch the next page. Stable across
+            inserts/deletes between pages. Supported with `sort` values
+            `created_at`, `updated_at`, `name`, and `size`. Malformed or
+            unsupported cursors return 400 with `INVALID_CURSOR`.
         - name: include_tags
           in: query
           schema:
@@ -6479,6 +6492,11 @@ components:
           type: integer
         has_more:
           type: boolean
+        next_cursor:
+          type: string
+          description: |
+            Opaque cursor to fetch the next page. Pass back as the `after`
+            query parameter. Omitted when there are no more results.
 
     TagInfo:
       type: object