# Request API: AD endpoint

The **AD endpoint** is used for integrations that can't parse a JSON response and require the response in a specific markup instead. It is typically used for [video and audio setups](https://documentation.adhese.org/books/integration-setup/page/vast-video-audio-advertising), where ads are requested by media players and follow the [VAST](https://iabtechlab.com/standards/vast/) protocol in XML.

The API is public and requires no authentication and **cookies are not required** for an integration to work.

## Request method

The AD endpoint supports **GET requests only**. As with the GET version of the JSON endpoint, **slot-level parameters are not supported**.

<p class="callout warning">Unlike the JSON endpoint, only one placement can be retrieved with each call</p>

## URL structure

A request URL is built from the sections below, in order. Sections marked *repeatable* can appear more than once.

<div class="overflow-x-auto w-full px-2 mb-6" data-sourcepos="13:1-19:71;610-1396" id="bkmrk-section-repeatable-d"><table class="min-w-full border-collapse text-sm leading-[1.7] whitespace-normal" style="width: 100%;"><thead class="text-left"><tr><th class="text-text-100 border-b-0.5 border-[hsl(var(--border-300)/0.6)] py-2 pr-4 align-top font-bold" scope="col" style="width: 19.9021%;">Section</th><th class="text-text-100 border-b-0.5 border-[hsl(var(--border-300)/0.6)] py-2 pr-4 align-top font-bold" scope="col" style="width: 10.1337%;">Repeatable</th><th class="text-text-100 border-b-0.5 border-[hsl(var(--border-300)/0.6)] py-2 pr-4 align-top font-bold" scope="col" style="width: 69.9642%;">Description</th></tr></thead><tbody><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 19.9021%;">`https://ads-[account].adhese.com`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 10.1337%;">No</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 69.9642%;">The domain — either the default ads domain for your account or a configured first-party domain. See [First-party domains](#bkmrk-when-handling-errors) for more info.</td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 19.9021%;">`/ad/`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 10.1337%;">No</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 69.9642%;">Fixed path segment that selects the AD endpoint.</td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 19.9021%;">`/sl[location code]-[format code]/`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 10.1337%;">No</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 69.9642%;">A placement (slot). Starts with the prefix `sl`, followed by the full slot code. </td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 19.9021%;">`/ct[value];[value]/`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 10.1337%;">Yes</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 69.9642%;">A target section. Starts with its predefined prefix (e.g. `ct`) and is followed by a single value or a list of values separated by `;`. Add one section per target group you want to pass.</td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 19.9021%;">`?t=[timestamp]`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 10.1337%;">No</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 69.9642%;">A timestamp, used to avoid caching issues.</td></tr></tbody></table>

</div>## Example request

```
https://ads-demo.adhese.com/ad/sldemo.com_kitchen-billboard/dtdesktop
```

Broken down:

<div class="overflow-x-auto w-full px-2 mb-6" data-sourcepos="29:1-34:69;1511-1828" id="bkmrk-part-meaning-https%3A%2F"><table class="min-w-full border-collapse text-sm leading-[1.7] whitespace-normal"><thead class="text-left"><tr><th class="text-text-100 border-b-0.5 border-[hsl(var(--border-300)/0.6)] py-2 pr-4 align-top font-bold" scope="col">Part</th><th class="text-text-100 border-b-0.5 border-[hsl(var(--border-300)/0.6)] py-2 pr-4 align-top font-bold" scope="col">Meaning</th></tr></thead><tbody><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top">`https://ads-demo.adhese.com`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top">Ads domain for the `demo` account</td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top">`/ad/`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top">AD endpoint</td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top">`/sldemo.com_kitchen-billboard/`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top">Placement: prefix `sl`, location code `demo.com_kitchen`, format code `billboard`</td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top">`/dtdesktop/`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top">Target section: prefix `dt` with value `desktop`</td></tr></tbody></table>

</div>## Response

A successful request returns the ads in the requested markup (VAST XML for video/audio setups).  
This markup is determined by the advar template used to create the banner that is returned by the request.

<p class="callout success">If no ads are available, the response contains **no ads**. This is still a successful `200` response, **not** an error.</p>

### Response codes

<div class="overflow-x-auto w-full px-2 mb-6" data-sourcepos="44:1-48:113;2081-2521" id="bkmrk-code-name-descriptio"><table class="min-w-full border-collapse text-sm leading-[1.7] whitespace-normal" style="width: 100%;"><thead class="text-left"><tr><th class="text-text-100 border-b-0.5 border-[hsl(var(--border-300)/0.6)] py-2 pr-4 align-top font-bold" scope="col" style="width: 6.67334%;">Code</th><th class="text-text-100 border-b-0.5 border-[hsl(var(--border-300)/0.6)] py-2 pr-4 align-top font-bold" scope="col" style="width: 12.7546%;">Name</th><th class="text-text-100 border-b-0.5 border-[hsl(var(--border-300)/0.6)] py-2 pr-4 align-top font-bold" scope="col" style="width: 80.5721%;">Description</th></tr></thead><tbody><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 6.67334%;">`200`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 12.7546%;">OK</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 80.5721%;">The body contains the ads. If no ads are available, the response contains no ads — an empty response is a successful result, not an error.</td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 6.67334%;">`454`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 12.7546%;">No slots</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 80.5721%;">The request contains no slots. The `x-adhese-bad-request` header contains `slots cannot be empty`.</td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 6.67334%;">`500`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 12.7546%;">Internal server error</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 80.5721%;">For a debug request, check the debug log. Otherwise, contact Adhese Support.</td></tr></tbody></table>

</div>### Error handling

When handling errors programmatically, read the **`x-adhese-bad-request`** response header for the specific error message.