> ## 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] Add Quality Score > Use the `/predictions` endpoint to get contextual predictions of conversion and relevance metrics, which are personalized by user and context.In order to provide predictions, Topsort requires that events are also sent, as a source of information. ## OpenAPI ````yaml /openapi.json post /toptimize/v1/predictions 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/predictions: post: tags: - Toptimize summary: '[Beta] Add Quality Score' description: > Use the `/predictions` endpoint to get contextual predictions of conversion and relevance metrics, which are personalized by user and context.In order to provide predictions, Topsort requires that events are also sent, as a source of information. operationId: getPredictions requestBody: description: > > ⚠️ **Beta Access Required** > Contact your sales representative to gain access to this endpoint and start using it. 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_PredictionRequest required: true responses: '200': description: > The prediction results. This will provide a numerical value for each combination of metric/product requested on the API call. content: application/json: schema: $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_PredictionResult '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_PredictionRequest: type: object description: Request to predict the outcome of an interaction. properties: metrics: type: object description: >- Metrics to predict, the response will include all the selected metrics. properties: ctr: type: boolean description: If `true` a Click Through Rate prediction will be made. cvr: type: boolean description: If `true` a Conversion Rate prediction will be made. 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 is being reported on the interaction. enum: - listings - banners deviceType: $ref: '#/components/schemas/Topsort_Endpoints_v2_API_Reference_DeviceType' productIds: type: array items: type: string examples: - p_1234 - p_5678 examples: - metrics: ctr: true opaqueUserId: u_9ske45 productIds: - p_PJbnN - p_ojng4 objectType: listings required: - metrics - productIds - objectType - opaqueUserId Topsort_Endpoints_v2_API_Reference_PredictionResult: description: >- The result of a prediction request, containing CTR and CVR predictions for products. type: object properties: objectType: allOf: - $ref: >- #/components/schemas/Topsort_Endpoints_v2_API_Reference_ObjectType - enum: - listings - banners examples: - listings predictions: type: array items: type: object properties: productId: type: string description: Product identifier defined on the request. ctr: type: number description: Click-Through Rate prediction. cvr: type: number description: Conversion Rate prediction. description: Predicted objects examples: - - productId: product-123 ctr: 0.05 cvr: 0.101 examples: - objectType: listings predictions: - productId: p_PJbnN ctr: 0.03 cvr: 0.06 - productId: p_ojng4 ctr: 0.056 cvr: 0.091 required: - objectType - predictions 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 ````