From 9ac6b460db6dccea25a0a0d1b0550cd1851c5a93 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= <johan@topsort.com>
Date: Tue, 11 Nov 2025 11:57:43 +0000
Subject: [PATCH 1/9] chore: reduce linting warnings

- Add additional descriptions
- Add missing discriminators for example responses
- Improve existing and add new examples

This takes us about 20 warnings a a few notices down.
---
 topsort-api-v2.yml | 57 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 43 insertions(+), 14 deletions(-)

diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
index 2e8ff39..07bcf1d 100644
--- a/topsort-api-v2.yml
+++ b/topsort-api-v2.yml
@@ -84,14 +84,16 @@ paths:
                   - results
                 examples:
                   - results:
-                      - winners:
+                      - resultType: listings
+                        winners:
                           - rank: 1
                             type: product
                             id: p_Mfk11
                             resolvedBidId: WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0==
                             campaignId: 82588593-85c5-47c0-b125-07e315b7f2b3
                         error: false
-                      - winners:
+                      - resultType: listings
+                        winners:
                           - rank: 1
                             type: product
                             id: p_Mfk15
@@ -103,9 +105,10 @@ paths:
                             resolvedBidId: WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
                             campaignId: a72e4e43-55b5-4d08-81bb-cbb57df59c72
                         error: false
-                      - winners:
+                      - resultType: banners
+                        winners:
                           - rank: 1
-                            type: product
+                            type: banner
                             id: p_PJbnN
                             resolvedBidId: WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd
                             campaignId: 1156ef4e-0109-4190-ac97-4436c82358d2
@@ -120,7 +123,8 @@ paths:
                                   heroImageAltText: "Topsort product image"
                         error: false
                   - results:
-                      - winners: []
+                      - resultType: 
+                        winners: []
                         error: false
         "400":
           $ref: "#/components/responses/BadRequest"
@@ -155,11 +159,11 @@ paths:
       responses:
         "201":
           description: >
-            The auction results. The list of winners will contain at most `winners` entries per
-            auction. It may contain fewer or no entries at all if there aren't enough products with
-            usable bids, that is, a bid amount greater than the reserve price and belonging to a
-            campaign with enough remaining budget. Bids become unusable if campaign budget is
-            exhausted, the bid is disqualified to preserve spend pacing, etc.
+            The sponsored brand auction results. The list of winners will contain at most `winners`
+            entries per auction. It may contain fewer or no entries at all if there aren't enough
+            products with usable bids, that is, a bid amount greater than the reserve price and
+            belonging to a campaign with enough remaining budget. Bids become unusable if campaign
+            budget is exhausted, the bid is disqualified to preserve spend pacing, etc.
           content:
             application/json:
               schema:
@@ -242,7 +246,7 @@ paths:
       responses:
         "201":
           description: >
-            The auction results. The list of winners will contain at most `winners` entries per
+            The travel auction results. The list of winners will contain at most `winners` entries per
             auction. It may contain fewer or no entries at all if there aren't enough products with
             usable bids, that is, a bid amount greater than the reserve price and belonging to a
             campaign with enough remaining budget. Bids become unusable if campaign budget is
@@ -918,6 +922,7 @@ components:
               - p_ojng4
     PredictionRequest:
       type: object
+      description: Request to predict the outcome of an interaction.
       properties:
         metrics:
           type: object
@@ -963,6 +968,7 @@ components:
         - objectType
         - opaqueUserId
     RetrievalRequest:
+      description: Request to retrieve objects based on context.
       type: object
       properties:
         slots:
@@ -989,9 +995,9 @@ components:
           type: array
           items:
             type: string
-          examples:
-            - p_1234
-            - p_5678
+            examples:
+              - p_1234
+              - p_5678
         mode:
           type: string
           description: Retrieval mode, how to interpret the context to get objects.
@@ -1020,13 +1026,28 @@ components:
         mapping:
           listings: "#/components/schemas/SponsoredListingsAuctionResult"
           banners: "#/components/schemas/BannersAuctionResult"
+          empty: "#/components/schemas/EmptyAuctionResult"
       oneOf:
         - $ref: "#/components/schemas/SponsoredListingsAuctionResult"
         - $ref: "#/components/schemas/BannersAuctionResult"
+        - $ref: "#/components/schemas/EmptyAuctionResult"
     TravelAuctionResult:
       oneOf:
         - $ref: "#/components/schemas/HotelsAuctionResult"
         - $ref: "#/components/schemas/FlightsAuctionResult"
+        - $ref: "#/components/schemas/EmptyAuctionResult"
+    EmptyAuctionResult:
+      type: object
+      properties:
+        resultType:
+          type: string
+        winners:
+          type: array
+          maxItems: 0
+        error:
+          type: boolean
+          examples:
+            - false
     BannersAuctionResult:
       type: object
       properties:
@@ -1907,6 +1928,8 @@ components:
             type: string
             minLength: 1
             description: A category ID.
+            examples:
+              - "cat1953"
           description: >
             An array of IDs of the categories associated to the page in which this event occurred,
             if applicable. These IDs must match the IDs provided through the catalog service.
@@ -1918,6 +1941,8 @@ components:
             applicable. This search string must match the searchQuery field that was provided in the
             auction request (if provided).
           minLength: 1
+          examples:
+            - "blue shoes"
     EventEntity:
       type: object
       description: >
@@ -1934,12 +1959,16 @@ components:
           type: string
           description: The marketplace's ID of the entity associated with the interaction.
           minLength: 1
+          examples:
+            - ean-512385132
         type:
           type: string
           description: The type of entity associated with the interaction.
           enum:
             - product
             - vendor
+          examples:
+            - product
     EventsRequest:
       type: object
       additionalProperties: false

From d1fc0bb6b2fcb718d6dc7bbb4431b743f43657a1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= <johan@topsort.com>
Date: Tue, 11 Nov 2025 12:01:00 +0000
Subject: [PATCH 2/9] fix: wrong response type

---
 topsort-api-v2.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
index 07bcf1d..9466ae3 100644
--- a/topsort-api-v2.yml
+++ b/topsort-api-v2.yml
@@ -108,7 +108,7 @@ paths:
                       - resultType: banners
                         winners:
                           - rank: 1
-                            type: banner
+                            type: product
                             id: p_PJbnN
                             resolvedBidId: WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd
                             campaignId: 1156ef4e-0109-4190-ac97-4436c82358d2

From 07204689b52977bcb52efbe6648a8341e5055302 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= <johan@topsort.com>
Date: Tue, 11 Nov 2025 14:36:30 +0000
Subject: [PATCH 3/9] fix: prettier

---
 topsort-api-v2.yml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
index 9466ae3..5a68ccb 100644
--- a/topsort-api-v2.yml
+++ b/topsort-api-v2.yml
@@ -123,7 +123,7 @@ paths:
                                   heroImageAltText: "Topsort product image"
                         error: false
                   - results:
-                      - resultType: 
+                      - resultType:
                         winners: []
                         error: false
         "400":
