From 1535a69bda0d166c94aadd6158a227ba77d60c76 Mon Sep 17 00:00:00 2001 From: Viki Harrod Date: Wed, 14 Jan 2026 14:55:37 -0700 Subject: [PATCH 1/8] Add cursor pagination info to /photos endpoint documentation --- openapi.yaml | 48 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index ed69628..01497ec 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1941,14 +1941,28 @@ paths: parameters: - name: page in: query + description: "Page number for offset-based pagination. Cannot be used with cursor pagination (after/before)" schema: type: integer format: int32 - name: per_page in: query + description: "Number of results per page. Default 50, maximum 100" schema: type: integer format: int32 + default: 50 + maximum: 100 + - name: after + in: query + description: "Cursor for forward pagination. Returns results after this cursor position. Cannot be used with 'before' or 'page'" + schema: + type: string + - name: before + in: query + description: "Cursor for backward pagination. Returns results before this cursor position. Cannot be used with 'after' or 'page'" + schema: + type: string - name: start_date in: query description: "A unix timestamp to return photos modified on or after the provided value" @@ -1985,7 +1999,26 @@ paths: format: int64 responses: "200": - description: "List of projects sorted by most recent activity first" + description: "List of photos sorted by captured date descending" + headers: + X-Next-Cursor: + description: "Cursor to fetch the next page of results. Empty if no more results" + schema: + type: string + X-Prev-Cursor: + description: "Cursor to fetch the previous page of results. Empty if no previous results" + schema: + type: string + X-Has-Next: + description: "Indicates whether more results exist after the current page" + schema: + type: string + enum: ["true", "false"] + X-Has-Prev: + description: "Indicates whether results exist before the current page" + schema: + type: string + enum: ["true", "false"] content: application/json: schema: @@ -1993,13 +2026,20 @@ paths: items: $ref: "#/components/schemas/Photo" "400": - description: "Bad Request" + description: "Bad Request. Returned when both 'after' and 'before' cursors are provided, or when cursor pagination is mixed with offset pagination." content: application/json: schema: $ref: "#/components/schemas/Error" - example: - errors: ["Bad Request"] + examples: + both_cursors: + summary: Both cursors provided + value: + errors: ["Cannot use both 'after' and 'before' parameters"] + mixed_pagination: + summary: Mixed pagination types + value: + errors: ["Cannot use cursor pagination with offset pagination"] "404": description: "Not found" content: From 78bf93c6a4b24b7f166c4d6443ce2491c796c924 Mon Sep 17 00:00:00 2001 From: Viki Harrod Date: Wed, 14 Jan 2026 15:04:43 -0700 Subject: [PATCH 2/8] Add missing documentation for project_id query param and photo schema status property --- openapi.yaml | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 01497ec..4181a67 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1973,6 +1973,14 @@ paths: description: "A unix timestamp to return photos modified on or before the provided value" schema: type: string + - name: project_ids + in: query + description: "Filter results to include photos from one of these project IDs" + schema: + type: array + items: + type: integer + format: int64 - name: user_ids in: query description: "Filter results to include photos captured by one of these user IDs" @@ -3474,6 +3482,11 @@ components: "duplicate", ] example: "processed" + status: + type: string + description: "The status of the Photo" + enum: ["active", "deleted"] + example: "active" coordinates: type: array description: "The coordinates where the Photo was captured" From 140223f334e2bec0f1edb3df7a94a240f325373f Mon Sep 17 00:00:00 2001 From: Viki Harrod Date: Wed, 14 Jan 2026 15:05:31 -0700 Subject: [PATCH 3/8] Fix wording issues & return type for photo coordinates --- openapi.yaml | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 4181a67..4317640 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1965,12 +1965,12 @@ paths: type: string - name: start_date in: query - description: "A unix timestamp to return photos modified on or after the provided value" + description: "A unix timestamp to return photos captured on or after the provided value" schema: type: string - name: end_date in: query - description: "A unix timestamp to return photos modified on or before the provided value" + description: "A unix timestamp to return photos captured on or before the provided value" schema: type: string - name: project_ids @@ -1991,7 +1991,7 @@ paths: format: int64 - name: group_ids in: query - description: "Filter results to include photos captured by one of these group IDs" + description: "Filter results to include photos captured by users in one of these group IDs" schema: type: array items: @@ -1999,7 +1999,7 @@ paths: format: int64 - name: tag_ids in: query - description: "Filter results to include photos captured by one of these tag IDs" + description: "Filter results to include photos with one of these tag IDs" schema: type: array items: @@ -3488,10 +3488,8 @@ components: enum: ["active", "deleted"] example: "active" coordinates: - type: array + $ref: "#/components/schemas/Coordinate" description: "The coordinates where the Photo was captured" - items: - $ref: "#/components/schemas/Coordinate" uris: type: array description: "A list of URIs for the different size variants of the photo." From 5c666e24221bbf5458603f82d309cd7097c6927b Mon Sep 17 00:00:00 2001 From: Viki Harrod Date: Thu, 15 Jan 2026 13:12:16 -0700 Subject: [PATCH 4/8] Clarify page param description --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 4317640..d0c99b1 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1941,7 +1941,7 @@ paths: parameters: - name: page in: query - description: "Page number for offset-based pagination. Cannot be used with cursor pagination (after/before)" + description: "Page number for offset-based pagination. Cannot be used with cursor pagination (after/before params)" schema: type: integer format: int32 From 4f138ffe53c7df7ceac1cd7f90657da61bcb0a7b Mon Sep 17 00:00:00 2001 From: Viki Harrod Date: Thu, 15 Jan 2026 16:01:37 -0700 Subject: [PATCH 5/8] Nest Coordinate ref inside allOf property so that description renders --- openapi.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index d0c99b1..0068e74 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3488,8 +3488,9 @@ components: enum: ["active", "deleted"] example: "active" coordinates: - $ref: "#/components/schemas/Coordinate" description: "The coordinates where the Photo was captured" + allOf: + - $ref: "#/components/schemas/Coordinate" uris: type: array description: "A list of URIs for the different size variants of the photo." From 752302449607c10f0215691ae637ca477a4ed42d Mon Sep 17 00:00:00 2001 From: Viki Harrod Date: Thu, 15 Jan 2026 16:05:15 -0700 Subject: [PATCH 6/8] Make relationship between cursor headers and params more explicit --- openapi.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 0068e74..9057363 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1955,12 +1955,12 @@ paths: maximum: 100 - name: after in: query - description: "Cursor for forward pagination. Returns results after this cursor position. Cannot be used with 'before' or 'page'" + description: "Cursor for forward pagination. Comes from X-Next-Cursor header value. Returns results after this cursor position. Cannot be used with 'before' or 'page'" schema: type: string - name: before in: query - description: "Cursor for backward pagination. Returns results before this cursor position. Cannot be used with 'after' or 'page'" + description: "Cursor for backward pagination. Comes from X-Prev-Cursor header value. Returns results before this cursor position. Cannot be used with 'after' or 'page'" schema: type: string - name: start_date @@ -2010,11 +2010,11 @@ paths: description: "List of photos sorted by captured date descending" headers: X-Next-Cursor: - description: "Cursor to fetch the next page of results. Empty if no more results" + description: "Cursor that can be used as an 'after' param to fetch the next page of results. Empty if no more results" schema: type: string X-Prev-Cursor: - description: "Cursor to fetch the previous page of results. Empty if no previous results" + description: "Cursor that can be used as a 'before' param to fetch the previous page of results. Empty if no previous results" schema: type: string X-Has-Next: From 86bd72a3f48a93049d7575518703f3a2c431f822 Mon Sep 17 00:00:00 2001 From: Viki Harrod Date: Wed, 21 Jan 2026 10:40:16 -0700 Subject: [PATCH 7/8] Remove pagination-specific language from bad request description --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 9057363..b3ae533 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2034,7 +2034,7 @@ paths: items: $ref: "#/components/schemas/Photo" "400": - description: "Bad Request. Returned when both 'after' and 'before' cursors are provided, or when cursor pagination is mixed with offset pagination." + description: "Bad Request" content: application/json: schema: From 6f0df01d9647fbb542c9f1a5c6fedc9ffc5bc4fa Mon Sep 17 00:00:00 2001 From: Viki Harrod Date: Mon, 23 Feb 2026 17:17:28 -0700 Subject: [PATCH 8/8] Add cursor pagination to /projects/:project_id/photos endpoint docs Co-Authored-By: Claude Sonnet 4.6 --- openapi.yaml | 43 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 5 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index b3ae533..fc7b235 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -827,22 +827,36 @@ paths: format: id - name: page in: query + description: "Page number for offset-based pagination. Cannot be used with cursor pagination (after/before params)" schema: type: integer format: int32 - name: per_page in: query + description: "Number of results per page. Default 50, maximum 100" schema: type: integer format: int32 + default: 50 + maximum: 100 + - name: after + in: query + description: "Cursor for forward pagination. Comes from X-Next-Cursor header value. Returns results after this cursor position. Cannot be used with 'before' or 'page'" + schema: + type: string + - name: before + in: query + description: "Cursor for backward pagination. Comes from X-Prev-Cursor header value. Returns results before this cursor position. Cannot be used with 'after' or 'page'" + schema: + type: string - name: start_date in: query - description: "A unix timestamp to return photos modified on or after the provided value" + description: "A unix timestamp to return photos captured on or after the provided value" schema: type: string - name: end_date in: query - description: "A unix timestamp to return photos modified on or before the provided value" + description: "A unix timestamp to return photos captured on or before the provided value" schema: type: string - name: user_ids @@ -855,7 +869,7 @@ paths: format: int64 - name: group_ids in: query - description: "Filter results to include photos captured by one of these group IDs" + description: "Filter results to include photos captured by users in one of these group IDs" schema: type: array items: @@ -863,7 +877,7 @@ paths: format: int64 - name: tag_ids in: query - description: "Filter results to include photos captured by one of these tag IDs" + description: "Filter results to include photos with one of these tag IDs" schema: type: array items: @@ -871,7 +885,26 @@ paths: format: int64 responses: "200": - description: "List of projects sorted by most recent activity first" + description: "List of photos sorted by captured date descending" + headers: + X-Next-Cursor: + description: "Cursor that can be used as an 'after' param to fetch the next page of results. Empty if no more results" + schema: + type: string + X-Prev-Cursor: + description: "Cursor that can be used as a 'before' param to fetch the previous page of results. Empty if no previous results" + schema: + type: string + X-Has-Next: + description: "Indicates whether more results exist after the current page" + schema: + type: string + enum: ["true", "false"] + X-Has-Prev: + description: "Indicates whether results exist before the current page" + schema: + type: string + enum: ["true", "false"] content: application/json: schema: