# Advalidation API

> Advalidation is an automated ad creative validation platform. Users upload ad creatives (display banners, video files, VAST tags) and each creative is evaluated through automated tests that return structured results such as file weight, dimensions, duration, click-through verification, and SSL compliance. The Advalidation API lets you run this workflow programmatically.

All requests use the base URL `https://app.advalidation.io/v2` and require the `X-API-Key` header.

## Docs

- [Getting started](https://advalidation.com/docs/getting-started/): Core API walkthrough - verify key, create campaign, upload creative, poll for results, retrieve scan data
- [Data model](https://advalidation.com/docs/data-model/): Creative structures, hierarchy navigation, and scan types for display and video
- [Creative files upload guide](https://advalidation.com/docs/file-upload/): Four upload methods (JSON, base64, plain text, binary) with examples
- [Retrieving results for a VAST tag](https://advalidation.com/docs/vast-case-study/): Step-by-step guide for VAST creatives with variations and media files
- [The test array](https://advalidation.com/docs/test-array/): Reference for all display and video tests returned in scan results
- [Conventions](https://advalidation.com/docs/conventions/): Response format, error handling, content types
- [Rate limiting](https://advalidation.com/docs/rate-limiting/): IP-based rate limits, response headers, handling 429s
- [API Reference](https://advalidation.com/docs/api/): Full OpenAPI reference for all endpoints
- [OpenAPI Spec](https://advalidation.com/openapi.json): Full machine-readable API specification

## Key concepts

### Authentication

All requests require the `X-API-Key` header with your API key.

### Response format

Successful responses include a `data` property. Single-resource endpoints return the object directly. Collection endpoints return an array and may include `meta` with pagination.

### Core workflow

1. Create a campaign (`POST /campaigns`) with `type` set to `display` or `video`
2. Upload a creative (`POST /campaigns/{campaignId}/creatives`):
   ```
   POST /v2/campaigns/{campaignId}/creatives
   Content-Type: application/json
   X-API-Key: your-api-key

   {"payload": "<iframe src=\"https://example.com/ad.html\" width=\"300\" height=\"250\"></iframe>"}
   ```
   The `payload` field accepts an HTML tag, URL, VAST URL, or base64-encoded file.
3. Poll the creative (`GET /creatives/{creativeId}`) until `processingStatus` is `finished`
4. Retrieve scan results (`GET /scans/{scanId}`)

### Data model

`/scans/{scanId}` is the only endpoint that returns test results. Everything else is about discovering scan IDs.

**Display creatives** are always flat: one creative, one scan.

**Hosted video creatives** are also flat: one creative, one scan.

**VAST without variations**: The creative holds the VAST XML scan. Media files each have their own video scan. Fetch media files from `/creatives/{id}/media-files`.

**VAST with variations**: Detected by `nbVariations` being present on the creative. The top-level scan has `nbIssues` but no `tests` array. Use `/creatives/{id}/variations` to list variations, then `/creatives/{id}/variations/{variationCreativeId}` to get both the variation XML scan and all child video scans.

### Navigating the hierarchy

Starting from `/campaigns/{campaignId}/creatives`:

```
For each creative:

  Has nbVariations?
    YES -> VAST with variations
      1. /scans/{latestScanStatus.id}            -> top-level nbIssues (no tests array)
      2. /creatives/{id}/variations               -> list variations
      3. /creatives/{id}/variations/{varId}        -> variation + media files
      4. /scans/{id} for each item                -> XML or video tests

    NO -> fetch /creatives/{id}/media-files
      Has results -> VAST without variations
        1. /scans/{latestScanStatus.id}           -> VAST XML tests
        2. /scans/{id} for each media file        -> video tests

      Empty -> flat creative (display or hosted video)
        1. /scans/{latestScanStatus.id}           -> all tests in one response
```

### Test results

Each test returns `name`, `value`, `result` (`pass`, `fail`, or `warn`), and `attributes`.

---

For complete documentation in a single file, see [llms-full.txt](https://advalidation.com/llms-full.txt).