@@ -246,10 +246,10 @@ paths:
       responses:
         "201":
           description: >
-            The travel auction results. The list of winners will contain at most `winners` entries per
-            auction. It may contain fewer or no entries at all if there aren't enough products with
-            usable bids, that is, a bid amount greater than the reserve price and belonging to a
-            campaign with enough remaining budget. Bids become unusable if campaign budget is
+            The travel auction results. The list of winners will contain at most `winners` entries
+            per auction. It may contain fewer or no entries at all if there aren't enough products
+            with usable bids, that is, a bid amount greater than the reserve price and belonging to
+            a campaign with enough remaining budget. Bids become unusable if campaign budget is
             exhausted, the bid is disqualified to preserve spend pacing, etc.
           content:
             application/json:

From 8a3c339b9706762d99624816bab8d5315a49e2f4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= <johan@topsort.com>
Date: Fri, 14 Nov 2025 12:28:30 +0000
Subject: [PATCH 4/9] chore: additional fixes

---
 topsort-api-v2.yml | 141 ++++++++++++++++++++++-----------------------
 1 file changed, 70 insertions(+), 71 deletions(-)

diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
index 5a68ccb..36067d7 100644
--- a/topsort-api-v2.yml
+++ b/topsort-api-v2.yml
@@ -123,7 +123,7 @@ paths:
                                   heroImageAltText: "Topsort product image"
                         error: false
                   - results:
-                      - resultType:
+                      - resultType: listings
                         winners: []
                         error: false
         "400":
@@ -566,6 +566,7 @@ components:
             $ref: "#/components/schemas/Error"
   schemas:
     AuctionCategory:
+      description: Represents one or more categories for auction targeting. Can be a single category, multiple categories, or category disjunctions.
       oneOf:
         - $ref: "#/components/schemas/SingleCategory"
         - type: object
@@ -588,8 +589,7 @@ components:
                 minLength: 1
               minItems: 1
               examples:
-                - c_men_clothing
-                - c_shoes
+                - ["c_men_clothing", "c_shoes"]
         - type: object
           title: Category Disjunctions
           description: Multiple disjunctions of categories for the purpose of running an auction.
@@ -609,8 +609,7 @@ components:
               minItems: 1
               maxItems: 5
               examples:
-                - c_red
-                - c_blue
+                - [["c_red"], ["c_blue"]]
     SingleCategory:
       type: object
       title: Single Category
@@ -653,6 +652,7 @@ components:
       examples:
         - mobile
     Page:
+      description: Information about the page where an auction or event occurs.
       type: object
       title: Page
       required:
@@ -912,6 +912,10 @@ components:
         - type: listings
           slots: 10
           pageSize: 10
+          page:
+            type: category
+            value: sneakers
+          opaqueUserId: u_9ske45
           category:
             ids:
               - sneakers
@@ -960,8 +964,7 @@ components:
           productIds:
             - p_PJbnN
             - p_ojng4
-          objectType:
-            - listings
+          objectType: listings
       required:
         - metrics
         - productIds
@@ -1013,8 +1016,8 @@ components:
             - p_PJbnN
             - p_ojng4
           mode: all
-          deviceType:
-            - mobile
+          objectType: listings
+          deviceType: mobile
       required:
         - slots
         - seedProductIds
@@ -1032,11 +1035,13 @@ components:
         - $ref: "#/components/schemas/BannersAuctionResult"
         - $ref: "#/components/schemas/EmptyAuctionResult"
     TravelAuctionResult:
+      description: The result of a travel-related auction request (hotels or flights).
       oneOf:
         - $ref: "#/components/schemas/HotelsAuctionResult"
         - $ref: "#/components/schemas/FlightsAuctionResult"
         - $ref: "#/components/schemas/EmptyAuctionResult"
     EmptyAuctionResult:
+      description: An auction result with no winners, typically when no eligible bids are available.
       type: object
       properties:
         resultType:
@@ -1045,10 +1050,9 @@ components:
           type: array
           maxItems: 0
         error:
-          type: boolean
-          examples:
-            - false
+          $ref: "#/components/schemas/ErrorFlag"
     BannersAuctionResult:
+      description: The result of a banner auction, containing winning banner ads.
       type: object
       properties:
         resultType:
@@ -1061,15 +1065,13 @@ components:
             Array of winner objects in order from highest to lowest bid. It will be empty if there
             were no qualifying bids or if there was an error.
         error:
-          type: boolean
-          description: A boolean indicating whether this auction was resolved successfully.
-          examples:
-            - false
+          $ref: "#/components/schemas/ErrorFlag"
       required:
         - winners
         - error
         - resultType
     SponsoredListingsAuctionResult:
+      description: The result of a sponsored listings auction, containing winning product listings.
       type: object
       properties:
         resultType:
@@ -1082,15 +1084,13 @@ components:
             Array of winner objects in order from highest to lowest bid. It will be empty if there
             were no qualifying bids or if there was an error.
         error:
-          type: boolean
-          description: A boolean indicating whether this auction was resolved successfully.
-          examples:
-            - false
+          $ref: "#/components/schemas/ErrorFlag"
       required:
         - winners
         - error
         - resultType
     SponsoredListingsWinner:
+      description: A winning bid in a sponsored listings auction with product and campaign details.
       type: object
       required:
         - rank
@@ -1100,13 +1100,7 @@ components:
         - campaignId
       properties:
         rank:
-          type: integer
-          format: int32
-          description: >
-            Where the product's bid ranked in the auction. One-based, so the product with rank 1 won
-            the auction. In an auction response, the winners array is sorted so rank will match the
-            entry's index.
-          minimum: 1
+          $ref: "#/components/schemas/WinnerRank"
         type:
           type: string
           description: The target type of the winning bid.
@@ -1124,10 +1118,7 @@ components:
         resolvedBidId:
           $ref: "#/components/schemas/ResolvedBidID"
         campaignId:
-          type: string
-          description: The ID of the campaign that won the auction.
-          examples:
-            - 4bcc6093-f367-4df2-aa1b-7c1674dd6441
+          $ref: "#/components/schemas/CampaignId"
     SponsoredBrandContent:
       type: object
       additionalProperties: true
@@ -1139,6 +1130,7 @@ components:
           brandName: "Topsort Brand"
           creative: "https://some.url.com/rocks.jpeg"
     BannersWinner:
+      description: A winning bid in a banner auction with asset and campaign details.
       type: object
       required:
         - rank
@@ -1148,13 +1140,7 @@ components:
         - asset
       properties:
         rank:
-          type: integer
-          format: int32
-          description: >
-            Where the product's bid ranked in the auction. One-based, so the product with rank 1 won
-            the auction. In an auction response, the winners array is sorted so rank will match the
-            entry's index.
-          minimum: 1
+          $ref: "#/components/schemas/WinnerRank"
         type:
           type: string
           description: The target type of the winning bid.
@@ -1172,10 +1158,7 @@ components:
         resolvedBidId:
           $ref: "#/components/schemas/ResolvedBidID"
         campaignId:
