> ## 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. # Serving recommendation > Serves recommended items for the ad unit (`tagid`) and request payload (`RecoRequest`). Resolves the recommendation policy for the ad unit and retrieves candidates from its configured sources. When provided, `seed_item_id` is used by policy sources that support seed-based retrieval, such as Association and Pinned. Returns the items to render (`catalog_id`, `position`) and a `tracking_token` for recommendation tracking. ## 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: Serving recommendation description: > Serves recommended items for the ad unit (`tagid`) and request payload (`RecoRequest`). Resolves the recommendation policy for the ad unit and retrieves candidates from its configured sources. When provided, `seed_item_id` is used by policy sources that support seed-based retrieval, such as Association and Pinned. Returns the items to render (`catalog_id`, `position`) and a `tracking_token` for recommendation tracking. 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/RecoRequest' description: RecoRequest is used for requesting a recommendation. required: true responses: '200': content: application/json: example: items: - catalog_id: catalog-123 position: 0 - catalog_id: catalog-234 position: 1 tracking_token: dXNlci0xMjN8ZjQ3YWMxMGJ8OWMzZTc3YTE version: 0.1.0 schema: $ref: '#/components/schemas/RecoResponse' description: Successfully served recommendation '400': content: application/json: schema: $ref: '#/components/schemas/RecoResponse' text/plain; charset=utf-8: path: /docs/redoc description: >- Malformed JSON request bodies return text/plain. Invalid tagid returns an application/json RecoResponse with an error code. '404': content: application/json: schema: $ref: '#/components/schemas/RecoResponse' description: AdUnit not found. The response contains a JSON error code. '415': content: text/plain: schema: type: string description: 'Expected request with `Content-Type: application/json`' '422': content: application/json: schema: $ref: '#/components/schemas/RecoResponse' text/plain; charset=utf-8: path: /docs/redoc description: >- JSON shape or type deserialization errors return text/plain. Disabled recommendation or unavailable delivery policy returns an application/json RecoResponse with an error code. security: - '': [] components: schemas: RecoRequest: description: RecoRequest is used for requesting a recommendation. 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: true seed_item_id: 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 RecoResponse: properties: errorcode: description: Error code if the request failed. type: - string - 'null' ext: description: Optional A2 specific extensions. items: description: Recommended items. items: $ref: '#/components/schemas/RecommendationItem' type: array tracking_token: description: >- Token identifying this recommendation result, echoed back on tracking calls. Absent on error responses. type: - string - 'null' user: anyOf: - $ref: '#/components/schemas/User' - type: 'null' description: Echoed User object from the ad request. version: description: Version of the SDK API. type: string required: - version - items 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 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 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 IpLocationService: enum: - 1 - 2 - 3 - 4 type: integer LocationType: enum: - 1 - 2 - 3 type: integer ````