> ## 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] Retrieve objects > > ⚠️ **Beta Access Required** > Contact your sales representative to gain access to this endpoint and start using it. Use the `/retrieval` endpoint to get recommendations of which products are relevant given a certain context. Context is provided by user information, plus seed products. This can be used to retrieve object to display on a PDP (single seed product) or in a cart (multiple seed products). In order to provide retrieval, Topsort requires that events are also sent, as a source of information. ## OpenAPI ````yaml /openapi.json post /toptimize/v1/retrieval 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/retrieval: post: tags: - Toptimize summary: '[Beta] Retrieve objects' description: > > ⚠️ **Beta Access Required** > Contact your sales representative to gain access to this endpoint and start using it. Use the `/retrieval` endpoint to get recommendations of which products are relevant given a certain context. Context is provided by user information, plus seed products. This can be used to retrieve object to display on a PDP (single seed product) or in a cart (multiple seed products). In order to provide retrieval, Topsort requires that events are also sent, as a source of information. operationId: retrieveObjects requestBody: description: > The context information for the predictions, including which metrics to predict. x-beta: 'true' content: application/json: schema: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_RetrievalRequest required: true responses: '200': description: > The retrieval results. Each retrieved products is accompanied by their relevancy score. content: application/json: schema: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_RetrievalResults '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_RetrievalRequest: description: Request to retrieve objects based on context. type: object properties: slots: type: integer description: How many objects to retrieve. examples: - 10 - 50 minimum: 1 maximum: 100 opaqueUserId: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_OpaqueUserID' page: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_Page' objectType: type: string description: The type of object that needs to be retrieved. enum: - listings - banners deviceType: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType' seedProductIds: type: array items: type: string examples: - p_1234 - p_5678 mode: type: string description: Retrieval mode, how to interpret the context to get objects. enum: - all - complement - similar default: all examples: - slots: 5 opaqueUserId: u_9ske45 seedProductIds: - p_PJbnN - p_ojng4 mode: all objectType: listings deviceType: mobile required: - slots - seedProductIds - opaqueUserId - objectType Topsort_Endpoints_v2_API_Reference_RetrievalResults: description: >- The result of a retrieval request, containing relevant objects with scores. type: object properties: objectType: allOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ObjectType - enum: - listings - banners objects: type: array items: type: object properties: id: type: string description: Object identifier defined on the request. score: type: number description: Relevance score for the retrieved products. description: Retrieved objects. examples: - objectType: listings objects: - id: p_xh90s score: 0.978 - id: p_12lp0 score: 0.953 - id: p_ds7ui score: 0.877 required: - objectType - objects 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_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_DeviceType: type: string description: The device the user is on. enum: - desktop - mobile examples: - mobile Topsort_Endpoints_v2_API_Reference_ObjectType: type: string description: The type of object that was predicted. 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 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 ````