-          type: string
-          description: The ID of the campaign that won the auction.
-          examples:
-            - 4bcc6093-f367-4df2-aa1b-7c1674dd6441
+          $ref: "#/components/schemas/CampaignId"
         asset:
           description: The list of available sources for a banner.
           type: array
@@ -1183,8 +1166,10 @@ components:
             $ref: "#/components/schemas/AssetSource"
           minItems: 1
     HotelsAuctionResult:
+      description: The result of a hotels travel auction.
       $ref: "#/components/schemas/SponsoredListingsAuctionResult"
     FlightsAuctionResult:
+      description: The result of a flights travel auction, containing winning flight products.
       type: object
       properties:
         resultType:
@@ -1197,15 +1182,13 @@ components:
             Array of winner objects in order from highest to lowest bid. It will be empty if there
             were no qualifying bids or if there was an error.
         error:
-          type: boolean
-          description: A boolean indicating whether this auction was resolved successfully.
-          examples:
-            - false
+          $ref: "#/components/schemas/ErrorFlag"
       required:
         - winners
         - error
         - resultType
     FlightsWinner:
+      description: A winning bid in a flights auction with flights and campaign details.
       type: object
       required:
         - rank
@@ -1216,13 +1199,7 @@ components:
         - variationID
       properties:
         rank:
-          type: integer
-          format: int32
-          description: >
-            Where the product's bid ranked in the auction. One-based, so the product with rank 1 won
-            the auction. In an auction response, the winners array is sorted so rank will match the
-            entry's index.
-          minimum: 1
+          $ref: "#/components/schemas/WinnerRank"
         type:
           type: string
           description: The target type of the winning bid.
@@ -1231,21 +1208,19 @@ components:
         id:
           type: string
           description:
-            The marketplace's ID of the winning flight product, depending on the target of the
+            The marketplace's ID of the winning flight, depending on the target of the
             campaign.
           examples:
             - p_Mfk15
         resolvedBidId:
           $ref: "#/components/schemas/ResolvedBidID"
         campaignId:
-          type: string
-          description: The ID of the campaign that won the auction.
-          examples:
-            - 4bcc6093-f367-4df2-aa1b-7c1674dd6441
+          $ref: "#/components/schemas/CampaignId"
         variationID:
           type: string
-          description: The marketplace's ID for the winning flight product's variation.
+          description: The marketplace's ID for the winning flight's variation.
     RankingResult:
+      description: The result of a ranking request, containing ordered products.
       type: object
       properties:
         resultType:
@@ -1257,15 +1232,13 @@ components:
           description: |
             Array of ranking objects in order from highest to lowest relevancy.
         error:
-          type: boolean
-          description: A boolean indicating whether this auction was resolved successfully.
-          examples:
-            - false
+          $ref: "#/components/schemas/ErrorFlag"
       required:
         - results
         - error
         - resultType
     RankingWinner:
+      description: A ranked item from a ranking request with position and type information.
       type: object
       required:
         - rank
@@ -1296,6 +1269,7 @@ components:
           examples:
             - WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
     PredictionResult:
+      description: The result of a prediction request, containing CTR and CVR predictions for products.
       type: object
       properties:
         objectType:
@@ -1338,6 +1312,7 @@ components:
         - objectType
         - predictions
     RetrievalResults:
+      description: The result of a retrieval request, containing relevant objects with scores.
       type: object
       properties:
         objectType:
@@ -1557,6 +1532,7 @@ components:
               geoTargeting: New York
               opaqueUserId": user-123
     SponsoredBrandAuctionResult:
+      description: The result of a sponsored brand auction, containing winning brand promotions.
       type: object
       properties:
         winners:
@@ -1567,10 +1543,7 @@ components:
             Array of winner objects in order from highest to lowest bid. It will be empty if there
             were no qualifying bids or if there was an error.
         error:
-          type: boolean
-          description: A boolean indicating whether this auction was resolved successfully.
-          examples:
-            - false
+          $ref: "#/components/schemas/ErrorFlag"
       required:
         - winners
         - error
@@ -1602,6 +1575,7 @@ components:
                   productIds: ["nonfat_vanilla_yogurt", "nonfat_strawberry_yogurt"]
               error: false
     SponsoredBrandWinner:
+      description: A winning bid in a sponsored brand auction with brand and campaign details.
       type: object
       required:
         - rank
@@ -1698,6 +1672,7 @@ components:
         travelContext:
           $ref: "#/components/schemas/HotelsTravelContext"
     HotelsTravelProduct:
+      description: A hotel product that can participate in a travel auction.
       type: object
       required:
         - id
@@ -1720,6 +1695,7 @@ components:
             participating products. If not given it will default to 1.
             Values must be between 0 and 1.
     BaseTravelContext:
+      description: Base context information for travel-related auctions including dates, location, and traveler details.
       type: object
       required:
         - site
@@ -1764,6 +1740,7 @@ components:
           type: string
           description: Platform e.g. "app", "mobile", "web", ...
     HotelsTravelContext:
+      description: Context information specific to hotel travel auctions.
       allOf:
         - $ref: "#/components/schemas/BaseTravelContext"
     FlightsAuctionRequest:
@@ -1788,27 +1765,28 @@ components:
           maximum: 40
         products:
           type: array
-          description: An array of flight products that should participate in the auction.
+          description: An array of flights that should participate in the auction.
           items:
             $ref: "#/components/schemas/FlightsTravelProduct"
         travelContext:
           $ref: "#/components/schemas/FlightsTravelContext"
     FlightsTravelProduct:
+      description: A flight that can participate in a travel auction.
       type: object
       required:
         - id
       properties:
         id:
           type: string
-          description: ID to identify flight product.
+          description: ID to identify a flight.
           examples:
             - L0_SAO-ORL
         variationID:
           type: string
-          description: ID to identify flight product variation.
+          description: ID to identify flights variation.
         price:
           type: number
-          description: Flight product variation total price in marketplace currency.
+          description: Flight variation total price in marketplace currency.
         qualityScore:
           type: number
           maximum: 1
@@ -1822,6 +1800,7 @@ components:
             participating products. If not given it will default to 1.
             Values must be between 0 and 1.
     FlightsTravelContext:
+      description: Context information specific to flight travel auctions including route and flight type.
       allOf:
         - $ref: "#/components/schemas/BaseTravelContext"
         - type: object
@@ -1833,6 +1812,7 @@ components:
               type: string
               description: Flight type e.g. "round_trip", "one_way", ...
     Error:
+      description: Error response object containing error code, message, and documentation URL.
       type: object
       required:
         - errCode
@@ -1883,6 +1863,7 @@ components:
           examples:
             - could not find the provided resolved bid id
     Placement:
+      description: Information about where an ad or product is placed on a page.
       type: object
       required:
         - path
@@ -1970,6 +1951,7 @@ components:
           examples:
             - product
     EventsRequest:
+      description: A batch request containing multiple events to be reported to Topsort.
       type: object
       additionalProperties: false
       properties:
