> ## 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. # Update cached ad units > Stores ad_unit information in the cache. Used to update serving logic based on ad_unit metadata. ## OpenAPI ````yaml /openapi/decision.api.en-dev.json post /app/api/cache/ad-units 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/api/cache/ad-units: post: tags: - Cache Management summary: Update cached ad units description: | Stores ad_unit information in the cache. Used to update serving logic based on ad_unit metadata. requestBody: content: application/json: schema: items: $ref: '#/components/schemas/AdUnit' type: array required: true responses: '204': description: Success '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': description: Internal Server Error. security: - '': [] components: schemas: AdUnit: properties: ad_unit_sizes: description: |- Targeting metadata sizes Distinct from display/video.w/h which govern serving and rendering. items: $ref: '#/components/schemas/AdUnitSize' type: - array - 'null' code: description: Ad unit code identifier. type: string created_at: description: The date and time when the ad unit was created. format: date-time type: string created_by: description: The ID of the user who created the ad unit. format: uuid type: string description: description: Description of the ad unit. type: - string - 'null' display: allOf: - $ref: '#/components/schemas/DisplayPlacement' default: clktype: 1 priv: 0 unit: 2 description: >- Placement Subtype Object that indicates that this may be a display placement and provides additional detail related thereto. ext: allOf: - $ref: '#/components/schemas/AdUnitExt' default: algorithm: axa0 approval_method: admin bcat: [] default_cpa: 0 default_cpc: 0 display: enabled: 1 native: enabled: 0 render_mode: html payout: rates recommendation: enabled: 0 responsive: fixed target_ecpm: 0 video: enabled: 0 description: >- Additional ad unit-specific extensions. Defaults to the `AdUnitExt` object. gpid: description: Canonical Placement ID for OpenRTB imp.ext.gpid. type: - string - 'null' id: description: ID of the ad unit (uuid7) format: uuid type: string instl: allOf: - $ref: '#/components/schemas/Instl' default: 0 description: >- Indicates if this is an interstitial placement, where 0 = no, 1 = yes. Applies across display, video, and native. is_active: description: |- Whether the ad unit is active. Superseded by `status`. Kept until every consumer reads `status`. type: - boolean - 'null' name: description: Name of the ad unit. type: string native: allOf: - $ref: '#/components/schemas/NativePlacement' default: assets: [] description: >- Based on OpenRTB Native Ads 1.2 Native Markup Request Object, not the AdCOM standard native format path: description: Hierarchical path of the ad unit (e.g., "parent_id/child_id"). type: string recommendation: allOf: - $ref: '#/components/schemas/RecommendationPlacement' default: ext: {} topn: 10 status: allOf: - $ref: '#/components/schemas/AdUnitStatus' default: INACTIVE description: Operational status of the ad unit. Defaults to `Inactive`. video: allOf: - $ref: '#/components/schemas/VideoPlacement' default: boxing: 1 maxext: 0 podseq: 0 skipafter: 0 skipmin: 0 slotinpod: 0 unit: 2 description: >- Placement Subtype Object that indicates that this may be a video placement and provides additional detail related thereto. required: - id - name - code - path - created_by - created_at type: object AdUnitSize: description: A targeting size entry for an ad unit properties: h: description: Height in pixels. format: uint32 minimum: 0 type: integer w: description: Width in pixels. format: uint32 minimum: 0 type: integer required: - w - h type: object DisplayPlacement: properties: ampren: format: uint8 maximum: 255 minimum: 0 type: - integer - 'null' api: items: format: uint16 maximum: 65535 minimum: 0 type: integer type: - array - 'null' clktype: default: 1 format: uint8 maximum: 255 minimum: 0 type: integer context: anyOf: - $ref: '#/components/schemas/DisplayContext' - type: 'null' ctype: items: format: uint8 maximum: 255 minimum: 0 type: integer type: - array - 'null' displayfmt: anyOf: - $ref: '#/components/schemas/DisplayFormat' - type: 'null' event: items: $ref: '#/components/schemas/EventSpec' type: - array - 'null' ext: true h: format: float type: - number - 'null' ifrbust: items: type: string type: - array - 'null' mime: items: type: string type: - array - 'null' pos: anyOf: - $ref: '#/components/schemas/PlacementPosition' - type: 'null' priv: default: 0 format: uint8 maximum: 255 minimum: 0 type: integer ptype: anyOf: - $ref: '#/components/schemas/DisplayPlacementTypes' - type: 'null' topframe: format: uint8 maximum: 255 minimum: 0 type: - integer - 'null' unit: default: 2 format: uint8 maximum: 255 minimum: 0 type: integer w: format: float type: - number - 'null' type: object AdUnitExt: properties: algorithm: default: axa0 description: Algorithm used for the ad unit. type: string approval_method: allOf: - $ref: '#/components/schemas/AdUnitApproval' default: admin description: Approval method for the ad unit. bcat: default: [] description: >- Blocked advertiser categories using the IAB taxonomy, and extended with additional sensitive categories. items: type: string type: - array - 'null' default_cpa: default: 0 description: >- Default CPA, for CPA line item that has no specific target CPA. Defaults to 0.0. format: double type: number default_cpc: default: 0 description: >- Default CPC, for CPC line item that has no specific target CPC. Defaults to 0.0. format: double type: number display: default: enabled: 0 description: Display-specific extension data in JSON format. external_raw_data: description: External raw data for the ad unit, represented as a map. implicit_app_inference: anyOf: - $ref: '#/components/schemas/ImplicitAppInference' - type: 'null' description: >- Configuration for fallback/implicit mobile app inference via UA keyword mapping. native: allOf: - $ref: '#/components/schemas/AdUnitExtNative' default: enabled: 0 render_mode: html description: Native-specific extension data. passback: description: Passback ad tags for the ad unit, represented as a map. payout: allOf: - $ref: '#/components/schemas/AdUnitPayout' default: rates description: Payout type for the ad unit. public_url: description: |- Public URL override for this ad unit's event tracker URLs. If set, overrides EdgeConfig.public_url for this ad unit. type: - string - 'null' publisher: anyOf: - $ref: '#/components/schemas/PublisherSettings' - type: 'null' description: Publisher identity sent on the OpenRTB site/app object. recommendation: default: enabled: 0 description: Recommendation-specific extension data in JSON format. responsive: allOf: - $ref: '#/components/schemas/AdUnitResponsiveness' default: fixed description: Indicates whether the ad unit is responsive. target_ecpm: default: 0 description: >- Target eCPM (effective cost per mille) for the ad unit. Defaults to 0.0. format: double type: number target_service: description: Target service for the ad unit. type: - string - 'null' video: default: enabled: 0 description: Video-specific extension data in JSON format. type: object Instl: description: OpenRTB interstitial flag. enum: - 0 - 1 type: integer x-enum-varnames: - 'No' - 'Yes' NativePlacement: description: >- Based on OpenRTB Native Ads 1.2 Native Markup Request Object, not the AdCOM standard native format properties: assets: default: [] description: Native asset request definitions for this placement. items: $ref: '#/components/schemas/AssetRequest' type: array context: description: >- OpenRTB Native context type (1=ContentCentric, 2=SocialCentric, 3=ProductContext) format: uint16 maximum: 65535 minimum: 0 type: - integer - 'null' contextsubtype: description: OpenRTB Native context subtype (e.g. 14=PrimarilyImageContent) format: uint16 maximum: 65535 minimum: 0 type: - integer - 'null' ext: description: Optional vendor-specific extensions. plcmtcnt: description: OpenRTB Native placement count format: uint8 maximum: 255 minimum: 1 type: - integer - 'null' plcmttype: description: >- OpenRTB Native placement type (1=Feed, 2=AtomicUnit, 3=OutsideOfContent, 4=RecommendationWidget) format: uint16 maximum: 65535 minimum: 0 type: - integer - 'null' type: object RecommendationPlacement: properties: ad_log_tracking_mode: anyOf: - $ref: '#/components/schemas/AdLogTrackingMode' - type: 'null' description: >- When a recommendation impression is recorded. Missing and null values are interpreted as `on_event_tracker` to preserve the behavior that predates response-time recommendation impressions. candidate_filtering: anyOf: - $ref: '#/components/schemas/CandidateFiltering' - type: 'null' description: Candidate filtering. content_filter_rule: anyOf: - $ref: '#/components/schemas/Expr' - type: 'null' description: Content filter rule. ext: default: {} description: Additional ad unit-specific extensions. fallback: description: Fallback chain, tried in order until every slot is filled. items: $ref: '#/components/schemas/RecommendationFallback' type: - array - 'null' topn: default: 10 description: Number of items to recommend. format: uint32 maximum: 99 minimum: 0 type: integer type: object AdUnitStatus: description: Operational status of an ad unit. oneOf: - const: ACTIVE description: The ad unit is active and available for targeting. title: ACTIVE type: string - const: INACTIVE description: The ad unit is inactive and not available for targeting. title: INACTIVE type: string - const: ARCHIVED description: >- The ad unit has been archived and is no longer subject to modification or targeting. title: ARCHIVED type: string VideoPlacement: properties: api: items: format: uint16 maximum: 65535 minimum: 0 type: integer type: - array - 'null' boxing: default: 1 format: uint8 maximum: 255 minimum: 0 type: - integer - 'null' clktype: format: uint8 maximum: 255 minimum: 0 type: - integer - 'null' comp: items: $ref: '#/components/schemas/Companion' type: - array - 'null' comptype: items: $ref: '#/components/schemas/CompanionType' type: - array - 'null' ctype: items: format: uint32 minimum: 0 type: integer type: - array - 'null' delay: format: uint32 minimum: 0 type: - integer - 'null' delivery: items: $ref: '#/components/schemas/DeliveryMethod' type: - array - 'null' expdir: items: $ref: '#/components/schemas/ExpandableDirection' type: - array - 'null' ext: true h: format: uint32 minimum: 0 type: - integer - 'null' linear: format: uint32 minimum: 0 type: - integer - 'null' maxbitr: format: uint32 minimum: 0 type: - integer - 'null' maxdur: format: uint32 minimum: 0 type: - integer - 'null' maxext: default: 0 format: int32 type: - integer - 'null' maxseq: format: uint32 minimum: 0 type: - integer - 'null' mime: items: type: string type: - array - 'null' minbitr: format: uint32 minimum: 0 type: - integer - 'null' mincpmpersec: format: double type: - number - 'null' mindur: format: uint32 minimum: 0 type: - integer - 'null' overlayexpdir: items: $ref: '#/components/schemas/ExpandableDirection' type: - array - 'null' playend: anyOf: - $ref: '#/components/schemas/PlaybackCessationMode' - type: 'null' playmethod: items: format: uint8 maximum: 255 minimum: 0 type: integer type: - array - 'null' poddur: format: uint32 minimum: 0 type: - integer - 'null' podid: format: uint32 minimum: 0 type: - integer - 'null' podseq: default: 0 format: int8 maximum: 127 minimum: -128 type: - integer - 'null' pos: anyOf: - $ref: '#/components/schemas/PlacementPosition' - type: 'null' ptype: format: uint8 maximum: 255 minimum: 0 type: - integer - 'null' rqddurs: items: format: uint32 minimum: 0 type: integer type: - array - 'null' skip: format: uint8 maximum: 255 minimum: 0 type: - integer - 'null' skipafter: default: 0 format: uint32 minimum: 0 type: - integer - 'null' skipmin: default: 0 format: uint32 minimum: 0 type: - integer - 'null' slotinpod: default: 0 format: int8 maximum: 127 minimum: -128 type: - integer - 'null' unit: default: 2 format: uint8 maximum: 255 minimum: 0 type: - integer - 'null' w: format: uint32 minimum: 0 type: - integer - 'null' type: object DisplayContext: enum: - ContentCentric - ArticleContent - VideoContent - AudioContent - ImageContent - UserGeneratedContent - SocialCentric - EmailContent - ChatContent - ProductContext - AppStore - ProductReviews type: string DisplayFormat: properties: expdir: anyOf: - $ref: '#/components/schemas/ExpandableDirection' - type: 'null' ext: true h: format: uint32 minimum: 0 type: - integer - 'null' hratio: format: uint32 minimum: 0 type: - integer - 'null' w: format: uint32 minimum: 0 type: - integer - 'null' wratio: format: uint32 minimum: 0 type: - integer - 'null' type: object EventSpec: properties: api: items: format: uint16 maximum: 65535 minimum: 0 type: integer type: - array - 'null' ext: true jstrk: items: type: string type: - array - 'null' method: items: $ref: '#/components/schemas/EventTrackingMethod' type: - array - 'null' pxtrk: items: type: string type: - array - 'null' type: $ref: '#/components/schemas/EventType' wjs: default: 1 format: int32 type: integer wpx: default: 1 format: int32 type: integer required: - type type: object PlacementPosition: enum: - Unknown - AboveTheFold - Locked - BelowTheFold - Header - Footer - Sidebar - FullScreen type: string DisplayPlacementTypes: enum: - Feed - AtomicUnit - OutsideCore - RecommendationWidget type: string AdUnitApproval: enum: - admin - delegate type: string ImplicitAppInference: properties: android_bundle: type: - string - 'null' app_name: type: - string - 'null' cat: items: type: string type: - array - 'null' ios_bundle: type: - string - 'null' ua_keywords: default: [] items: type: string type: array type: object AdUnitExtNative: properties: enabled: default: 0 description: Whether native ads are enabled for the ad unit (0 or 1). format: int64 type: integer render_mode: allOf: - $ref: '#/components/schemas/NativeRenderMode' default: html description: Native rendering mode for this ad unit. type: object AdUnitPayout: enum: - rates - revenue_share - none type: string PublisherSettings: description: 'OpenRTB 2.6 Publisher: every field is optional.' properties: company: type: - string - 'null' domain: type: - string - 'null' ext: true id: type: - string - 'null' name: type: - string - 'null' page: type: - string - 'null' seller_id: type: - string - 'null' type: object AdUnitResponsiveness: enum: - fixed - resized type: string AssetRequest: anyOf: - required: - title title: title - required: - img title: img - required: - video title: video - required: - data title: data properties: data: anyOf: - $ref: '#/components/schemas/DataAssetRequest' - type: 'null' ext: true id: format: int32 type: integer img: anyOf: - $ref: '#/components/schemas/ImageAssetRequest' - type: 'null' required: anyOf: - $ref: '#/components/schemas/IsRequired2' - type: 'null' title: anyOf: - $ref: '#/components/schemas/TitleAssetRequest' - type: 'null' video: anyOf: - $ref: '#/components/schemas/VideoAssetRequest' - type: 'null' required: - id type: object 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 CandidateFiltering: properties: method: allOf: - $ref: '#/components/schemas/CandidateFilteringMethod' default: NoFilter description: Filtering method. type: object Expr: oneOf: - properties: data: $ref: '#/components/schemas/Compare' type: const: cmp type: string required: - type - data title: cmp type: object - properties: data: items: $ref: '#/components/schemas/Expr' type: array type: const: and type: string required: - type - data title: and type: object - properties: data: items: $ref: '#/components/schemas/Expr' type: array type: const: or type: string required: - type - data title: or type: object - properties: data: $ref: '#/components/schemas/Expr' type: const: not type: string required: - type - data title: not type: object RecommendationFallback: description: >- One step of a fallback chain, filling the slots the recommendation left empty. oneOf: - allOf: - $ref: '#/components/schemas/PopularFallback' description: Fill from the popularity ranking. properties: type: const: popular type: string required: - type title: popular type: object - allOf: - $ref: '#/components/schemas/PresetFallback' description: Fill from items listed in the configuration. properties: type: const: preset type: string required: - type title: preset type: object - allOf: - $ref: '#/components/schemas/SnapshotFallback' description: Fill from a local snapshot file. properties: type: const: snapshot type: string required: - type title: snapshot type: object Companion: properties: display: anyOf: - $ref: '#/components/schemas/DisplayPlacement' - type: 'null' ext: true id: type: - string - 'null' vcm: format: int32 type: - integer - 'null' type: object CompanionType: enum: - Static - HTML - IFrame type: string DeliveryMethod: enum: - Streaming - Progressive - Download type: string ExpandableDirection: enum: - Left - Right - Up - Down - FullScreen - ResizeMinimize type: string PlaybackCessationMode: enum: - OnVideoCompletion - OnLeavingViewport - OnLeavingViewportContinuesAsAUnit type: string EventTrackingMethod: enum: - 1 - 2 type: integer EventType: enum: - 1 - 2 - 3 - 4 - 5 type: integer NativeRenderMode: description: >- Native rendering mode: server-rendered HTML markup, or raw asset data for client-side rendering. enum: - html - asset type: string DataAssetRequest: properties: ext: true len: format: uint32 minimum: 0 type: - integer - 'null' type: format: uint16 maximum: 65535 minimum: 0 type: integer required: - type type: object ImageAssetRequest: properties: ext: true h: format: uint32 minimum: 0 type: - integer - 'null' hmin: format: uint32 minimum: 0 type: - integer - 'null' mimes: items: type: string type: - array - 'null' type: format: uint16 maximum: 65535 minimum: 0 type: - integer - 'null' w: format: uint32 minimum: 0 type: - integer - 'null' wmin: format: uint32 minimum: 0 type: - integer - 'null' type: object IsRequired2: enum: - 0 - 1 type: integer x-enum-varnames: - 'No' - 'Yes' TitleAssetRequest: properties: ext: true len: format: uint32 minimum: 0 type: integer required: - len type: object VideoAssetRequest: properties: ext: true linearity: anyOf: - $ref: '#/components/schemas/LinearityMode' - type: 'null' maxduration: format: uint32 minimum: 0 type: integer mimes: items: type: string type: array minduration: format: uint32 minimum: 0 type: integer protocols: items: format: uint16 maximum: 65535 minimum: 0 type: integer type: array required: - mimes - minduration - maxduration - protocols type: object CandidateFilteringMethod: enum: - NoFilter - ViewPenalty - ViewOut type: string Compare: properties: lhs: items: type: string type: array op: $ref: '#/components/schemas/Op' rhs: true required: - lhs - op - rhs type: object PopularFallback: description: Fill from the popularity ranking (`RankedItemPool`). properties: activation: allOf: - $ref: '#/components/schemas/FallbackActivation' default: except_timeout description: >- When this step serves, relative to the recommendation running out of time. serving_context: default: all description: >- Context to query within the popularity pool (e.g. `all`, `A:`). examples: - all - A:83031007-09d1-45d5-abe1-071b3763d876 - AU:83031007-09d1-45d5-abe1-071b3763d876:user1 - ABU:83031007-09d1-45d5-abe1-071b3763d876:1:user1 type: string type: object PresetFallback: description: Fill from items listed in the configuration itself. properties: activation: allOf: - $ref: '#/components/schemas/FallbackActivation' default: always description: >- When this step serves, relative to the recommendation running out of time. items: default: [] description: Candidate items. items: $ref: '#/components/schemas/FallbackItem' type: array order: allOf: - $ref: '#/components/schemas/FallbackOrder' default: sequential description: How the items are laid into the slots. type: object SnapshotFallback: description: Fill from a snapshot file local to the serving host. properties: activation: allOf: - $ref: '#/components/schemas/FallbackActivation' default: always description: >- When this step serves, relative to the recommendation running out of time. order: allOf: - $ref: '#/components/schemas/FallbackOrder' default: sequential description: How the items are laid into the slots. path: description: Path of the snapshot file. type: string required: - path type: object LinearityMode: enum: - 1 - 2 type: integer x-enum-varnames: - Linear - NonLinear Op: enum: - eq - ne - lt - le - gt - ge - in - nin - intersects type: string FallbackActivation: description: >- When a fallback step serves, relative to the recommendation running out of time. oneOf: - const: always description: Whether or not the recommendation ran out of time. title: always type: string - const: except_timeout description: Only when the recommendation finished in time. title: except_timeout type: string - const: timeout_only description: Only when the recommendation ran out of time. title: timeout_only type: string FallbackItem: description: >- One item a fallback serves, listed in a preset or read from a snapshot file. properties: expire: description: When the item stops being served. Never, when absent. format: date-time type: - string - 'null' id: description: Item id (`catalogs.id`). type: string required: - id type: object FallbackOrder: description: How a fallback's items are laid into the slots. oneOf: - const: sequential description: In the order the items are listed. title: sequential type: string - const: random description: Shuffled uniformly at random per request. title: random type: string ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.