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

# Publisher list management

> Declare the publisher domains your storefront covers so buyers can evaluate reach before purchasing.

## Overview

Every storefront can declare the publisher domains it represents. Buyers use this to answer "which publishers does this seller represent?" before committing. This is publisher **coverage**, not delivery: a verified domain means the publisher has authorized this seller, not a guarantee of what actually delivers on a given buy. For product-level availability, use product discovery.

Declared domains are resolved against each publisher's `adagents.json` file automatically. The result -- **verified** or **declared** -- is visible to buyers on storefront detail and on the publisher list sub-endpoint.

## Seller: managing your publisher list

### Add a single domain

```http theme={null}
POST /api/v2/storefront/publishers
{ "domain": "bbc.com" }
```

Accepted input formats:

* Bare domain: `bbc.com`
* Full URL: `https://www.bbc.com/news` (normalized to `bbc.com` automatically)

Returns the full updated publisher list (201 on success).

### Replace the full list atomically

```http theme={null}
PUT /api/v2/storefront/publishers
{ "publishers": ["bbc.com", "nytimes.com", "theguardian.com"] }
```

Replaces every previously declared domain in one transaction. Up to 5,000 domains per call. Any invalid domain (one that can't be normalized to an apex domain) fails the whole request -- the list is not partially updated.

### Remove a domain

```http theme={null}
DELETE /api/v2/storefront/publishers/bbc.com
```

Returns 204 (idempotent). Returns 409 if the domain was not seller-declared -- crawled and discovered rows can only be removed by the platform.

### List your publishers

```http theme={null}
GET /api/v2/storefront/publishers
```

Returns all publisher rows associated with the storefront, regardless of provenance:

```json theme={null}
{
  "publishers": [
    {
      "domain": "bbc.com",
      "provenance": "declared",
      "adagentsStatus": "resolved",
      "authorizationStatus": "authorized",
      "propertyCount": 12,
      "lastSyncedAt": "2026-07-10T00:00:00Z"
    }
  ],
  "total": 1,
  "verified": 1
}
```

## Field reference

### `provenance`

| Value        | Meaning                                                                         |
| ------------ | ------------------------------------------------------------------------------- |
| `declared`   | Seller explicitly added this domain via the API.                                |
| `crawled`    | Platform discovered it via adagents.json crawl of a connected inventory source. |
| `discovered` | Surfaced through a buyer brief match.                                           |

### `authorizationStatus`

| Value          | Meaning                                                                                               |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| `authorized`   | The publisher's `adagents.json` explicitly authorizes this seller.                                    |
| `unauthorized` | The publisher's `adagents.json` explicitly denies this seller. Hidden from buyers.                    |
| `unknown`      | Not yet resolved -- either `adagentsStatus` is `pending` or the file has no `authorized_agents` list. |

### `adagentsStatus`

| Value         | Meaning                                                              |
| ------------- | -------------------------------------------------------------------- |
| `resolved`    | The publisher's `adagents.json` was fetched and parsed successfully. |
| `no_adagents` | No `adagents.json` file exists at the expected location.             |
| `error`       | File exists but could not be fetched or parsed.                      |
| `pending`     | Resolution not yet attempted.                                        |

## Buyer: viewing publisher coverage

### Storefront detail

`GET /api/v2/buyer/storefronts/{storefrontId}` returns a `publishers` summary:

```json theme={null}
{
  "publishers": {
    "total": 42,
    "verified": 38,
    "sample": ["bbc.com", "nytimes.com", "theguardian.com"]
  }
}
```

`null` when the storefront has no declared publishers yet.

### Full paginated list

```http theme={null}
GET /api/v2/buyer/storefronts/{storefrontId}/publishers?limit=20&offset=0&q=bbc&verification=verified
```

Query parameters (all optional):

* `q` -- prefix match on domain name
* `verification` -- `verified` or `declared`
* `limit` -- page size, 1-100 (default 20)
* `offset` -- pagination offset

### Filter storefronts by publisher domain

```http theme={null}
GET /api/v2/buyer/storefronts?publisherDomain=bbc.com
```

Returns all storefronts that cover `bbc.com` or any of its subdomains.

## Readiness

The `declare-publishers` readiness check (non-blocking) appears on `GET /storefront/readiness` when no declared publishers exist yet. It is informational -- a storefront without declared publishers can still go live. Declaring at least one publisher clears the check.