> ## Documentation Index > Fetch the complete documentation index at: https://docs.aiderx.io/llms.txt > Use this file to discover all available pages before exploring further. # Request recommendations > Serves recommended items for the ad unit (`tagid`) using its recommendation policy. The response includes the items to render and a `tracking_token` for recommendation events. It never includes `user`. ## OpenAPI ````yaml /openapi/decision.api.en-dev.json post /app/v0/recommendation/{tagid} openapi: 3.1.0 info: contact: email: a2support@aiderx.io name: A2 Support url: https://aiderx.io description: >+ ### Introduction The Decision API is responsible for selecting and distributing ads or content based on user requests or contextual information, all in real time. Its rapid response and dynamic capabilities enable the **optimal** ad or recommendation to be served, ensuring users receive the highest possible value. A variety of algorithms, machine learning models, and rule-based logic can be applied, allowing the system to **adapt flexibly** to constantly changing conditions. title: Decision APIs version: dev x-logo: altText: A2 Logo url: >- https://cdn.prod.website-files.com/668de9e1f25ab5675d87758d/6690cf1bdce95af5e3522c25_a2_logo_800_250.png servers: [] security: [] tags: - description: > Ad Serving APIs for requesting ads and configuring cache settings and other parameters of the ad serving modules. name: Ad Serving - description: | Recommendation Serving APIs for requesting recommendations. name: Recommendation Serving - description: >- APIs for manipulating caches of the serving server. ### **Important** If you directly manipulate the cached data related to advertising or recommendations on the Serving server, we **strongly advise** against also modifying the advertising or recommendation data through the Ad Manager. Alternatively, we **recommend** handling any advertising or recommendation data modifications via the Ad Manager APIs. Any changes made on the Serving server will **not** be reflected in the Ad Manager, which can compromise **data integrity**. name: Cache Management - description: |- APIs for manipulating configurations of the serving server name: Configuration - description: > APIs for receiving conversion, impression, and click logs related to ads or recommendations. name: Ad Log paths: /app/v0/recommendation/{tagid}: post: tags: - Recommendation Serving summary: Request recommendations description: >- Serves recommended items for the ad unit (`tagid`) using its recommendation policy. The response includes the items to render and a `tracking_token` for recommendation events. It never includes `user`. parameters: - description: |- The ID of the ad unit. Get from the advertising manager. in: path name: tagid required: true schema: description: |- The ID of the ad unit. Get from the advertising manager. format: uuid type: string style: simple requestBody: content: application/json: schema: $ref: '#/components/schemas/RecommendationServingRequest' required: true responses: '200': content: application/json: example: ext: ad_log_tracking_mode: on_ad_response items: - catalog_id: catalog-123 position: 0 score: 0.87 - catalog_id: catalog-234 position: 1 tracking_token: opaque-recommendation-tracking-token version: 0.1.0 schema: $ref: '#/components/schemas/RecommendationServingResponse' description: Successfully served recommendation '400': content: application/json: schema: $ref: '#/components/schemas/RecommendationErrorResponse' text/plain; charset=utf-8: {} description: >- Malformed JSON request bodies return text/plain. Invalid tagid (`1300`) or a filter array with more than 100 values (`1304`) returns an application/json error response with empty items and ext.message. '404': content: application/json: schema: $ref: '#/components/schemas/RecommendationErrorResponse' description: >- AdUnit not found (`1301`). JSON response contains empty items and ext.message. '415': content: text/plain: schema: type: string description: 'Expected request with `Content-Type: application/json`' '422': content: application/json: schema: $ref: '#/components/schemas/RecommendationErrorResponse' text/plain; charset=utf-8: {} description: >- JSON shape or type deserialization errors return text/plain. Disabled recommendation (`1302`) or no applicable delivery policy (`1303`) returns an application/json error response with empty items and ext.message. security: - '': [] components: schemas: RecommendationServingRequest: properties: app: anyOf: - $ref: '#/components/schemas/ServingRequestApp' - type: 'null' description: App object for the current serving request. device: anyOf: - $ref: '#/components/schemas/Device' - type: 'null' description: Device object for the current serving request. examples: - null filter: description: >- Optional exclusion conditions. For webtoon catalogs, `rating` excludes items above the supplied rating and `exclusion_tags` excludes items sharing any supplied tag. Conditions combine as exclusions: a match on either condition removes the item. Creative catalog filtering is not implemented. Unknown fields, null values, and empty arrays do not filter candidates. Every top-level array is limited to 100 values, including arrays under unknown fields; exceeding the limit returns HTTP 400 with errorcode `1304`. examples: - exclusion_tags: - tag:10 - taste:N rating: 2 seed_item_id: description: >- Optional catalog ID used by seed-based sources, such as Association and Pinned. type: - string - 'null' site: anyOf: - $ref: '#/components/schemas/ServingRequestSite' - type: 'null' description: Site object for the current serving request. user: anyOf: - $ref: '#/components/schemas/User' - type: 'null' description: User object for the current serving request. examples: - gender: M id: account-187acvbvz yob: 1988 type: object RecommendationServingResponse: description: >- Recommendation wire response. Unlike an ad response, it never echoes `user`. properties: errorcode: description: >- Application error code on an error response: `1300` invalid tagid; `1301` ad unit not found; `1302` recommendation disabled; `1303` no applicable delivery policy; `1304` filter array exceeds 100 values. Absent on success. type: - string - 'null' ext: anyOf: - $ref: '#/components/schemas/RecommendationServingResponseExt' - type: 'null' description: Tracking mode on success, or a message on an error response. items: description: >- Recommended catalog IDs, zero-based positions, and scores when supplied by the candidate source. Empty on error; success may also contain no items. items: $ref: '#/components/schemas/RecommendationItem' type: array tracking_token: description: >- Opaque token for this recommendation result. Send it as `tracking_token` in recommendation log events. Absent on errors. type: - string - 'null' version: description: Version of the SDK API. type: string required: - version - items type: object RecommendationErrorResponse: properties: errorcode: type: string ext: $ref: '#/components/schemas/RecommendationErrorDetails' items: description: Always empty on an application error. items: $ref: '#/components/schemas/RecommendationItem' maxItems: 0 type: array version: type: string required: - version - errorcode - items - ext type: object ServingRequestApp: properties: bundle: type: - string - 'null' domain: type: - string - 'null' name: type: - string - 'null' storeurl: type: - string - 'null' ver: type: - string - 'null' type: object Device: properties: ext: description: >- Placeholder for advertising-system specific extensions to this object geo: anyOf: - $ref: '#/components/schemas/Geo' - type: 'null' description: >- Location of the device assumed to be the user’s current location defined by a Geo object ip: description: IPv4 address closest to device. type: - string - 'null' ua: description: |- Browser user agent string. This field represents a raw user agent string from the browser. For backwards compatibility, exchanges are recommended to always populate ‘ua’ with the User-Agent string, when available from the end user’s device, even if an alternative representation, such as the User-Agent Client-Hints, is available and is used to populate ‘sua’. No inferred or approximated user agents are expected in this field. If a client supports User-Agent Client Hints, and ‘sua’ field is present, bidders are recommended to rely on ‘sua’ for detecting device type, browser type and version and other purposes that rely on the user agent information, and ignore ‘ua’ field. This is because the ‘ua’ may contain a frozen or reduced user agent string. type: - string - 'null' type: object ServingRequestSite: properties: domain: type: - string - 'null' mobile: type: - boolean - 'null' name: type: - string - 'null' page: type: - string - 'null' ref: type: - string - 'null' search: type: - string - 'null' type: object User: properties: buyeruid: description: >- Buyer-specific ID for the user as mapped by the exchange for the buyer. type: - string - 'null' ext: description: Placeholder for exchange-specific extensions to OpenRTB. gender: anyOf: - $ref: '#/components/schemas/Gender' - type: 'null' description: >- Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown). geo: anyOf: - $ref: '#/components/schemas/Geo' - type: 'null' description: >- Location of the user’s home base defined by a Geo object (Section 3.2.19). This is not necessarily their current location. id: description: Exchange-specific ID for the user. type: - string - 'null' keywords: description: >- Comma separated list of keywords, interests, or intent. Only one of ‘keywords’ or ‘kwarray’ may be present. type: - string - 'null' yob: deprecated: true description: Year of birth as a 4-digit integer. format: uint16 maximum: 65535 minimum: 0 type: - integer - 'null' type: object RecommendationServingResponseExt: additionalProperties: true properties: ad_log_tracking_mode: anyOf: - $ref: '#/components/schemas/AdLogTrackingMode' - type: 'null' description: >- Effective impression tracking mode. With `on_ad_response`, the server records an impression for a non-empty result. With `on_event_tracker`, the server does not record it; send a `reco_log` event with `action: "imp"`, the response's `tracking_token`, `event_items`, and `event_position` to `/dmp/v0/log` when the recommended items are shown. message: description: Explanation accompanying an application error code. type: - string - 'null' type: object RecommendationItem: description: One recommended item carried by a [`RecoResponse`]. properties: catalog_id: description: Catalog ID of the recommended item. type: string position: description: |- Zero-based slot position on the recommendation placement. Set to 0 when the placement has no distinct slots. format: int32 type: integer score: description: >- Relevance score the item was ranked with, carried over from the candidate pool. format: double type: - number - 'null' required: - catalog_id - position type: object RecommendationErrorDetails: properties: message: type: string required: - message type: object Geo: properties: accuracy: format: int32 type: - integer - 'null' city: type: - string - 'null' country: type: - string - 'null' ext: true ipservice: anyOf: - $ref: '#/components/schemas/IpLocationService' - type: 'null' lastfix: format: uint32 minimum: 0 type: - integer - 'null' lat: format: float type: - number - 'null' lon: format: float type: - number - 'null' metro: type: - string - 'null' region: type: - string - 'null' regionfips104: type: - string - 'null' type: anyOf: - $ref: '#/components/schemas/LocationType' - type: 'null' utcoffset: format: int32 type: - integer - 'null' zip: type: - string - 'null' type: object Gender: enum: - M - F - O type: string AdLogTrackingMode: description: >- Impression log tracking mode. - `on_ad_response`: the A2 server records an impression when returning the ad response. - `on_event_tracker`: for supported creatives, the response includes an impression tracker URL. The client calls it when the ad is displayed, and A2 records the impression when that request arrives. Do not also submit the same `imp` to the Log API. enum: - on_ad_response - on_event_tracker type: string IpLocationService: enum: - 1 - 2 - 3 - 4 type: integer LocationType: enum: - 1 - 2 - 3 type: integer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.