> ## Documentation Index > Fetch the complete documentation index at: https://docs.topsort.com/llms.txt > Use this file to discover all available pages before exploring further. # [Beta] Rank objects > > ⚠️ **Beta Access Required** > Contact your sales representative to gain access to this endpoint and start using it. Use the `/ranking` endpoint to re-rank objects to show on a page. This endpoint can retrieve sponsored and non-sonsored objects and rank them together, according to an appropriate context and behavior information. ## OpenAPI ````yaml /openapi.json post /toptimize/v1/rank openapi: 3.1.0 info: title: Topsort Endpoints v2 API Reference description: > In order for a storefront to be able to run auctions in Topsort and report auction-related events back to Topsort, both the `/v2/auctions` and `/v2/events` endpoints must be integrated. Below are the endpoint and model definitions for each. contact: email: wicha@topsort.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://assets.topsort.com/Topsort_logo_icon_dark.svg backgroundColor: '#fff' altText: Topsort version: 2.0.0 servers: - url: https://api.topsort.com description: Base API URL security: [] tags: - name: Auctions description: >- An auction determines which products should be promoted based on the vendors' bids. - name: Events description: >- Events are sent to Topsort as part of the attribution and reporting journey. - name: Toptimize description: > An out-of-the-box solution for prediction, ranking, retrieval, and other elements of ad selection. - name: Toppie API description: Toppie management API. - name: Campaign API description: Full-featured campaign management API for banners and sponsored listings. - name: Catalog API description: Products catalog management API. - name: Billing API description: Marketplace and Vendor Billing management API. - name: Reporting API description: Marketplace, Vendor, Campaign, and product reporting API. - name: Invitation API description: Vendor invitations management API. - name: User API description: User management API. - name: Webhooks API description: Webhooks API that allows event-driven automation. - name: Assets API description: Assets management API. - name: Segments Service description: Segments Service. - name: Forecasting Service description: Toptimize Forecasting Service. - name: Offsite Ads API description: Offsite Ads API that allows to manage offsite ads campaigns. - name: Media API description: Ad configuration API. paths: /toptimize/v1/rank: post: tags: - Toptimize summary: '[Beta] Rank objects' description: > > ⚠️ **Beta Access Required** > Contact your sales representative to gain access to this endpoint and start using it. Use the `/ranking` endpoint to re-rank objects to show on a page. This endpoint can retrieve sponsored and non-sonsored objects and rank them together, according to an appropriate context and behavior information. operationId: createRanking requestBody: description: > The context information to get the ranking, to rank organic and sponsored products. x-beta: 'true' content: application/json: schema: type: object properties: ranking: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_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: default: value: ranking: - type: listings slots: 3 pageSize: 3 page: type: category value: sneakers pageId: /category/sneakers opaqueUserId: u_9ske45 category: ids: - sneakers - shoes products: ids: - p_PJbnN - p_ojng4 required: true responses: '201': description: > The ranking results. The list of winners will contain at most `slots` entries per auction. It may contain fewer or no entries at all if there aren't enough products to fill the slots. content: application/json: schema: type: object properties: results: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_RankingResult minItems: 1 maxItems: 5 example: - resultType: listings results: [] error: false required: - results examples: default: value: results: - resultType: listings results: - rank: 1 type: organic id: p_Mfk11 resolvedItemId: >- WyJiX01mazExIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTMyNjYtY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0== - rank: 2 type: sponsored id: p_Mfk15 resolvedItemId: >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= - rank: 3 type: organic id: p_PJbnN resolvedItemId: >- WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= error: false '400': $ref: '#/components/responses/Topsort_Endpoints_v2_API_Reference_BadRequest' '401': $ref: >- #/components/responses/Topsort_Endpoints_v2_API_Reference_UnauthorizedError security: - Topsort_Endpoints_v2_API_Reference_HTTPBearer: [] components: schemas: Topsort_Endpoints_v2_API_Reference_RankingRequest: type: object description: | Describes the context related to a Ranking request properties: type: type: string enum: - listings description: Type of object to be ranked slots: type: integer format: int32 minimum: 1 description: >- Specifies the maximum number of ranked objects that should be returned. pageSize: type: integer format: int32 minimum: 1 description: >- Specifies the maximum number of ranked objects per page that should be returned. page: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page' category: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_AuctionCategory device: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Device' geoTargeting: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_GeoTargeting' products: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Products' opaqueUserId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID' required: - type - slots - pageSize - page - opaqueUserId examples: - type: listings slots: 10 pageSize: 10 page: type: category value: sneakers pageId: /category/sneakers opaqueUserId: u_9ske45 category: ids: - sneakers - shoes products: ids: - p_PJbnN - p_ojng4 Topsort_Endpoints_v2_API_Reference_RankingResult: description: The result of a ranking request, containing ordered products. type: object properties: resultType: type: string results: type: array items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_RankingWinner description: | Array of ranking objects in order from highest to lowest relevancy. error: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_ErrorFlag' required: - results - error - resultType Topsort_Endpoints_v2_API_Reference_Page: description: Information about the page where an auction or event occurs. type: object title: Page required: - type - pageId properties: type: type: string enum: - home - category - PDP - search - cart - other description: Type of page. examples: - category value: oneOf: - type: string description: Detail of the page, depending on the type examples: - electronics - type: array items: type: string description: Only valid for type cart. Items on the cart examples: - coffee - cookies - apples minItems: 1 pageId: type: string description: Identifies the page examples: - /category/electronics Topsort_Endpoints_v2_API_Reference_AuctionCategory: description: >- Represents one or more categories for auction targeting. Can be a single category, multiple categories, or category disjunctions. oneOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_SingleCategory - type: object title: Multiple Categories description: A set of categories for the purpose of running an auction. required: - ids properties: ids: type: array description: > An array containing the category IDs of the bids that will participate in an auction. In order to participate in an auction, a bid product must belong to **all** of the categories provided in the auction request. items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryID minItems: 1 examples: - - c_men_clothing - c_shoes - type: object title: Category Disjunctions description: >- Multiple disjunctions of categories for the purpose of running an auction. required: - disjunctions properties: disjunctions: type: array description: > An array of disjunctions. In order to participate in an auction, a bid product must belong to at least one of the categories of the disjunction provided in the auction request. items: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryDisjunction minItems: 1 maxItems: 5 examples: - - - c_red - - c_blue Topsort_Endpoints_v2_API_Reference_Device: type: string description: The device for which the ads are meant for. enum: - desktop - mobile default: desktop Topsort_Endpoints_v2_API_Reference_GeoTargeting: type: object description: >- An object describing geographical information associated with this auction. required: - location properties: location: description: The location this auction is being run for. type: string examples: - New York Topsort_Endpoints_v2_API_Reference_Products: required: - ids type: object description: | List of products for the purpose of running an auction. properties: ids: type: array description: > An array of product IDs that should participate in the auction. We recommend sending no more than 500 products per auction. items: type: string description: > The marketplace's ID of a product which will participate in the auction. These ID must match those in the catalog integration with Topsort. examples: - p_SA0238 minLength: 1 minItems: 1 maxItems: 10000 qualityScores: type: array description: > An array of marketplace defined quality scores, each corresponding to the product ID with matching array index. If given, these values will be combined with our internal quality scores to provide a score that better represents the relevance of the participating products. Note that the length of this array must be the same as the length of the `ids` array and that the values must be greater than 0 and less than or equal to 1. items: type: number maximum: 1 exclusiveMinimum: 0 minimum: 0 examples: - 0.75 format: double minItems: 1 maxItems: 10000 Topsort_Endpoints_v2_API_Reference_OpaqueUserID: type: string description: >- The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the original value. This identifier allows Topsort to correlate user activity between auctions and user interactions, independent of the user's logged-in status. For apps or sites where users might interact while logged out, we recommend generating a random identifier (UUIDv7) on the first load, storing it on local storage (cookie, local storage, etc), and letting it live for at least a year. Otherwise, if your users are always logged in for interactions, you may use a hash of your customer ID. Correct purchase attribution requires long-lived opaque user IDs consistent between auction and event requests. examples: - 71303ce0-de89-496d-8270-6434589615e8 Topsort_Endpoints_v2_API_Reference_RankingWinner: description: A ranked item from a ranking request with position and type information. type: object required: - rank - type - id - resolvedItemId properties: rank: type: integer format: int32 description: | Where is the product ranked in the auction. minimum: 1 type: allOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_WinnerType - enum: - organic - sponsored id: type: string description: The marketplace's ID of the ranked entity. examples: - p_Mfk15 resolvedItemId: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ResolvedItemID examples: - >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= Topsort_Endpoints_v2_API_Reference_ErrorFlag: type: boolean description: A boolean indicating whether this auction was resolved successfully. examples: - false - true Topsort_Endpoints_v2_API_Reference_Error: description: >- Error response object containing error code, message, and documentation URL. type: object required: - errCode properties: errCode: type: string description: A short string uniquely identifying the problem. enum: - bad_request - empty_request - internal_server_error - invalid_api_key - invalid_auction_id - invalid_demand_source - invalid_event_type - invalid_external_bid - invalid_external_demand_ad_type - invalid_promotion_type - invalid_session - missing_auctions - missing_context - missing_placement - missing_product_id - missing_promotion_type - missing_purchased_at - missing_session - missing_slot_id - missing_slots - no_products - no_purchase_items - purchase_item_quantity_less_or_equal_than_zero - resolved_bid_id_not_found - too_few_impressions - too_few_slots - too_many_auctions - too_many_external_bids - unauthorized_external_demand examples: - bad_request - no_products docUrl: type: string format: uri description: >- A link to a documentation page providing more information about the error. examples: - https://api.docs.topsort.com/reference/errors message: type: string description: > Human-readable explanation of or details about the error. The string for a given error may change over time; code should not parse or dispatch based on particular values for this field. examples: - could not find the provided resolved bid id Topsort_Endpoints_v2_API_Reference_SingleCategory: type: object title: Single Category description: A category for the purpose of running an auction. required: - id properties: id: type: string description: The category ID of the bids that will participate in an auction. minLength: 1 examples: - c_yogurt Topsort_Endpoints_v2_API_Reference_CategoryID: type: string description: A category ID. minLength: 1 examples: - c_electronics Topsort_Endpoints_v2_API_Reference_CategoryDisjunction: type: array description: > An array of category IDs, describing a category disjunction. A bid entity must belong to at least one of the categories in the disjunction in order to participate in the auction. items: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_CategoryID' minItems: 1 Topsort_Endpoints_v2_API_Reference_WinnerType: type: string description: The target type of the winning bid. Topsort_Endpoints_v2_API_Reference_ResolvedItemID: type: string description: >- An opaque Topsort ID to be used when this item is ranked or interacted with. examples: - >- WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0= responses: Topsort_Endpoints_v2_API_Reference_BadRequest: description: HTTP status codes as registered with IANA. content: application/json: schema: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Error' Topsort_Endpoints_v2_API_Reference_UnauthorizedError: description: Access token is missing or invalid securitySchemes: Topsort_Endpoints_v2_API_Reference_HTTPBearer: description: >- A valid API key generated in Topsort's UI. Use a TSE API key for calls to Auctions or Events API. scheme: bearer type: http ````