autobidding endpoint documentation

.gitignore

@@ -1 +1,2 @@
 openapitools.json
+.idea

topsort-api-v2.yml

@@ -83,6 +83,15 @@ tags:
       ## Winner (Sponsored Listings)
       <SchemaDefinition schemaRef="#/components/schemas/SponsoredListingsWinner" />
 
+      ## Autobidding Result
+      <SchemaDefinition schemaRef="#/components/schemas/AutobiddingResult" />
+
+      ## Autobidding Bid
+      <SchemaDefinition schemaRef="#/components/schemas/AutobiddingBid" />
+
+      ## Autobidding Bid Info
+      <SchemaDefinition schemaRef="#/components/schemas/AutobiddingBidInfo" />
+
 security:
   - BearerAuth: []
 
@@ -228,6 +237,113 @@ paths:
           $ref: '#/components/responses/UnauthorizedError'
         400:
           $ref: '#/components/responses/BadRequest'
+  /bids:
+    post:
+      tags:
+        - Auctions
+      summary: (Preview) Create new autobidding requests
+      operationId: createAutobiddingRequest
+      requestBody:
+        description: |
+          The information describing the contents of the autobidding call.
+          Topsort will run compute the autobidding bids for each batched autobidding request.
+          The format of the autobidding request is identical to the auction request.
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                auctions:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/AuctionRequest'
+                  minItems: 1
+                  maxItems: 5
+              required:
+                - auctions
+              example:
+                auctions:
+                  - type: listings
+                    slots: 1
+                    category:
+                      disjunctions:
+                        - - c_large
+                          - c_medium
+                        - - c_red
+                          - c_blue
+                  - type: listings
+                    slots: 2
+                    products:
+                      ids:
+                        - p_PJbnN
+                        - p_ojng4
+                        - p_8VKDt
+                        - p_Mfk15
+                    geoTargeting:
+                      location: New York
+                  - type: banners
+                    slots: 1
+                    slotId: categories-ribbon-banner
+                    category:
+                      id: c_yogurt
+                  - type: banners
+                    slots: 1
+                    slotId: homepage-banner
+        required: true
+      responses:
+        201:
+          description: >
+            The results of autobidding requests.
+            The list of bids will contain at most `slots` entries per autobidding request.
+            It may contain fewer or no entries at all if there aren't enough products with usable bids, 
+            belonging to a campaign with enough remaining budget and not excluded by pacing mechanism.
+            Bids become unusable if campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/AutobiddingResult'
+                    minItems: 1
+                    maxItems: 5
+                required:
+                  - results
+                example:
+                  results:
+                    - winners:
+                        - rank: 1
+                          type: product
+                          id: p_Mfk11
+                          resolvedBidId: WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0==
+                          bidInfo:
+                            amount: 42
+                      error: false
+                    - winners:
+                        - rank: 1
+                          type: product
+                          id: p_Mfk15
+                          resolvedBidId: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
+                          bidInfo:
+                            amount: 42
+                        - rank: 2
+                          type: product
+                          id: p_PJbnN
+                          resolvedBidId: WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
+                          bidInfo:
+                            amount: 24
+                            qualityScore: 0.1
+                      error: false
+                    - winners: []
+                      error: false
+        401:
+          $ref: '#/components/responses/UnauthorizedError'
+        400:
+          $ref: '#/components/responses/BadRequest'
+        402:
+          $ref: '#/components/responses/PaymentRequired'
 
 components:
   responses:
@@ -991,6 +1107,83 @@ components:
           description: The price of a single item in the marketplace currency.
           example: 12.95
 
+    AutobiddingResult:
+      type: object
+      properties:
+        resultType:
+          type: string
+        winners:
+          type: array
+          items:
+            $ref: '#/components/schemas/AutobiddingBid'
+          description: >
+            Array of autobidding bid objects in order from highest to lowest according to internal ranking score.
+            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.
+          example: false
+      required:
+        - winners
+        - error
+        - resultType
+
+    AutobiddingBid:
+      description: >
+        Container for the autobidding bid result, similar to auction winner
+      type: object
+      required:
+        - type
+        - id
+        - resolvedBidId
+        - bidInfo
+      properties:
+        rank:
+          type: integer
+          format: int32
+          description: >
+            Where the product's bid ranked by the internal ranking score. 
+            In an autobidding response, the bids array is sorted so rank will match the entry's index.
+          minimum: 1
+        type:
+          type: string
+          description: The target type of the bid.
+          enum:
+            - product
+            - vendor
+            - brand
+            - url
+        id:
+          type: string
+          description: |-
+            The marketplace's ID of the bid entity, depending on the target of the campaign.
+          example: p_Mfk15
+        resolvedBidId:
+          type: string
+          description: An opaque Topsort ID to be used when this item is interacted with.
+          example: WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=
+        bidInfo:
+          $ref: '#/components/schemas/AutobiddingBidInfo'
+
+    AutobiddingBidInfo:
+      description: >
+        Bidding values, including bid amount and optional quality score
+      type: object
+      required:
+        - amount
+      properties:
+        amount:
+          type: integer
+          format: int64
+          description: Bid amount in minimum currency units.
+          minimum: 1
+        qualityScore:
+          type: number
+          format: double
+          description: Optional quality score value
+          minimum: 0.0
+          maximum: 1.0
+
   securitySchemes:
     BearerAuth:
       type: http