> ## 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 an ad > Serves an ad based on the placement tag (`tagid`) and request payload (`AdRequest`). Selects the most appropriate ad using campaign, creative, and bidding strategy data. Returns the final ad determined through DSP response and internal mediation logic. ```bash Request Example curl --request POST \ --url https://your_a2_service/app/v0/ad/{tagid} \ --header 'Content-Type: application/json' \ --data '{ "user": { "gender": "M", "id": "account-187acvbvz", "yob": 1988 }, "version": "0.1.0" }' ``` ## OpenAPI ````yaml /openapi/decision.api.en-0.2.2.json post /app/v0/ad/{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: v0.2.2 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: >- 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 ad conversion, impression, and click logs — essential for tracking and optimizing advertisement performance. name: Ad Serving paths: /app/v0/ad/{tagid}: post: tags: - Ad Serving summary: Serving an ad description: >- Serves an ad based on the placement tag (`tagid`) and request payload (`AdRequest`). Selects the most appropriate ad using campaign, creative, and bidding strategy data. Returns the final ad determined through DSP response and internal mediation logic. ```bash Request Example curl --request POST \ --url https://your_a2_service/app/v0/ad/{tagid} \ --header 'Content-Type: application/json' \ --data '{ "user": { "gender": "M", "id": "account-187acvbvz", "yob": 1988 }, "version": "0.1.0" }' ``` parameters: - description: |- The ID of the placement. Get from the advertising manager. in: path name: tagid required: true schema: description: |- The ID of the placement. Get from the advertising manager. format: uuid type: string style: simple requestBody: content: application/json: schema: $ref: '#/components/schemas/AdRequest' description: AdRequest is used for requesting an ad. required: true responses: '200': content: application/json: example: ad: display: banner: img: https://example.com/image.jpg h: 1024 w: 768 id: b56dc3bf-935d-4ee6-b1ed-f31bfc02be91 ext: ad_log: >- YTU2ZDY2ZjctNDM4ZS00OTVjLWJiYTAtMjI4Mzk2MjQ0ZWVkfDA2NDI4NjYwLWY2NDMtNGVmNS05MzgzLTZjZmE1OGYxOGI2OXxjNTZkYzNiZi05MzVkLTRlZTYtYjFlZC1mMzFiZmMwMmJlOTF8NGJlMmQ4ZTYtYThhMS00NzI2LWEzMjAtNjkyNTYzMDkwZTQyfDllZjY2ZGM4LTBlMmMtNDlmMS05NDU3LWFmYmUwZGQ2ZjU3M3w1NTgxNmIzOTcxMWY5YjVhY2YzYjkwZTMxM2VkMjllNTE2NjU2MjNm message: success version: 0.1.0 schema: $ref: '#/components/schemas/AdResponse' description: Successfully served an ad '204': description: No Bid. '404': description: Placement not found. '500': description: Internal Server Error. security: - '': [] components: schemas: AdRequest: description: AdRequest is used for requesting an ad. properties: device: anyOf: - $ref: '#/components/schemas/Device' - type: 'null' description: Device object for the current ad request. user: anyOf: - $ref: '#/components/schemas/User' - type: 'null' description: User object for the current ad request. version: description: Version of the SDK API. type: string required: - version type: object AdResponse: properties: ad: anyOf: - $ref: '#/components/schemas/Ad' - type: 'null' description: Ad object. errorcode: description: Error code if the request failed. type: - string - 'null' ext: description: Optional A2 specific extensions. version: description: Version of the SDK API. type: string required: - version 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 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 minimum: 0 type: - integer - 'null' type: object Ad: properties: cat: description: >- Array of content categories describing the ad using IDs from the taxonomy indicated in cattax. Implementer should ensure compliance with regional legislation around data usage and sharing. items: type: string type: - array - 'null' cattax: anyOf: - $ref: '#/components/schemas/CategoryTaxonomy' - type: 'null' description: >- The taxonomy in use for the cat attribute. Refer to List: Category Taxonomies. display: anyOf: - $ref: '#/components/schemas/Display' - type: 'null' description: >- Creative Subtype Object that indicates this is a display ad and provides additional detail as such. ext: description: Optional A2 specific extensions. id: description: >- ID of the creative; unique at least throughout the scope of a vendor (e.g., an exchange or buying platform). Note that multiple instances of the same ad when used in transactions must have the same ID. type: string iurl: description: >- URL without cache-busting to an image that is representative of the ad content for cursory level ad quality checking. type: - string - 'null' lang: description: >- Language of the creative using ISO-639-1-alpha-2. In practice, vendors using this object may elect an alternate standard (e.g., BCP-47) in which case this must be communicated beforehand. The non-standard code “xx” may also be used if the creative has no linguistic content (e.g., a banner with just a company logo). type: - string - 'null' video: anyOf: - $ref: '#/components/schemas/Video' - type: 'null' description: >- Creative Subtype Object that indicates this is a video ad and provides additional detail as such. required: - id 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 CategoryTaxonomy: oneOf: - enum: - IABTechLabAdProductTaxonomy1_0 - IABTechLabAudienceTaxonomy1_1 - IABTechLabContentCategoryTaxonomy2_1 - IABTechLabContentCategoryTaxonomy2_2 - IABTechLabContentCategoryTaxonomy3_0 - IABTechLabAdProductTaxonomy2_0 type: string - deprecated: true enum: - IABTechLabContentCategoryTaxonomy1_0 type: string - deprecated: true enum: - IABTechLabContentCategoryTaxonomy2_0 type: string - additionalProperties: false properties: VendorSpecific: format: uint16 minimum: 0 type: integer required: - VendorSpecific type: object Display: properties: adm: type: - string - 'null' api: items: $ref: '#/components/schemas/ApiFramework' type: - array - 'null' banner: anyOf: - $ref: '#/components/schemas/Banner' - type: 'null' description: Structured banner image object for banner creatives. ctype: items: $ref: '#/components/schemas/CreativeSubtypesDisplay' type: - array - 'null' curl: type: - string - 'null' event: items: $ref: '#/components/schemas/Event' type: - array - 'null' ext: description: Optional A2-specific extensions. h: description: Absolute height of the creative in device independent pixels (DIPS). format: uint32 minimum: 0 type: - integer - 'null' hratio: format: uint32 minimum: 0 type: - integer - 'null' mime: description: Mime type of the ad (e.g., “image/jpeg”). type: - string - 'null' native: anyOf: - $ref: '#/components/schemas/Native' - type: 'null' description: Structured native object for native ads. priv: type: - string - 'null' w: description: Absolute width of the creative in device independent pixels (DIPS). format: uint32 minimum: 0 type: - integer - 'null' wratio: format: uint32 minimum: 0 type: - integer - 'null' type: object Video: properties: adm: type: - string - 'null' api: items: $ref: '#/components/schemas/ApiFramework' type: - array - 'null' ctype: anyOf: - $ref: '#/components/schemas/CreativeSubtypesAudioVideo' - type: 'null' curl: type: - string - 'null' dur: format: uint32 minimum: 0 type: - integer - 'null' ext: true mime: items: type: string type: - array - 'null' type: object IpLocationService: enum: - 1 - 2 - 3 - 4 type: integer LocationType: enum: - 1 - 2 - 3 type: integer ApiFramework: oneOf: - enum: - VPAID1_0 - VPAID2_0 - MRAID1_0 - ORMMA - MRAID2_0 - MRAID3_0 - OMID1_0 - SIMID1_0 - SIMID1_1 type: string - additionalProperties: false properties: VendorSpecific: format: uint16 minimum: 0 type: integer required: - VendorSpecific type: object Banner: properties: ext: true img: type: string link: anyOf: - $ref: '#/components/schemas/LinkAsset' - type: 'null' required: - img type: object CreativeSubtypesDisplay: enum: - HTML - AMPHTML - StructuredImageObject - StructuredNativeObject type: string Event: properties: api: items: $ref: '#/components/schemas/ApiFramework' type: - array - 'null' cdata: true ext: true method: $ref: '#/components/schemas/EventTrackingMethod' type: $ref: '#/components/schemas/EventType' url: type: string required: - method - type - url type: object Native: properties: asset: items: $ref: '#/components/schemas/Asset' type: - array - 'null' ext: true link: anyOf: - $ref: '#/components/schemas/LinkAsset' - type: 'null' type: object CreativeSubtypesAudioVideo: oneOf: - enum: - VAST1_0 - VAST2_0 - VAST3_0 - VAST1_0Wrapper - VAST2_0Wrapper - VAST3_0Wrapper - VAST4_0 - VAST4_0Wrapper - DAAST1_0 - DAAST1_0Wrapper - VAST4_1 - VAST4_1Wrapper - VAST4_2 - VAST4_2Wrapper type: string - additionalProperties: false properties: VendorSpecific: format: uint16 minimum: 0 type: integer required: - VendorSpecific type: object LinkAsset: description: >- This object identifies the native asset as a link asset and is used to define navigation for call-to-action or other activations (i.e., clicks). A link asset can be independent or associated with the overall native ad (i.e., a default for all assets). properties: ext: true trkr: items: type: string type: - array - 'null' url: type: string urlfb: type: - string - 'null' required: - url type: object EventTrackingMethod: enum: - 1 - 2 type: integer EventType: enum: - 1 - 2 - 3 - 4 - 5 type: integer Asset: properties: data: anyOf: - $ref: '#/components/schemas/DataAsset' - type: 'null' ext: true id: format: int32 type: - integer - 'null' image: anyOf: - $ref: '#/components/schemas/ImageAsset' - type: 'null' link: anyOf: - $ref: '#/components/schemas/LinkAsset' - type: 'null' req: anyOf: - $ref: '#/components/schemas/IsRequired' - type: 'null' title: anyOf: - $ref: '#/components/schemas/TitleAsset' - type: 'null' video: anyOf: - $ref: '#/components/schemas/VideoAsset' - type: 'null' type: object DataAsset: description: >- This object identifies the native asset as a data asset. A data asset is used for all miscellaneous elements such as brand name, ratings, stars, review count, downloads, price, counts, etc. It is purposefully generic to support native elements not currently contemplated by this specification. properties: ext: true len: format: int32 type: - integer - 'null' type: anyOf: - $ref: '#/components/schemas/NativeDataAssetType' - type: 'null' value: type: string required: - value type: object ImageAsset: description: >- This object identifies the native asset as a image asset. Image assets are use for such elements as the actual creative images and icons. properties: ext: true h: format: uint32 minimum: 0 type: - integer - 'null' type: anyOf: - $ref: '#/components/schemas/NativeImageAssetType' - type: 'null' url: type: string w: format: uint32 minimum: 0 type: - integer - 'null' required: - url type: object IsRequired: enum: - 0 - 1 type: integer TitleAsset: description: >- This object identifies the native asset as a title asset, which is essentially just a plain text string with specified length. properties: ext: true len: format: uint32 minimum: 0 type: - integer - 'null' text: type: string required: - text type: object VideoAsset: description: >- This object identifies the native asset as a video asset. Video markup (e.g., VAST) must be either included or referenced. properties: adm: type: - string - 'null' curl: type: - string - 'null' ext: true type: object NativeDataAssetType: enum: - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 type: integer NativeImageAssetType: enum: - 1 - 2 - 3 type: integer ````