@@ -2231,6 +2213,7 @@ components:
           examples:
             - onsite
     PurchaseItem:
+      description: An item included in a purchase transaction with product, quantity, and pricing details.
       type: object
       required:
         - productId
@@ -2316,6 +2299,22 @@ components:
             - instore
           examples:
             - onsite
+    WinnerRank:
+      type: integer
+      format: int32
+      description: The rank/position of this winner in the auction results, with 1 being the highest.
+      minimum: 1
+    CampaignId:
+      type: string
+      description: The ID of the campaign that won the auction.
+      examples:
+        - 82588593-85c5-47c0-b125-07e315b7f2b3
+    ErrorFlag:
+      type: boolean
+      description: A boolean indicating whether this auction was resolved successfully.
+      examples:
+        - false
+        - true
   securitySchemes:
     HTTPBearer:
       description: A valid API key generated in Topsort's UI.

From 8f7bbe8e5d09909a5023cb0c4147e25eb0bf3f42 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= <johan@topsort.com>
Date: Fri, 14 Nov 2025 12:29:47 +0000
Subject: [PATCH 5/9] chore: lint

---
 topsort-api-v2.yml | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
index 36067d7..95c3f07 100644
--- a/topsort-api-v2.yml
+++ b/topsort-api-v2.yml
@@ -566,7 +566,9 @@ components:
             $ref: "#/components/schemas/Error"
   schemas:
     AuctionCategory:
-      description: Represents one or more categories for auction targeting. Can be a single category, multiple categories, or category disjunctions.
+      description:
+        Represents one or more categories for auction targeting. Can be a single category, multiple
+        categories, or category disjunctions.
       oneOf:
         - $ref: "#/components/schemas/SingleCategory"
         - type: object
@@ -1208,8 +1210,7 @@ components:
         id:
           type: string
           description:
-            The marketplace's ID of the winning flight, depending on the target of the
-            campaign.
+            The marketplace's ID of the winning flight, depending on the target of the campaign.
           examples:
             - p_Mfk15
         resolvedBidId:
@@ -1269,7 +1270,8 @@ components:
           examples:
             - WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
     PredictionResult:
-      description: The result of a prediction request, containing CTR and CVR predictions for products.
+      description:
+        The result of a prediction request, containing CTR and CVR predictions for products.
       type: object
       properties:
         objectType:
@@ -1695,7 +1697,9 @@ components:
             participating products. If not given it will default to 1.
             Values must be between 0 and 1.
     BaseTravelContext:
-      description: Base context information for travel-related auctions including dates, location, and traveler details.
+      description:
+        Base context information for travel-related auctions including dates, location, and traveler
+        details.
       type: object
       required:
         - site
@@ -1800,7 +1804,8 @@ components:
             participating products. If not given it will default to 1.
             Values must be between 0 and 1.
     FlightsTravelContext:
-      description: Context information specific to flight travel auctions including route and flight type.
+      description:
+        Context information specific to flight travel auctions including route and flight type.
       allOf:
         - $ref: "#/components/schemas/BaseTravelContext"
         - type: object
@@ -2213,7 +2218,8 @@ components:
           examples:
             - onsite
     PurchaseItem:
-      description: An item included in a purchase transaction with product, quantity, and pricing details.
+      description:
+        An item included in a purchase transaction with product, quantity, and pricing details.
       type: object
       required:
         - productId
@@ -2302,7 +2308,8 @@ components:
     WinnerRank:
       type: integer
       format: int32
-      description: The rank/position of this winner in the auction results, with 1 being the highest.
+      description:
+        The rank/position of this winner in the auction results, with 1 being the highest.
       minimum: 1
     CampaignId:
       type: string

From c860c375eeb173dc806c273cdad1f61dae082fa5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= <johan@topsort.com>
Date: Fri, 14 Nov 2025 12:41:07 +0000
Subject: [PATCH 6/9] fix: go to _zero_ redocly warnings

One poor example indentation and the rest is missing propreties
in examples
---
 topsort-api-v2.yml | 89 +++++++++++++++++++++++++++-------------------
 1 file changed, 52 insertions(+), 37 deletions(-)

diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
index 95c3f07..565bfd8 100644
--- a/topsort-api-v2.yml
+++ b/topsort-api-v2.yml
@@ -220,7 +220,8 @@ paths:
                           qualityScore: 0.7
                         - id: hotel-2
                       category:
-                        id: hotel-boutique
+                        SingleCategory:
+                          id: hotel-boutique
                       travelContext:
                         travelStartDate: "2025-01-01"
                         travelEndDate: "2025-01-15"
@@ -269,25 +270,31 @@ paths:
                       - resultType: hotels
                         winners:
                           - rank: 1
+                            type: product
                             id: hotel-1
                             resolvedBidId: ChAHd-K97Xs8MNRELdY9VCeJFiBCk1_aEYz8eb-WZqyhzL4EFhBCk5Mt_X2_b8Yu_vXJgzPWJhVLBTFRBTGssk9
                             campaignId: 8b816367-da17-4c65-9a26-391edf01a10d
                           - rank: 2
+                            type: product
                             id: hotel-2
                             resolvedBidId: ChAJe-M23Yr5QPTEFdX7VBgJGhCDm2_wDXy6cb-XZpxjxK6GHhCDm3Ku_W1_c9Zw_wYHfzQYKjTLBVGQBTLttu6
                             campaignId: 7be0d8c8-243c-41af-bb43-b43ef4935672
+                        error: false
                       - resultType: flights
                         winners:
                           - rank: 1
+                            type: product
                             id: L0_SAO-ORL
                             resolvedBidId: ChAKf-N45Vq3LOTEGcW9VDhKHjADk3_zCXx8db-XZsyiwM2HIjADk4Lr_X0_b9Xw_uKHgyRZKhUKCTHQCTHrrh7
                             campaignId: 8ab7b29e-1934-4ec9-ad87-60c285bc7f38
                             variationID: "002"
                           - rank: 2
+                            type: product
                             id: L0_SAO-ORL
                             resolvedBidId: ChAGg-P56Wu4MRUEHdX8VEfLHkBEk4_aEXz9fb-YZtxjwN3IJkBEk5Ms_W2_c8Yx_vZJhzSXKlVLDUJQDUJssl8
                             campaignId: cb8ed0a7-0ecf-4ffb-a863-022f862649ec
                             variationID: "001"
+                        error: false
         "400":
           $ref: "#/components/responses/BadRequest"
         "401":
@@ -424,6 +431,11 @@ paths:
                     - type: listings
                       slots: 3
                       pageSize: 3
+                      page:
+                        type: category
+                        value: sneakers
+                        pageId: /category/sneakers
+                      opaqueUserId: u_9ske45
                       category:
                         ids:
                           - sneakers
@@ -454,7 +466,8 @@ paths:
                   - results
                 examples:
                   - results:
-                      - products:
+                      - resultType: listings
+                        results:
                           - rank: 1
                             type: organic
                             id: p_Mfk11
@@ -917,6 +930,7 @@ components:
           page:
             type: category
             value: sneakers
