> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ad Unit API

> Learn how to create, read, update, and delete ad units from your server with an API key.

The Ad Unit API lets you create and manage ad units from your server. Units you create with the API appear in the console right away. You use unit IDs for SDK integration and in the creative sets of the [Ad Product API](https://docs.adrop.io/integrations/ad-products.md).

The API works on the same data as ad units in the console. You can also read and update units created in the console.

***

## Prerequisites

* You need an API key with the `ad-unit:read` and `ad-unit:write` scopes. You can't select these scopes in **\[Settings]** > **\[Integrations]** in the console. Ask Adrop, and we'll issue you a key with the scopes. You can get the [App API](https://docs.adrop.io/integrations/apps.md) and [Ad Product API](https://docs.adrop.io/integrations/ad-products.md) scopes on the same key.
* The two scopes are checked separately. A key with only `ad-unit:write` gets `403` on read (`GET`) requests. Create and update responses include the full unit, but you also need `ad-unit:read` to read units separately.
* Look up the ID of the app to create units in with the [App API](https://docs.adrop.io/integrations/apps.md).

> [!WARNING]
>
> Call the API from your server only. Don't put API keys in apps or web pages.

***

## Basics

| Item | Value |
| - | - |
| Base URL | `https://lake.adrop.io` |
| Authentication | Put the API key in the `x-api-key` header. You can only work with units in the key's project. Unit IDs from other projects return `404`. |
| Content-Type | Create and update request bodies must be JSON (`application/json`). Other types return `415`. |
| Maximum request body size | 100 KB. Larger bodies return `413`. A read (`GET`) request with a body returns `413` regardless of its size. |
| ID format | A string of up to 64 letters, digits, `_`, and `-`. New units get a 26-character ULID. Older units may have IDs that aren't ULIDs. |
| Timestamps | `createdAt` and `updatedAt` are epoch milliseconds. |
| Concurrent requests | Up to 4 per project at a time, counted across all keys of the same project and separately from the Ad Product API. More return `429`. |

When you get `429`, wait for the number of seconds in the `Retry-After` header, then send the request again. When the server is busy, you can get `429` even if you send requests one at a time.

***

## Endpoints

Paths are relative to the Base URL.

| Method | Path | Scope | Description |
| - | - | - | - |
| `POST` | `/ad-units` | `ad-unit:write` | [Create a unit](#create-a-unit) |
| `GET` | `/ad-units` | `ad-unit:read` | [List units](#list-units) |
| `GET` | `/ad-units/{unitId}` | `ad-unit:read` | [Get a unit](#get-a-unit) |
| `PATCH` | `/ad-units/{unitId}` | `ad-unit:write` | [Update a unit](#update-a-unit) |
| `DELETE` | `/ad-units/{unitId}` | `ad-unit:write` | [Delete a unit](#delete-a-unit) |

***

## Create a Unit

Creates an ad unit.

### Request

```http theme={null}
POST /ad-units
```

Requires the `ad-unit:write` scope.

### Request Body

| Field | Type | Required | Description |
| - | - | :-: | - |
| `app` | string | Yes | ID of the app to create the unit in. Must be an app in this project. |
| `title` | string | Yes | Unit name (up to 200 characters). An empty string isn't accepted. |
| `format` | string | Yes | Format. See [Formats and Sizes](#formats-and-sizes). |
| `desc` | string \| null | - | Description (up to 1,000 characters) |
| `size` | object \| null | - | Creative size, `{ "w": width, "h": height }`. If omitted, the format's default size is used. `null` means a native unit with no image or video. |
| `video` | object \| null | - | Aspect ratio of a video size: `{ "dimensions": "16:9" }` or `"9:16"`. Send it only when you use a video size. |
| `useTemplate` | boolean | - | Template only (console label). You can turn it on only for banners that use a preset size and have no video. |
| `useWatermark` | boolean | - | Show AD Mark (console label). You can turn it on only for native units. |
| `features` | object | - | Format settings. See [Format Settings](#format-settings). |

* Omitted values are filled with the same per-format defaults as the unit creation screen in the console.
* If you turn on a setting and don't send the values that go with it, they get the same defaults as in the console. For example, if you turn on `carouselActivated`, `carouselShowIndicator` and `carouselRollingInterval` are filled with their defaults.
* You can create only banner and native units in web apps.
* Response-only fields (`_id`, `connected`, `archived`, `createdAt`, `updatedAt`) and fields not listed here return `400 VALIDATION_FAILED`.

### Request Example

```bash theme={null}
curl -X POST https://lake.adrop.io/ad-units \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
    "title": "Home Banner",
    "format": "banner",
    "size": { "w": 320, "h": 50 },
    "features": { "carouselActivated": true }
  }'
```

### Response Example

Returns `201` with the new unit as a [unit object](#unit-object).

```json theme={null}
{
  "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K",
  "app": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
  "title": "Home Banner",
  "format": "banner",
  "size": { "w": 320, "h": 50 },
  "useTemplate": false,
  "useWatermark": false,
  "video": null,
  "features": {
    "bgColorLight": "#FFFFFF",
    "carouselActivated": true,
    "carouselShowIndicator": true,
    "carouselRollingInterval": 3000,
    "canSupportThemeDark": false,
    "videoSupported": false,
    "videoController": false,
    "videoSkipDelayMs": 0,
    "nativeSlots": []
  },
  "connected": false,
  "archived": false,
  "createdAt": 1790820300000,
  "updatedAt": 1790820300000
}
```

> [!NOTE]
>
> Create requests aren't idempotent. If you resend a request because you didn't get a response, the unit can be created twice. Before resending, check the [unit list](#list-units) to see whether the unit was created.

### Errors

* `400 AD_UNIT_VALIDATION_FAILED`: The request breaks a unit rule, such as the size, the range of a format setting, or a condition between settings.
* `400 AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE`: `nativeSlots` doesn't follow the rules.
* `404 PROJECT_APP_NOT_FOUND`: `app` isn't an app in this project.

***

## Unit Object

The get, create, and update endpoints return units in this format.

| Field | Type | Description |
| - | - | - |
| `_id` | string | Unit ID. Used to request ads in the SDK. |
| `app` | string | ID of the app the unit belongs to |
| `title` | string | Unit name |
| `desc` | string \| null | Description. Omitted or `null` when there's no value. |
| `format` | string | Format. Older units with a format that's no longer used don't have this field. |
| `size` | object \| null | Creative size, `{ "w", "h" }`. `null` for native units with no image or video and for some older rewarded units. |
| `useTemplate` | boolean | Whether Template only is on |
| `useWatermark` | boolean | Whether the AD mark is shown |
| `video` | object \| null | Aspect ratio of a video size, `{ "dimensions" }`. `null` if the size isn't a video size or for some older rewarded units. |
| `features` | object | Format settings. Includes only the stored settings that the unit's format uses. |
| `connected` | boolean | Whether the unit has ever received ad requests from the SDK |
| `archived` | boolean | Whether the unit has been deleted |
| `createdAt` | number | When the unit was created |
| `updatedAt` | number | When the unit was last updated |

Settings that aren't stored aren't filled with defaults in `features`.

***

## Formats and Sizes

Set `format` to one of these values exactly, including case.

| `format` | Console | Size presets (width x height) | Default size |
| - | - | - | - |
| `banner` | Banner | 320x50, 320x100, 300x250, 728x90, 300x600, 320x180 (16:9 video), 180x320 (9:16 video) | 300x250 |
| `native` | Native | 360x360, 600x314, 1200x628, 320x180 (16:9 video), 180x320 (9:16 video), No Image/Video (`null`) | 600x314 |
| `popupBottom` | Bottom popup | 360x240, 360x450, 320x180 (16:9 video), 180x320 (9:16 video) | 360x240 |
| `popupCenter` | Center popup | 360x360, 320x180 (16:9 video), 180x320 (9:16 video) | 360x360 |
| `interstitial` | Interstitial | 320x480, 360x360 | 360x360 |
| `rewarded` | Rewarded | 180x320 (9:16 video) | 180x320 |
| `splash` | Splash | 360x270 | 360x270 |

* Banners, native units, and popups can also use a custom size instead of a preset. Width and height are each an integer from 1 to 10,000, and popups must have a width-to-height ratio from 2:3 to 3:2.
* If you use a video size (320x180 or 180x320), set `video.dimensions` to the matching ratio (`16:9` or `9:16`).
* Rewarded unit creatives are always 9:16 videos.

For what each format offers, see [Ad Unit Formats](https://docs.adrop.io/ad-unit/formats.md).

***

## Format Settings

`features` can include only the settings the format uses. Settings for other formats return `400`. Send numbers as JSON numbers (strings such as `"1000"` aren't accepted). Time values are in milliseconds.

### All Formats

| Setting | Type | Console | Description |
| - | - | - | - |
| `canSupportThemeDark` | boolean | Accept Dark Mode Creative | Whether to accept creatives for dark mode. See [Supporting Dark Mode](https://docs.adrop.io/ad-unit/dark-mode.md). |
| `videoSupported` | boolean | Accept Video Creatives | You can turn it on for banners, native units, and popups. |
| `videoController` | boolean | Video Controller | You can turn it on only when `videoSupported` is on. |
| `videoSkipDelayMs` | number | Video Skip Delay | 0–30,000. Values other than 0 are allowed only when `videoController` is on. |
| `nativeSlots` | array | Media setup | Media list of a native unit. See [Native Texts and Media](#native-texts-and-media) below. |

Video settings (`videoSupported`, `videoController`, and `videoSkipDelayMs`) are always off for interstitial, rewarded, and splash units.

### Banner

| Setting | Type | Console | Description |
| - | - | - | - |
| `bgColorLight` | string | Background color | For example, `"#FFFFFF"` (up to 32 characters). You can set it only for banners that use a preset size and have no video. |
| `carouselActivated` | boolean | Enable Carousel | You can't turn it on together with Video creatives. |
| `carouselShowIndicator` | boolean | Show Indicator | |
| `carouselRollingInterval` | number | Rolling Interval | 1,000–60,000 |

### Native

| Setting | Type | Console | Description |
| - | - | - | - |
| `nativeShowCTA` | boolean | CTA Button | You can't turn it on for native units with no image or video. |
| `nativeShowAdvProfileLogo` | boolean | Advertiser Logo | |
| `nativeShowAdvProfileName` | boolean | Advertiser Name | |
| `nativeTexts` | array | Native text fields | Text items such as the ad headline and ad description. See [Native Texts and Media](#native-texts-and-media) below. |

### Popup (Bottom and Center)

| Setting | Type | Console | Description |
| - | - | - | - |
| `popupTemplate` | string | Button Template | `"performance"` (Performance Optimized) or `"hideForToday"` (Hide for Today) |
| `popupCloseButtonPosition` | number | Close Button Position | `0` inside bottom, `1` inside top, `2` outside top, `3` outside bottom. Bottom popups accept only `0`–`2`. |
| `popupUseDimTapToClose` | boolean | Tap Outside to Close | |
| `popupDimOpacity` | number | Background Opacity | One of `80`, `55`, and `30` |
| `popupUseHideUnitForToday` | boolean | Hide for Today Button | |
| `popupUseHideCampaignForToday` | boolean | Hide This Ad for Today | |
| `carouselCountLimit` | number \| null | Max Ad Count | 1–20. `null` turns off the count limit. |

### Interstitial

| Setting | Type | Console | Description |
| - | - | - | - |
| `interstitialCloseDelayTime` | number | Close button delay | 0–10,000 |

### Splash

| Setting | Type | Console | Description |
| - | - | - | - |
| `bgColorLight` | string | Background color | For example, `"#FFFFFF"` (up to 32 characters) |
| `splashCloseTime` | number | Splash display time | 500–3,000 |

Rewarded units use only the settings common to all formats.

### Setting Conditions

* Template only (`useTemplate`) is available only for banners that use a preset size and have no video.
* You can turn on `canSupportThemeDark` only for banners with Template only turned off, native units with an image or video, popups, and splash units.
* For native units with no image or video, you can't turn on **Show AD Mark** (`useWatermark`), **CTA Button**, or **Accept Video Creatives**.
* Ranges are checked only when the related setting is on. For example, `carouselRollingInterval` is checked when `carouselActivated` is on.

### Native Texts and Media

* Each `nativeTexts` item has `id` (lowercase letters, digits, and `_`), `label`, `maxLength` (maximum number of characters, greater than 0), and `optional` (whether the item is optional). You can add up to 50 items.
* `headline` (ad headline) and `body` (ad description) can only be in the first or second position of `nativeTexts`.
* Each `nativeSlots` item has `id`, `label` (optional), `w`, and `h`. You can use `nativeSlots` only for native units with an image or video. The first media item must have the `id` `m1` and the same size as the unit's `size`. You can add up to 3 items. If there's only one media item, it's stored as `[]`.
* IDs must be unique across `nativeTexts` and `nativeSlots` combined.

If `nativeSlots` breaks these rules, the API returns `400 AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE` with the reason in `detail.reason`. For multiple media items, see [Native Multi-Media](https://docs.adrop.io/ad-unit/native-multi-media.md).

***

## List Units

Returns the project's units, newest first, one page at a time. Deleted units are excluded by default.

### Request

```http theme={null}
GET /ad-units
```

Requires the `ad-unit:read` scope.

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | :-: | - | - |
| `limit` | number | - | `20` | Number of units per page (1–120) |
| `next` | string | - | - | Cursor for the next page. Pass the `next` value from the previous response as is. Omit it for the first page. |
| `format` | string | - | - | Returns only units of this format (for example, `splash`). If omitted, units of all formats are returned. |
| `includeArchived` | boolean | - | `false` | If `true`, deleted units are included. |

### Request Example

```bash theme={null}
curl "https://lake.adrop.io/ad-units?format=banner&limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response Example

Returns `200` with `items` (the units) and `next` (the cursor for the next page). If there's no `next`, this is the last page.

```json theme={null}
{
  "items": [
    {
      "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K",
      "app": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
      "title": "Home Banner",
      "format": "banner",
      "size": { "w": 320, "h": 50 },
      "useTemplate": false,
      "useWatermark": false,
      "video": null,
      "features": { "bgColorLight": "#FFFFFF", "carouselActivated": false, "videoSupported": false },
      "connected": true,
      "archived": false,
      "createdAt": 1790820300000,
      "updatedAt": 1790820300000
    }
  ],
  "next": "01JAZ3KA1B2C3D4E5F6G7H8J9K"
}
```

The order is mostly newest first, but older units may be out of order. Don't rely on the order. Use `next` to read the following pages.

***

## Get a Unit

Returns one unit. You can also get a deleted unit by ID. In that case, `archived` is `true`.

### Request

```http theme={null}
GET /ad-units/{unitId}
```

Requires the `ad-unit:read` scope.

### Request Example

```bash theme={null}
curl "https://lake.adrop.io/ad-units/01JAZ3KA1B2C3D4E5F6G7H8J9K" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response

Returns `200` with a [unit object](#unit-object).

### Errors

* `404 AD_UNIT_NOT_FOUND`: The unit doesn't exist or belongs to another project.

***

## Update a Unit

Changes only the fields you send.

### Request

```http theme={null}
PATCH /ad-units/{unitId}
```

Requires the `ad-unit:write` scope. The request body takes the same fields as when you [create a unit](#request-body), except `app`. You can't change a unit's app.

### Query Parameters

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `ifUpdatedAt` | number | - | The `updatedAt` of the unit you last read. If the unit changed since then, the API returns `409 AD_UNIT_CONFLICT` and changes nothing. |

### How Updates Work

* Fields you don't send stay as they are. An empty body `{}` changes nothing.
* In `features`, only the settings you send change. Other settings stay as they are. However, when you turn `carouselActivated`, `videoSupported`, or `videoController` on or off, dependent settings you don't send (`carouselShowIndicator`, `carouselRollingInterval`, `videoController`, `videoSkipDelayMs`) change to their defaults when turned on and to their off values when turned off.
* You can send `null` only for `desc` (clears the description), `size` (changes the unit to a native unit with no image or video), `video` (clears the video size), and `features.carouselCountLimit` (turns off the popup carousel count limit).
* When you change the format and the current size isn't a preset of the new format, you must also send `size`. Settings the new format doesn't use are removed, and the new format's settings are filled with defaults.
* You can't update deleted units (`409 AD_UNIT_ARCHIVED`).

### Locked Fields

For units that have received ad requests from the SDK (`connected: true`) and units in an ad product's creative set, you can't change `format`, `size`, `video`, or the `id` of `nativeSlots` items (`409 AD_UNIT_FIELD_LOCKED`). You can change the name, description, and other settings.

### Impact on Ad Products

If you change `useTemplate`, `useWatermark`, or `features` of a unit in an ad product, the unit may no longer match its creative set. The unit then gets the **Needs Modification** status (`fixRequired`) in that product, and ads aren't served to it. For details, see [Creative Sets in the Ad Product API](https://docs.adrop.io/integrations/ad-products.md#creative-sets).

If too many products use the unit to reconcile them all at once, the API returns `409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED` and changes nothing. `detail.limit` holds the name of the limit that was hit, and `detail.max` holds its value.

> [!TIP]
>
> If you take a get response, remove the response-only fields (`_id`, `app`, `connected`, `archived`, `createdAt`, `updatedAt`), and send the rest as is, nothing changes. Units created in the console long ago may store the numbers in `features` as strings (for example, `"1000"`). Convert them to numbers before you send them back.

### Request Example

```bash theme={null}
curl -X PATCH "https://lake.adrop.io/ad-units/01JAZ3KA1B2C3D4E5F6G7H8J9K?ifUpdatedAt=1790820300000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Home Banner (Main)",
    "features": { "carouselRollingInterval": 5000 }
  }'
```

### Response

Returns `200` with the updated [unit object](#unit-object).

### Errors

* `404 AD_UNIT_NOT_FOUND`: The unit doesn't exist or belongs to another project.
* `409 AD_UNIT_ARCHIVED`: The unit has been deleted.
* `409 AD_UNIT_CONFLICT`: `ifUpdatedAt` differs from the unit's `updatedAt`. Get the unit again, then update it.
* `409 AD_UNIT_FIELD_LOCKED`: You tried to change a locked field.
* `409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED`: Too many products use this unit.

***

## Delete a Unit

Deletes a unit. You can't restore a deleted unit.

### Request

```http theme={null}
DELETE /ad-units/{unitId}
```

Requires the `ad-unit:write` scope.

### Request Example

```bash theme={null}
curl -X DELETE "https://lake.adrop.io/ad-units/01JAZ3KA1B2C3D4E5F6G7H8J9K" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response Example

Returns `200` with the unit ID.

```json theme={null}
{ "_id": "01JAZ3KA1B2C3D4E5F6G7H8J9K" }
```

* Deleted units no longer appear in the list, but you can still get them by ID (`archived: true`). Deleting a unit that's already deleted also returns `200`.
* A deleted unit is removed from the creative sets of every ad product that uses it. Creative sets left empty are removed too, so a product can end up with no units.

> [!WARNING]
>
> Before you delete a unit, check with the [Ad Product API](https://docs.adrop.io/integrations/ad-products.md#get-a-product) whether any products use it. The product list doesn't include unit IDs, so get each product and check `unitGroups[].units`.

### Errors

* `404 AD_UNIT_NOT_FOUND`: The unit doesn't exist or belongs to another project.
* `409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED`: Too many products use this unit. Remove the unit from the products first.

***

## Error Handling

### Error Response

Error responses include `statusCode`. Errors whose `errorCode` in the table below isn't `-` also include `errorCode`. Errors that point to a problem in the request also include `detail`. Handle errors by `errorCode`, or by `statusCode` when there's no `errorCode`.

```json theme={null}
{
  "statusCode": 400,
  "errorCode": "AD_UNIT_VALIDATION_FAILED",
  "timestamp": "2026-11-05T19:58:22+09:00",
  "detail": {
    "errors": [
      {
        "path": "features.splashCloseTime",
        "constraint": "max",
        "message": "features.splashCloseTime must not be greater than 3000",
        "value": 5000
      }
    ]
  }
}
```

In `detail.errors[]`, `path` is the location of the invalid field, and `value` is the value you sent. `detail.errors` holds up to 100 errors. Request format errors (`VALIDATION_FAILED`) also include the `message` and `error` fields. Errors in `features` are combined into one line in `message`, so check `detail.errors[]` for the error on each setting.

### Error Codes

| Status | `errorCode` | Cause |
| - | - | - |
| `400` | `VALIDATION_FAILED` | The request format is invalid. You sent an unknown field or a response-only field, a value has the wrong type, format, or length, `format` isn't a format name, or the JSON is malformed. |
| `400` | `AD_UNIT_VALIDATION_FAILED` | A unit rule was broken. This covers sizes, video, the app platform, and the ranges and conditions of format settings. |
| `400` | `AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE` | `nativeSlots` doesn't follow the rules. `detail.reason` has the reason. |
| `401` | - | The API key is missing, invalid, or revoked. |
| `403` | - | The key doesn't have the required scope (`ad-unit:read` or `ad-unit:write`). |
| `404` | `AD_UNIT_NOT_FOUND` | The unit doesn't exist or belongs to another project. |
| `404` | `PROJECT_APP_NOT_FOUND` | The `app` you sent when creating a unit isn't an app in this project. |
| `408` | `REQUEST_BODY_TIMEOUT` | The request body wasn't fully sent within 30 seconds, or it was sent slower than 16 KB per second. |
| `409` | `AD_UNIT_FIELD_LOCKED` | You tried to change `format`, `size`, `video`, or the `id` of `nativeSlots` items on a unit that has received ad requests from the SDK or is in a product. |
| `409` | `AD_UNIT_CONFLICT` | `ifUpdatedAt` differs from the unit's `updatedAt`. |
| `409` | `AD_UNIT_ARCHIVED` | You tried to update a deleted unit. |
| `409` | `AD_UNIT_RECONCILE_LIMIT_EXCEEDED` | Too many products use this unit to process the request. |
| `413` | - | The request body is larger than 100 KB, or a read request has a body. |
| `415` | `UNSUPPORTED_MEDIA_TYPE` | The request body isn't JSON or uses an unsupported character encoding. Use UTF-8. |
| `429` | `TOO_MANY_CONCURRENT_REQUESTS` | The concurrent request limit was exceeded, or the server is busy. Wait for the number of seconds in the `Retry-After` header, then resend. |
| `502` | - | Internal server communication failed. |

### Retrying

* If a write request (`POST`, `PATCH`, or `DELETE`) gets `502` or the connection drops without a response, the request may have been applied. Get the unit to check before resending. Create requests aren't idempotent, so resending one as is can create a duplicate unit.
* When you resend an update with `ifUpdatedAt`, you can get `409 AD_UNIT_CONFLICT` if the earlier request was applied. Get the unit again to check.

***

## Limits

| Item | Limit |
| - | - |
| Unit name | 200 characters |
| Description | 1,000 characters |
| Custom size | 1–10,000 for each of width and height |
| `nativeTexts` | 50 (`id` up to 64 characters, `label` up to 500 characters) |
| `nativeSlots` | 3 (`id` up to 64 characters, `label` up to 500 characters) |
| `bgColorLight` | 32 characters |
| Request body | 100 KB |
| Concurrent requests | 4 per project |
| Request body upload | Within 30 seconds, at 16 KB per second or faster |
| Response download | If you don't receive the whole response within 30 seconds, the server closes the connection. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.