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

# Browse what an ad-server source offers

> Read an ad-server source's capabilities, creative formats and publisher properties with get, and browse its ad units, placements and segments with search, before you author a product.

Before you author a [wholesale product](https://docs.apostra.com/v3/seller-product-creation.md) on an ad-server
source, you need to know what the source supports, which creative formats and
publisher properties it can carry, and which ad units, placements or segments you
can sell. V3 reads each of these without a tool of its own: three `include` values
on `get` for the small facts of one source, and one `search` kind for the long,
paged list of selectors.

Every read on this page needs a source with a managed ad-server connection, such
as Google Ad Manager or FreeWheel. Pass the source's own `sourceId`, as
`search({ "kind": "inventory_source" })` returns it. You never pass an ad-server
connection id.

A read changes nothing. Browsing a selector does not create, import or reserve
anything: it gives you the values a product's `inventory` is written from.

## Read the source's capabilities, formats and properties

Call `get` with `kind: "inventory_source"`, the source's `id` and any of
`capabilities`, `creativeFormats` and `publisherProperties`:

```json theme={null}
{
  "kind": "inventory_source",
  "id": "SOURCE_ID",
  "include": ["capabilities", "creativeFormats", "publisherProperties"]
}
```

A `get` that names none of the three returns what it returned before.

If the source has no managed ad-server connection, or the connection cannot answer,
that include is left out of the result and listed in `unavailableIncludes` with
its reason. The other includes you asked for are still returned. A source that is
not yours is not found, as for any `get`.

### `capabilities`

What the ad-server adapter declares. These are the adapter's own facts, not AdCP's,
so the names are the adapter's, in camelCase.

| Field | Meaning |
| - | - |
| `adapter` | The adapter's name, such as `google_ad_manager`. Absent when the connection states none. |
| `selectorTypes` | The kinds of selector you can browse and sell. Each has a `selectorType` (what you pass to `search` as `filter.selectorType`), a `label` and `supportsParentFilter`, which says whether you can list the children of one selector. |
| `selectionRequirements` | Rules a product must meet. Each names the `selectorTypes` it covers, `minSelected` and a `message`. Absent when the adapter states none, and `[]` only when it states an empty list. |
| `pricingModels` | The pricing models the ad server supports. |
| `targetingDimensions` | The targeting dimensions it supports. |
| `optimizationGoals` | The optimization goals it supports. |
| `overlaySupportCeiling` | The most a product on this source may declare in its own `overlay_support`, in AdCP's `TargetingOverlaySupport` shape. Absent when the adapter states no overlay dimensions, and `{}` only when it states an empty list. |
| `settlementCurrency` | The currency the ad server settles prices in, or `null` when none is known. Price a product in this currency. |

**What "not stated" looks like.** `adapter`, `selectionRequirements` and
`overlaySupportCeiling` are absent when the adapter did not state them, so you can tell
"not stated" from "stated as empty". The difference matters: a FreeWheel product needs at
least one package, and that rule applies whenever the adapter states no selection
requirements of its own, while a stated `[]` means the adapter really has none.
`selectorTypes`, `pricingModels`, `targetingDimensions` and `optimizationGoals` are empty
when the adapter does not state them, because nothing depends on the difference.

If the adapter states a list of selection requirements and any entry in it cannot be read,
Apostra does not serve a partial list or `[]`. It leaves `capabilities` out of the result
and lists it in `unavailableIncludes` with that reason. Treat the requirements as unknown
until they can be read.

`overlaySupportCeiling` uses AdCP's own names and values, in snake\_case. A dimension the
adapter applies is `true`. `geo_metros` and `geo_metros_exclude` carry
`{ "systems": [...] }` with the adapter's AdCP metro systems, such as `nielsen_dma`, and
`geo_postal_areas` and `geo_postal_areas_exclude` carry AdCP's country-keyed postal map,
such as `{ "US": ["zip"] }`. A metro or postal dimension whose systems the adapter does not
state is left out, because `true` would promise every system. The place dimensions
(`geo_places` and `geo_places_exclude`) are never carried: AdCP's place declaration needs
catalog versions that no adapter states. Send `overlay_support` on
`save_wholesale_product` only within this ceiling.

### `creativeFormats`

The creative formats the source can carry, as AdCP format declarations. A format is
named by `format_kind` and `params`, and has no agent URL. The source's older format
list, which names formats by agent URL and id, is not served.

| Field | Meaning |
| - | - |
| `format_option_id` | The option's id. |
| `format_kind` | An AdCP canonical format kind, such as `image` or `video_hosted`. |
| `params` | The kind's parameters, such as `width` and `height`. |
| `display_name` | The format's name. |
| `publisher_domain` | Present only when the source states one. An ad server's own formats are product-local, and AdCP says a product-local option leaves `publisher_domain` out. Today no ad-server adapter states one. |
| `dimensions`, `assetTypes`, `requirements` | The adapter's own facts about the format. They are read-only. |
| `requirementsOmitted` | Present, and `true`, only when the adapter's `requirements` for this option name a legacy agent URL or format id. The option is served without `requirements` and keeps its canonical identity (`format_option_id`, `format_kind`, `params`, `display_name`), so you can still use it in a product. |

To use a format in a product, send its `format_option_id`, `format_kind` and
`params` back in `formatOptions` on `save_wholesale_product`, unchanged. Do not send
`display_name`, `dimensions`, `assetTypes` or `requirements`: a save does not take
them.

An option whose `params` name a legacy agent URL or format id is not served, because that
is the older identity this read does not carry. An option whose `requirements` name one is
served without `requirements` and with `requirementsOmitted: true`: its canonical identity
carries no agent URL, so nothing this read returns names one.

### `publisherProperties`

The properties the source can sell, and the selectors the ad server has already
decided are valid. The result has two lists, `properties` and `selectors`.

A property uses AdCP's `Property` names: `publisher_domain`, `property_id`,
`identifiers` (a list of `type` and `value`) and `tags`. AdCP also requires
`property_type` and `name`. The ad server does not always state them, so a property
carries only what the source stated. The ad server's display text for a property is
`label`, kept beside the AdCP fields and read-only. It is not AdCP's `name`.

A selector uses AdCP's `PublisherPropertySelector`: `selection_type` (`all`,
`by_id` or `by_tag`), `publisher_domain`, `property_ids` and `property_tags`. It is
the shape `inventory.publisher_properties` takes on `save_wholesale_product`, so
send one back unchanged. Its `label` is the ad server's own text and is read-only.