+            pageId: /category/sneakers
           opaqueUserId: u_9ske45
           category:
             ids:
@@ -1298,9 +1312,9 @@ components:
                 description: Conversion Rate prediction.
           description: Predicted objects
           examples:
-            - productId: product-123
-              ctr: 0.05
-              cvr: 0.101
+            - - productId: product-123
+                ctr: 0.05
+                cvr: 0.101
       examples:
         - objectType: listings
           predictions:
@@ -1336,15 +1350,14 @@ components:
                 description: Relevance score for the retrieved products.
           description: Retrieved objects.
       examples:
-        - objectType: listing
+        - objectType: listings
           objects:
             - id: p_xh90s
-              value: 0.978
+              score: 0.978
             - id: p_12lp0
-              value: 0.953
+              score: 0.953
             - id: p_ds7ui
-              value: 0.877
-          error: false
+              score: 0.877
       required:
         - objectType
         - objects
@@ -1508,31 +1521,31 @@ components:
         page:
           $ref: "#/components/schemas/Page"
       examples:
-        - auctions:
-            - winners: 2
-              placementId: some-placement
-              triggers:
-                products:
-                  ids:
-                    - "vanilla_yogurt"
-                    - "nonfat_vanilla_yogurt"
-              geoTargeting: New York
-              opaqueUserId": user-123
-        - auctions:
-            - winners: 2
-              placementId: some-placement
-              triggers:
-                category:
-                  id: c_yogurt
-              geoTargeting: New York
-              opaqueUserId": user-123
-        - auctions:
-            - winners: 2
-              placementId: some-placement
-              triggers:
-                searchQuery: vanilla yogurt
-              geoTargeting: New York
-              opaqueUserId": user-123
+        - winners: 2
+          placementId: some-placement
+          triggers:
+            products:
+              ids:
+                - "vanilla_yogurt"
+                - "nonfat_vanilla_yogurt"
+          geoTargeting:
+            location: New York
+          opaqueUserId: user-123
+        - winners: 2
+          placementId: some-placement
+          triggers:
+            category:
+              id: c_yogurt
+          geoTargeting:
+            location: New York
+          opaqueUserId: user-123
+        - winners: 2
+          placementId: some-placement
+          triggers:
+            searchQuery: vanilla yogurt
+          geoTargeting:
+            location: New York
+          opaqueUserId: user-123
     SponsoredBrandAuctionResult:
       description: The result of a sponsored brand auction, containing winning brand promotions.
       type: object
@@ -2002,7 +2015,8 @@ components:
                 position: 1
                 page: 1
                 pageSize: 15
-                categoryId: 9BLIe
+                categoryIds:
+                  - 9BLIe
               resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
               deviceType: mobile
               channel: onsite
@@ -2015,7 +2029,8 @@ components:
                 position: 1
                 page: 1
                 pageSize: 15
-                categoryId: 9BLIe
+                categoryIds:
+                  - 9BLIe
               resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
               deviceType: mobile
               channel: offsite

From c6254701cacf4601e45bfed298856e4c27e34433 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= <johan@topsort.com>
Date: Fri, 14 Nov 2025 13:06:19 +0000
Subject: [PATCH 7/9] fix: additional fixes

---
 topsort-api-v2.yml | 143 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 112 insertions(+), 31 deletions(-)

diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
index 565bfd8..f93ed45 100644
--- a/topsort-api-v2.yml
+++ b/topsort-api-v2.yml
@@ -51,6 +51,14 @@ paths:
           will compete against each other.
         content:
           application/json:
+            example:
+              auctions:
+                - type: listings
+                  slots: 2
+                  products:
+                    ids:
+                      - p_PJbnN
+                      - p_ojng4
             schema:
               type: object
               properties:
@@ -60,6 +68,12 @@ paths:
                     $ref: "#/components/schemas/AuctionRequest"
                   minItems: 1
                   maxItems: 5
+                  example:
+                    - type: listings
+                      slots: 2
+                      products:
+                        ids:
+                          - p_PJbnN
         required: true
       responses:
         "201":
@@ -80,6 +94,10 @@ paths:
                       $ref: "#/components/schemas/AuctionResult"
                     minItems: 1
                     maxItems: 5
+                    example:
+                      - resultType: listings
+                        winners: []
+                        error: false
                 required:
                   - results
                 examples:
@@ -144,6 +162,14 @@ paths:
           compete against each other.
         content:
           application/json:
+            example:
+              auctions:
+                - winners: 2
+                  placementId: some-placement
+                  triggers:
+                    products:
+                      ids:
+                        - vanilla_yogurt
             schema:
               type: object
               properties:
@@ -153,6 +179,13 @@ paths:
                     $ref: "#/components/schemas/SponsoredBrandAuctionRequest"
                   minItems: 1
                   maxItems: 5
+                  example:
+                    - winners: 2
+                      placementId: some-placement
+                      triggers:
+                        products:
+                          ids:
+                            - vanilla_yogurt
               required:
                 - auctions
         required: true
@@ -166,6 +199,18 @@ paths:
             budget is exhausted, the bid is disqualified to preserve spend pacing, etc.
           content:
             application/json:
+              example:
+                results:
+                  - resultType: brand
+                    winners:
+                      - rank: 1
+                        type: product
+                        id: brand-123
+                        resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
+                        content:
+                          headline: "Topsort Rocks"
+                          brandName: "Topsort Brand"
+                    error: false
               schema:
                 type: object
                 properties:
@@ -175,6 +220,10 @@ paths:
                       $ref: "#/components/schemas/SponsoredBrandAuctionResult"
                     minItems: 1
                     maxItems: 5
+                    example:
+                      - resultType: brand
+                        winners: []
+                        error: false
                 required:
                   - results
         "400":
@@ -209,6 +258,11 @@ paths:
                     $ref: "#/components/schemas/TravelAuctionRequest"
                   minItems: 1
                   maxItems: 5
+                  example:
+                    - type: hotels
+                      slots: 2
+                      travelContext:
+                        site: argentina
               required:
                 - auctions
               examples:
@@ -220,7 +274,7 @@ paths:
                           qualityScore: 0.7
                         - id: hotel-2
                       category:
-                        SingleCategory:
+                        singleCategory:
                           id: hotel-boutique
                       travelContext:
                         travelStartDate: "2025-01-01"
