> ## 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 an ad > Returns an ad for the ad unit tag (`tagid`) and the request payload. Selects the most suitable ad using line item, creative, and bidding strategy data, and returns the final ad decided through DSP responses and internal mediation. The response includes `ext.ad_log` for event tracking. When no ad is available, the server returns HTTP 204 without a response body, or HTTP 200 with the ad unit's passback if one is configured (see the 200 response). ## OpenAPI ````yaml /openapi/decision.api.en-dev.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: 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/ad/{tagid}: post: tags: - Ad Serving summary: Request an ad description: >- Returns an ad for the ad unit tag (`tagid`) and the request payload. Selects the most suitable ad using line item, creative, and bidding strategy data, and returns the final ad decided through DSP responses and internal mediation. The response includes `ext.ad_log` for event tracking. When no ad is available, the server returns HTTP 204 without a response body, or HTTP 200 with the ad unit's passback if one is configured (see the 200 response). 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/AdServingRequest' 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: ab_test: bucket_id: 0 experiment_id: experiment-123 ad_log: >- YTU2ZDY2ZjctNDM4ZS00OTVjLWJiYTAtMjI4Mzk2MjQ0ZWVkfDA2NDI4NjYwLWY2NDMtNGVmNS05MzgzLTZjZmE1OGYxOGI2OXxjNTZkYzNiZi05MzVkLTRlZTYtYjFlZC1mMzFiZmMwMmJlOTF8NGJlMmQ4ZTYtYThhMS00NzI2LWEzMjAtNjkyNTYzMDkwZTQyfDllZjY2ZGM4LTBlMmMtNDlmMS05NDU3LWFmYmUwZGQ2ZjU3M3w1NTgxNmIzOTcxMWY5YjVhY2YzYjkwZTMxM2VkMjllNTE2NjU2MjNm message: success version: 0.1.0 schema: $ref: '#/components/schemas/AdServingResponse' description: >- Returned ad, or the ad unit's passback when no ad is available and a passback tag is configured. A passback response has `errorcode: "204"`, `ext.passback`, and no `ad`. An A/B assignment appears only when applicable; the example illustrates an assigned request. '204': description: No Bid. '400': content: text/plain: schema: type: string description: Failed to parse the request body as JSON '415': content: text/plain: schema: type: string description: 'Expected request with `Content-Type: application/json`' '422': content: text/plain: schema: type: string description: Failed to deserialize the JSON body into the target type '500': content: application/json: schema: $ref: '#/components/schemas/AdServingErrorResponse' description: >- Invalid tagid or referenced AdUnit not found. The response contains a JSON error. security: - '': [] components: schemas: AdServingRequest: properties: ad_size: description: Ad sizes requested for the ad. items: items: format: int32 type: integer maxItems: 2 minItems: 2 type: array type: - array - 'null' 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 ext: anyOf: - $ref: '#/components/schemas/AdServingRequestExt' - type: 'null' description: >- Optional ad serving options. Set `echo_user` to true to include `user` in a successful ad response. site: anyOf: - $ref: '#/components/schemas/ServingRequestSite' - type: 'null' description: Site object for the current serving request. targeting: description: Targeting key-value pairs for the ad 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 AdServingResponse: properties: ad: anyOf: - $ref: '#/components/schemas/Ad' - type: 'null' description: Served ad. Absent in passback and error responses. errorcode: description: Error code if the request failed. type: - string - 'null' ext: anyOf: - $ref: '#/components/schemas/AdServingResponseExt' - type: 'null' description: >- Tracking, experiment assignment, or passback details, depending on the response. 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 type: object AdServingErrorResponse: properties: errorcode: type: string ext: $ref: '#/components/schemas/AdServingErrorDetails' version: type: string required: - version - errorcode - 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 AdServingRequestExt: additionalProperties: true properties: echo_user: default: false description: >- Echo the request user in a successful ad response. Defaults to false. This option does not apply to passback or error responses. type: boolean 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 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: description: >- The taxonomy in use for the cat attribute. Refer to List: Category Taxonomies. format: uint16 maximum: 65535 minimum: 0 type: - integer - 'null' 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 AdServingResponseExt: additionalProperties: true properties: ab_test: anyOf: - $ref: '#/components/schemas/AdExperimentAssignment' - type: 'null' description: >- Present when the served request was assigned to an A/B experiment bucket. ad_log: description: >- Opaque tracking token returned for a served ad. Send it as `ad_log` in subsequent ad log events. type: - string - 'null' message: description: >- `success` for a served ad, or an error description on an error response. type: - string - 'null' passback: description: >- Configured passback tag. A passback response has HTTP 200, `errorcode: "204"`, no `ad`, and this field instead of the normal success extensions. type: - string - 'null' type: object AdServingErrorDetails: 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 Display: properties: adm: type: - string - 'null' api: items: format: uint16 maximum: 65535 minimum: 0 type: integer type: - array - 'null' banner: anyOf: - $ref: '#/components/schemas/Banner' - type: 'null' description: Structured banner image object for banner creatives. ctype: items: format: uint8 maximum: 255 minimum: 0 type: integer 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/NativeType' - 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: format: uint16 maximum: 65535 minimum: 0 type: integer type: - array - 'null' ctype: format: uint16 maximum: 65535 minimum: 0 type: - integer - 'null' curl: type: - string - 'null' dur: format: uint32 minimum: 0 type: - integer - 'null' ext: true mime: items: type: string type: - array - 'null' type: object AdExperimentAssignment: properties: bucket_id: description: Assigned experiment bucket. format: uint8 maximum: 255 minimum: 0 type: integer experiment_id: description: Experiment identifier. type: string required: - experiment_id - bucket_id type: object IpLocationService: enum: - 1 - 2 - 3 - 4 type: integer LocationType: enum: - 1 - 2 - 3 type: integer Banner: properties: ext: true img: type: string link: anyOf: - $ref: '#/components/schemas/LinkAsset' - type: 'null' required: - img type: object Event: properties: api: items: format: uint16 maximum: 65535 minimum: 0 type: integer type: - array - 'null' cdata: true ext: true method: $ref: '#/components/schemas/EventTrackingMethod' type: $ref: '#/components/schemas/EventType' url: type: string required: - type - method - url type: object NativeType: anyOf: - $ref: '#/components/schemas/Native' title: Native - $ref: '#/components/schemas/NativeResponse' title: NativeResponse 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 Native: properties: asset: items: $ref: '#/components/schemas/Asset' type: - array - 'null' ext: true link: anyOf: - $ref: '#/components/schemas/LinkAsset' - type: 'null' type: object NativeResponse: properties: assets: items: $ref: '#/components/schemas/AssetResponse' type: - array - 'null' assetsurl: type: - string - 'null' dcourl: type: - string - 'null' eventtrackers: items: $ref: '#/components/schemas/EventTrackerResponse' type: - array - 'null' ext: true imptrackers: items: type: string type: - array - 'null' jstracker: type: - string - 'null' link: true privacy: type: - string - 'null' ver: type: - string - 'null' required: - link type: object 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 AssetResponse: properties: data: anyOf: - $ref: '#/components/schemas/DataAssetResponse' - type: 'null' ext: true id: format: int32 type: integer img: anyOf: - $ref: '#/components/schemas/ImageAssetResponse' - type: 'null' link: anyOf: - $ref: '#/components/schemas/LinkAssetResponse' - type: 'null' required: anyOf: - $ref: '#/components/schemas/IsRequired2' - type: 'null' title: anyOf: - $ref: '#/components/schemas/TitleAssetResponse' - type: 'null' video: anyOf: - $ref: '#/components/schemas/VideoAssetResponse' - type: 'null' required: - id type: object EventTrackerResponse: properties: customdata: true event: format: uint16 maximum: 65535 minimum: 0 type: integer ext: true method: format: uint16 maximum: 65535 minimum: 0 type: integer url: type: - string - 'null' required: - event - method 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 x-enum-varnames: - 'No' - 'Yes' 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 DataAssetResponse: properties: ext: true len: format: uint32 minimum: 0 type: - integer - 'null' type: format: uint16 maximum: 65535 minimum: 0 type: - integer - 'null' value: type: string required: - value type: object ImageAssetResponse: properties: ext: true h: format: uint32 minimum: 0 type: - integer - 'null' type: format: uint16 maximum: 65535 minimum: 0 type: - integer - 'null' url: type: string w: format: uint32 minimum: 0 type: - integer - 'null' required: - url type: object LinkAssetResponse: properties: clicktrackers: items: type: string type: - array - 'null' ext: true fallback: type: - string - 'null' url: type: string required: - url type: object IsRequired2: enum: - 0 - 1 type: integer x-enum-varnames: - 'No' - 'Yes' TitleAssetResponse: properties: ext: true len: format: uint32 minimum: 0 type: - integer - 'null' text: type: string required: - text type: object VideoAssetResponse: properties: vasttag: type: string required: - vasttag type: object NativeDataAssetType: enum: - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 500 type: integer x-enum-varnames: - Sponsored - Desc - Rating - Likes - Downloads - Price - SalePrice - Phone - Address - Desc2 - DisplayUrl - CtaText - Other NativeImageAssetType: enum: - 1 - 2 - 3 - 4 - 500 type: integer x-enum-varnames: - Icon - Main - Logo - Thumbnail - Other ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.