Apostra returns these as stored and does not check them against the AdCP schema
when you read them. The check happens when you save a product.

## Browse the source's selectors

Selectors are the ad units, placements, segments and other items the ad server
declares. A list can run to thousands, so it is a search, not an include:

```json theme={null}
{
  "kind": "inventory_source_item",
  "sourceId": "SOURCE_ID",
  "filter": { "selectorType": "ad_unit", "parentId": "PARENT_ID" },
  "query": "homepage"
}
```

* `sourceId` and `filter.selectorType` are required. A search without either is
  refused. Take `selectorType` from the `selectorTypes` that `capabilities` lists.
* `query` narrows the list by name. `filter.parentId` lists the children of one
  selector.
* `filter.mediaType` is `display` or `video`, and `filter.environmentType` is
  `BROWSER` or `VIDEO_PLAYER`. Both are optional. Any other value is refused with
  `VALIDATION_ERROR`.
* `include: ["adServerMetadata"]` is for the Apostra app and gives an agent nothing to
  read. See [Details for the Apostra app](https://docs.apostra.com/v3/seller-browse-ad-server-source.md#details-for-the-apostra-app).
* `limit` is at most 100. When more rows match, the answer has `nextCursor`. Send it
  back as `cursor` with the same `sourceId` and filters. If the ad server's cursor is
  longer than 2048 characters, it is not returned: the answer has
  `nextCursorTooLong: true` and `truncated: true` instead. Narrow the search with
  `query`, `filter.parentId`, `filter.mediaType` or `filter.environmentType`.
* The kind is explicit-only. A search with no `kind` never reads selectors, and
  `get` does not read a selector.

Each row has the ad server's own facts:

| Field | Meaning |
| - | - |
| `selectorType` | Which selector type the row is. |
| `externalId` | The ad server's id. Use it as `external_id` in `inventory.execution.selectors`. |
| `name`, `path`, `parentId`, `status` | The ad server's name, its path of ancestor names, its parent's `externalId` and its status. Each is `null` when the ad server sends none. |
| `hasChildren` | Whether the ad server says the row has children, as a boolean. Present only when the ad server states one, on the row or in the row's own `metadata`. A value that is not a boolean counts as not stated, and the field is absent. The text line for a row with `hasChildren: true` says it has children. |
| `truncated` | Present, and `true`, only when a value on the row was cut. The ad server controls these strings, so each one (`selectorType`, `externalId`, `name`, `parentId`, `status` and each `path` entry) is cut at 512 characters and ends with "…", and `path` keeps at most 32 entries. A cut `externalId` cannot be sent back in a product. A row with no cut value has no `truncated` field. |

A row with no `name` is kept: `name` is `null`, and the text line shows the `externalId` in
its place. No row is dropped for lacking a name.

The page has one more field, `adServerCount`: the ad server's own `count` for the search.
It is present only when the ad server states a non-negative integer. It is the ad server's
number as stated, and it is not always an exact total across pages, because some ad servers
fill it with the size of the page they just returned. Use `nextCursor`, not `adServerCount`,
to know whether more rows exist.

### Ad units with children

A Google Ad Manager ad unit reads its descendants from `include_descendants` in the
selector's `options`. When you save a product with `save_wholesale_product` and a Google Ad
Manager `ad_unit` selector does not state `include_descendants`, Apostra reads that ad
unit's `hasChildren` from the ad server and sets `include_descendants: true` if it says the
ad unit has children. Otherwise the option is left as you sent it.

* A value you send, `true` or `false`, is kept as sent.
* The rule applies only to `ad_unit` selectors of a product whose `inventory.execution.adapter`
  is `google_ad_manager`. Placements, other selector types and other adapters are never
  changed, and nothing is read for them.
* If Apostra cannot tell (the ad server does not answer, the selector is not found, or the
  ad server states no `hasChildren`), the option is left unset.
* A dry run (`dryRun: true`) shows what a save would add in `selectorOptionsAdded`.
* Products you saved earlier are not changed. The rule applies when a save sends the
  selector.

### Details for the Apostra app

`include: ["adServerMetadata"]` asks for the ad server's own details for each row: ad sizes,
ad unit ids, property, placement and mapping suggestions. The Apostra app's Components and
Inventory Selector widgets read them. They are served only in the result's `_meta`, under
`adServerMetadata`, and never in `structuredContent` or in the text, so an agent that asks
gets nothing it can read. A search that does not ask carries none. The value is valid only
for `kind: "inventory_source_item"`.

The entry is `{ rows, adServerMetadataTruncated? }`. `rows` maps a row's `selectorType` and
`externalId`, joined by a colon, to an object with these keys, each present only when the ad
server sent it:

| Key | Contents |
| - | - |
| `sizes` | The row's ad sizes, each `{ width, height }` with positive integers. A size the ad server gives only as a name is left out. |
| `adUnitIds` | The ad unit ids a placement covers. |
| `property` | `{ id, domain }`. |
| `placement` | `{ id, subCount }`. |
| `mapping` | `{ status, confidence, candidateIds }`. `status` is one of `suggested`, `accepted`, `manual`, `ambiguous`, `unmapped` or `ignored`. |

Only numbers, those status words and short plain tokens are served, never free text. A token
is an id or a domain made of letters, digits and `.`, `_`, `:` or `-`: at most 64 characters
for an id and 253 for a domain. A value that is not a token is left out and never cut,
because a cut id is a different id. Names, paths, labels and the evidence text behind a
mapping suggestion are not served.

The entry is bounded. A row keeps at most 32 sizes, 64 ad unit ids and 16 candidate ids, and
its object is kept to 1,024 characters of JSON by dropping keys from the end of the order
above. Anything left out sets `truncated: true` inside that row's object, which means the
object is partial. This is not the row's own `truncated`. The whole entry is kept to 32,768
characters: a row past that has no entry in `rows`, and the entry says
`adServerMetadataTruncated: true`.

## Related

* [Create and manage seller products](https://docs.apostra.com/v3/seller-product-creation.md) uses these values in
  `save_wholesale_product`.
* [Sellers on the V3 tool surface](https://docs.apostra.com/v3/tool-reference.md) lists every `get` kind and include a seller
  account reads.


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