@@ -334,6 +388,7 @@ paths:
         Room](https://docs.topsort.com/knowledge-base/analytics/data-room/).
       operationId: reportEvents
       requestBody:
+        description: Event data including impressions, clicks, purchases, and page views.
         content:
           application/json:
             schema:
@@ -362,6 +417,7 @@ paths:
       x-beta: "true"
       operationId: linkUsers
       requestBody:
+        description: Request to link multiple user IDs that represent the same user.
         content:
           application/json:
             schema:
@@ -372,11 +428,15 @@ paths:
                   description: The opaque user ID of the original user account.
                   minLength: 1
                   maxLength: 64
+                  examples:
+                    - user_abc123
                 to:
                   type: string
                   description: The opaque user ID of the target user account to be linked.
                   minLength: 1
                   maxLength: 64
+                  examples:
+                    - user_xyz789
               required:
                 - from
                 - to
@@ -424,6 +484,15 @@ paths:
                     $ref: "#/components/schemas/RankingRequest"
                   minItems: 1
                   maxItems: 5
+                  example:
+                    - type: listings
+                      slots: 3
+                      pageSize: 3
+                      page:
+                        type: category
+                        value: sneakers
+                        pageId: /category/sneakers
+                      opaqueUserId: u_9ske45
               required:
                 - ranking
               examples:
@@ -462,6 +531,10 @@ paths:
                       $ref: "#/components/schemas/RankingResult"
                     minItems: 1
                     maxItems: 5
+                    example:
+                      - resultType: listings
+                        results: []
+                        error: false
                 required:
                   - results
                 examples:
@@ -1040,6 +1113,8 @@ components:
         - opaqueUserId
         - objectType
     AuctionResult:
+      description:
+        Base auction result schema supporting different auction types through discriminator.
       discriminator:
         propertyName: resultType
         mapping:
@@ -1067,6 +1142,10 @@ components:
           maxItems: 0
         error:
           $ref: "#/components/schemas/ErrorFlag"
+      required:
+        - winners
+        - error
+        - resultType
     BannersAuctionResult:
       description: The result of a banner auction, containing winning banner ads.
       type: object
@@ -1550,6 +1629,8 @@ components:
       description: The result of a sponsored brand auction, containing winning brand promotions.
       type: object
       properties:
+        resultType:
+          type: string
         winners:
           type: array
           items:
@@ -1562,33 +1643,30 @@ components:
       required:
         - winners
         - error
-      x-examples:
-        Example 1:
-          results:
-            - winners:
-                - rank: 1
-                  resolvedBidId: ChAGc-G66Wt7LKQEOcW8VBdIEhABjz_zDXx7db-ZYpxiwJ3DGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATEQATDrrg8
-                  type: "url"
-                  id: "https://some.url.com/myyougurtbrand/page"
-                  title: Brand Example Promo 1
-                  content:
-                    headline: "some cool regular yogurt headline"
-                    brandName: "my regular yogurt brand"
-                    creative1: "https://some.url.com/regular_yogurt.jpeg"
-                  campaignId: 01934a6e-7bb3-79c1-89b3-134e2e3bf88e
-                  productIds: ["vanilla_yogurt", "strawberry_yogurt"]
-                - rank: 2
-                  resolvedBidId: ChAGc-G66Wt7LKQEOcW8VBdIEhABk0pue7N5wYmzE04uO_iOGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATgQATDrrg8
-                  type: "url"
-                  id: "https://some.url.com/mynonfatyougurtbrand/page"
-                  title: Brand Example Promo 2
-                  content:
-                    - headline: "some cool nonfat regular yogurt headline"
-                      brandName: "my nonfat yogurt brand"
-                      creative1: "https://some.url.com/nonfat_yogurt.jpeg"
-                  campaignId: 01934a6e-7bb3-79c1-89b3-134e2e3bf88e
-                  productIds: ["nonfat_vanilla_yogurt", "nonfat_strawberry_yogurt"]
-              error: false
+      examples:
+        - resultType: brand
+          winners:
+            - rank: 1
+              resolvedBidId: ChAGc-G66Wt7LKQEOcW8VBdIEhABjz_zDXx7db-ZYpxiwJ3DGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATEQATDrrg8
+              type: "url"
+              id: "https://some.url.com/myyougurtbrand/page"
+              title: Brand Example Promo 1
+              content:
+                headline: "some cool regular yogurt headline"
+                brandName: "my regular yogurt brand"
+                creative1: "https://some.url.com/regular_yogurt.jpeg"
+              productIds: ["vanilla_yogurt", "strawberry_yogurt"]
+            - rank: 2
+              resolvedBidId: ChAGc-G66Wt7LKQEOcW8VBdIEhABk0pue7N5wYmzE04uO_iOGhABjr4Lt_J0_a7Xv_uIfyOXIgUKATgQATDrrg8
+              type: "url"
+              id: "https://some.url.com/mynonfatyougurtbrand/page"
+              title: Brand Example Promo 2
+              content:
+                headline: "some cool nonfat regular yogurt headline"
+                brandName: "my nonfat yogurt brand"
+                creative1: "https://some.url.com/nonfat_yogurt.jpeg"
+              productIds: ["nonfat_vanilla_yogurt", "nonfat_strawberry_yogurt"]
+          error: false
     SponsoredBrandWinner:
       description: A winning bid in a sponsored brand auction with brand and campaign details.
       type: object
@@ -1672,9 +1750,10 @@ components:
           description: A category for the purpose of running an auction.
           type: object
           required:
-            - SingleCategory
+            - singleCategory
           properties:
-            SingleCategory:
+            singleCategory:
+              type: object
               required:
                 - id
               properties:
@@ -1757,7 +1836,9 @@ components:
           type: string
           description: Platform e.g. "app", "mobile", "web", ...
     HotelsTravelContext:
-      description: Context information specific to hotel travel auctions.
+      description:
+        Context information specific to hotel travel auctions extending base travel context with
+        hotel-specific fields.
       allOf:
         - $ref: "#/components/schemas/BaseTravelContext"
     FlightsAuctionRequest:

From 567a34875e135fe2c2d4e1d7460614f26da1e258 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= <johan@topsort.com>
Date: Fri, 14 Nov 2025 13:31:30 +0000
Subject: [PATCH 8/9] fix: more examples, desdcriptions and fix a custom
 `x-examples` section

---
 topsort-api-v2.yml | 277 +++++++++++++++++++++------------------------
 1 file changed, 130 insertions(+), 147 deletions(-)

diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
index f93ed45..2915e54 100644
--- a/topsort-api-v2.yml
+++ b/topsort-api-v2.yml
@@ -672,9 +672,7 @@ components:
                 In order to participate in an auction, a bid product must belong to **all** of the
                 categories provided in the auction request.
               items:
-                type: string
-                description: A category ID.
-                minLength: 1
+                $ref: "#/components/schemas/CategoryID"
               minItems: 1
               examples:
                 - ["c_men_clothing", "c_shoes"]
@@ -720,9 +718,7 @@ components:
         A bid entity must belong to at least one of the categories in the disjunction in order to
         participate in the auction.
       items:
-        type: string
-        description: A category ID.
-        minLength: 1
+        $ref: "#/components/schemas/CategoryID"
       minItems: 1
     Device:
       type: string
@@ -848,6 +844,64 @@ components:
       description: An opaque Topsort ID to be used when this item is interacted with.
       examples:
         - WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
+    ResolvedItemID:
+      type: string
+      description: An opaque Topsort ID to be used when this item is ranked or interacted with.
+      examples:
+        - WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
+    CategoryID:
+      type: string
+      description: A category ID.
+      minLength: 1
+      examples:
+        - "c_electronics"
+    SlotsCount:
+      type: integer
+      format: int32
+      description: Specifies the maximum number of auction winners that should be returned.
+      minimum: 1
+    WinnerType:
+      type: string
+      description: The target type of the winning bid.
+    WinnerID:
+      type: string
+      description:
+        The marketplace's ID of the winning entity, depending on the target of the campaign.
+    ChannelType:
+      type: string
+      description: Optional. The channel where the event occurred.
+      enum:
+        - onsite
+        - offsite
+        - instore
+      examples:
+        - onsite
+    QualityScore:
+      type: number
+      maximum: 1
+      exclusiveMinimum: 0
+      format: double
+      description: |
+        If given, this value will be combined with our internal quality
+        score to provide a score that better represents the relevance of the
+        participating products. If not given it will default to 1.
+        Values must be between 0 and 1.
+      examples:
+        - 0.75
+    ExternalCampaignId:
+      type: string
+      description: Marketplace provided ID for a campaign
+      examples:
+        - awareness-campaign-2025
+    ExternalVendorId:
+      type: string
+      description: Marketplace provided ID for a vendor
+      examples:
+        - my-new-vendor
+
+    ObjectType:
+      type: string
+      description: The type of object that was predicted.
     SponsoredListingsAuction:
       title: Sponsored Listing
       type: object
@@ -860,14 +914,10 @@ components:
       properties:
         type:
           type: string
-          enum:
-            - listings
+          const: listings
           description: Discriminator for the type of auction.
         slots:
-          type: integer
-          format: int32
-          minimum: 1
-          description: Specifies the maximum number of auction winners that should be returned.
+          $ref: "#/components/schemas/SlotsCount"
         category:
           $ref: "#/components/schemas/AuctionCategory"
         searchQuery:
@@ -910,14 +960,10 @@ components:
       properties:
         type:
           type: string
-          enum:
-            - banners
+          const: banners
           description: Discriminator for the type of auction.
         slots:
-          type: integer
-          format: int32
-          minimum: 1
-          description: Specifies the maximum number of auction winners that should be returned.
+          $ref: "#/components/schemas/SlotsCount"
         category:
           $ref: "#/components/schemas/AuctionCategory"
         searchQuery:
@@ -1197,17 +1243,15 @@ components:
         rank:
           $ref: "#/components/schemas/WinnerRank"
         type:
-          type: string
-          description: The target type of the winning bid.
-          enum:
-            - product
-            - vendor
-            - brand
-            - url
+          allOf:
+            - $ref: "#/components/schemas/WinnerType"
+            - enum:
+                - product
+                - vendor
+                - brand
+                - url
         id:
-          type: string
-          description:
-            The marketplace's ID of the winning entity, depending on the target of the campaign.
+          $ref: "#/components/schemas/WinnerID"
           examples:
             - p_Mfk15
         resolvedBidId:
@@ -1237,17 +1281,15 @@ components:
         rank:
           $ref: "#/components/schemas/WinnerRank"
         type:
-          type: string
-          description: The target type of the winning bid.
-          enum:
-            - product
-            - vendor
-            - brand
-            - url
+          allOf:
+            - $ref: "#/components/schemas/WinnerType"
+            - enum:
+                - product
+                - vendor
+                - brand
+                - url
         id:
-          type: string
-          description:
-            The marketplace's ID of the winning entity, depending on the target of the campaign.
+          $ref: "#/components/schemas/WinnerID"
           examples:
             - p_Mfk15
         resolvedBidId:
@@ -1296,10 +1338,10 @@ components:
         rank:
           $ref: "#/components/schemas/WinnerRank"
         type:
-          type: string
-          description: The target type of the winning bid.
-          enum:
-            - product
+          allOf:
+            - $ref: "#/components/schemas/WinnerType"
+            - enum:
+                - product
         id:
           type: string
           description:
@@ -1347,19 +1389,18 @@ components:
             Where is the product ranked in the auction.
           minimum: 1
         type:
-          type: string
-          description: The target type of the winning bid.
-          enum:
-            - organic
-            - sponsored
+          allOf:
+            - $ref: "#/components/schemas/WinnerType"
+            - enum:
+                - organic
+                - sponsored
         id:
           type: string
           description: The marketplace's ID of the ranked entity.
           examples:
             - p_Mfk15
         resolvedItemId:
-          type: string
-          description: An opaque Topsort ID to be used when this item is interacted with.
+          $ref: "#/components/schemas/ResolvedItemID"
           examples:
             - WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
     PredictionResult:
@@ -1368,13 +1409,13 @@ components:
       type: object
       properties:
         objectType:
-          type: string
-          enum:
-            - listings
-            - banners
-          examples:
-            - listings
-          description: The type of object that was predicted.
+          allOf:
+            - $ref: "#/components/schemas/ObjectType"
+            - enum:
+                - listings
+                - banners
+              examples:
+                - listings
         predictions:
           type: array
           items:
@@ -1411,11 +1452,11 @@ components:
       type: object
       properties:
         objectType:
-          type: string
-          enum:
-            - listings
-            - banners
-          description: The type of object that was predicted.
+          allOf:
+            - $ref: "#/components/schemas/ObjectType"
+            - enum:
+                - listings
+                - banners
         objects:
           type: array
           items:
@@ -1553,10 +1594,7 @@ components:
         - triggers
       properties:
         winners:
-          type: integer
-          format: int32
-          minimum: 1
-          description: Specifies the maximum number of auction winners that should be returned.
+          $ref: "#/components/schemas/SlotsCount"
         placementId:
           type: string
           x-stoplight:
@@ -1686,15 +1724,13 @@ components:
             entry's index.
           minimum: 1
         type:
-          type: string
-          description: The target type of the winning bid.
-          enum:
-            - product
-            - url
+          allOf:
+            - $ref: "#/components/schemas/WinnerType"
+            - enum:
+                - product
+                - url
         id:
-          type: string
-          description:
-            The marketplace's ID of the winning entity, depending on the target of the campaign.
+          $ref: "#/components/schemas/WinnerID"
           examples:
             - p_Mfk15
             - https://some.url.com/topsort-brand
@@ -1734,13 +1770,12 @@ components:
             - hotels
           description: Discriminator for the type of travel auction.
         slots:
-          type: integer
-          format: int32
-          description:
-            Specifies the maximum number of auction winners that should be returned. If slots > 40,
-            it is capped at 40.
-          minimum: 1
-          maximum: 40
+          allOf:
+            - $ref: "#/components/schemas/SlotsCount"
+            - description:
+                Specifies the maximum number of auction winners that should be returned. If slots >
+                40, it is capped at 40.
+              maximum: 40
         products:
           type: array
           description: An array of hotels products that should participate in the auction.
@@ -1758,9 +1793,7 @@ components:
                 - id
               properties:
                 id:
-                  type: string
-                  description: The category ID of the bids that will participate in an auction.
-                  minLength: 1
+                  $ref: "#/components/schemas/CategoryID"
                   examples:
                     - c_buenos-aires-hotels
         travelContext:
@@ -1777,17 +1810,7 @@ components:
           examples:
             - miami-hotel
         qualityScore:
-          type: number
-          maximum: 1
-          exclusiveMinimum: 0
-          examples:
-            - 0.75
-          format: double
-          description: |
-            If given, this value will be combined with our internal quality
-            score to provide a score that better represents the relevance of the
-            participating products. If not given it will default to 1.
-            Values must be between 0 and 1.
+          $ref: "#/components/schemas/QualityScore"
     BaseTravelContext:
       description:
         Base context information for travel-related auctions including dates, location, and traveler
@@ -1854,11 +1877,11 @@ components:
             - flights
           description: Discriminator for the type of travel auction.
         slots:
-          type: integer
-          format: int32
-          description:
-            Specifies the maximum number of auction winners that should be returned. If slots > 40,
-            it is capped at 40.
+          allOf:
+            - $ref: "#/components/schemas/SlotsCount"
+            - description:
+                Specifies the maximum number of auction winners that should be returned. If slots >
+                40, it is capped at 40.
           minimum: 1
           maximum: 40
         products:
@@ -1886,17 +1909,7 @@ components:
           type: number
           description: Flight variation total price in marketplace currency.
         qualityScore:
-          type: number
-          maximum: 1
-          exclusiveMinimum: 0
-          examples:
-            - 0.75
-          format: double
-          description: |
-            If given, this value will be combined with our internal quality
-            score to provide a score that better represents the relevance of the
-            participating products. If not given it will default to 1.
-            Values must be between 0 and 1.
+          $ref: "#/components/schemas/QualityScore"
     FlightsTravelContext:
       description:
         Context information specific to flight travel auctions including route and flight type.
@@ -2005,11 +2018,7 @@ components:
         categoryIds:
           type: array
           items:
-            type: string
-            minLength: 1
-            description: A category ID.
-            examples:
-              - "cat1953"
+            $ref: "#/components/schemas/CategoryID"
           description: >
             An array of IDs of the categories associated to the page in which this event occurred,
             if applicable. These IDs must match the IDs provided through the catalog service.
@@ -2187,15 +2196,9 @@ components:
         object:
           $ref: "#/components/schemas/InteractionObject"
         externalCampaignId:
-          type: string
-          description: Marketplace provided ID for a campaign
-          examples:
-            - awareness-campaign-2025
+          $ref: "#/components/schemas/ExternalCampaignId"
         externalVendorId:
-          type: string
-          description: Marketplace provided ID for a vendor
-          examples:
-            - my-new-vendor
+          $ref: "#/components/schemas/ExternalVendorId"
         deviceType:
           $ref: "#/components/schemas/DeviceType"
         channel:
@@ -2253,15 +2256,9 @@ components:
             - like
             - add-to-cart
         externalCampaignId:
-          type: string
-          description: Marketplace provided ID for a campaign
-          examples:
-            - awareness-campaign-2025
+          $ref: "#/components/schemas/ExternalCampaignId"
         externalVendorId:
-          type: string
-          description: Marketplace provided ID for a vendor
-          examples:
-            - my-new-vendor
+          $ref: "#/components/schemas/ExternalVendorId"
         deviceType:
           $ref: "#/components/schemas/DeviceType"
         channel:
@@ -2305,14 +2302,7 @@ components:
         deviceType:
           $ref: "#/components/schemas/DeviceType"
         channel:
-          type: string
-          description: Optional. The channel where the event occurred.
-          enum:
-            - onsite
-            - offsite
-            - instore
-          examples:
-            - onsite
+          $ref: "#/components/schemas/ChannelType"
     PurchaseItem:
       description:
         An item included in a purchase transaction with product, quantity, and pricing details.
@@ -2393,14 +2383,7 @@ components:
         deviceType:
           $ref: "#/components/schemas/DeviceType"
         channel:
-          type: string
-          description: Optional. The channel where the event occurred.
-          enum:
-            - onsite
-            - offsite
-            - instore
-          examples:
-            - onsite
+          $ref: "#/components/schemas/ChannelType"
     WinnerRank:
       type: integer
       format: int32

From ff41a9eb8f5688252c1aeba694b56309e17d98b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20Bergstr=C3=B6m?= <johan@topsort.com>
Date: Fri, 14 Nov 2025 13:45:48 +0000
Subject: [PATCH 9/9] chore: use slotscount

---
 topsort-api-v2.yml | 29 ++++++++++++-----------------
 1 file changed, 12 insertions(+), 17 deletions(-)

diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
index 2915e54..e05c5d6 100644
--- a/topsort-api-v2.yml
+++ b/topsort-api-v2.yml
@@ -860,6 +860,7 @@ components:
       format: int32
       description: Specifies the maximum number of auction winners that should be returned.
       minimum: 1
+      maximum: 40
     WinnerType:
       type: string
       description: The target type of the winning bid.
@@ -915,7 +916,7 @@ components:
         type:
           type: string
           const: listings
-          description: Discriminator for the type of auction.
+          description: Discriminator for the listings auction.
         slots:
           $ref: "#/components/schemas/SlotsCount"
         category:
@@ -961,7 +962,7 @@ components:
         type:
           type: string
           const: banners
-          description: Discriminator for the type of auction.
+          description: Discriminator for the banner auction.
         slots:
           $ref: "#/components/schemas/SlotsCount"
         category:
@@ -1770,12 +1771,10 @@ components:
             - hotels
           description: Discriminator for the type of travel auction.
         slots:
-          allOf:
-            - $ref: "#/components/schemas/SlotsCount"
-            - description:
-                Specifies the maximum number of auction winners that should be returned. If slots >
-                40, it is capped at 40.
-              maximum: 40
+          $ref: "#/components/schemas/SlotsCount"
+          description:
+            Specifies the maximum number of auction winners that should be returned. If slots > 40,
+            it is capped at 40.
         products:
           type: array
           description: An array of hotels products that should participate in the auction.
@@ -1859,11 +1858,10 @@ components:
           type: string
           description: Platform e.g. "app", "mobile", "web", ...
     HotelsTravelContext:
+      $ref: "#/components/schemas/BaseTravelContext"
       description:
         Context information specific to hotel travel auctions extending base travel context with
         hotel-specific fields.
-      allOf:
-        - $ref: "#/components/schemas/BaseTravelContext"
     FlightsAuctionRequest:
       type: object
       description: Describes the intent of running a flight travel auction.
@@ -1877,13 +1875,10 @@ components:
             - flights
           description: Discriminator for the type of travel auction.
         slots:
-          allOf:
-            - $ref: "#/components/schemas/SlotsCount"
-            - description:
-                Specifies the maximum number of auction winners that should be returned. If slots >
-                40, it is capped at 40.
-          minimum: 1
-          maximum: 40
+          $ref: "#/components/schemas/SlotsCount"
+          description:
+            Specifies the maximum number of auction winners that should be returned. If slots > 40,
+            it is capped at 40.
         products:
           type: array
           description: An array of flights that should participate in the auction.