> ## 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.

# Adopt a managed audio source

> Production-dark contract for adopting one promoted managed audio source

`POST /api/v2/buyer/creatives/adopt-managed-audio-source`

This page defines a capability-gated contract. It is available only when both
the account's managed-audio capability and its bounded delivery origin are
explicitly enabled; this change enables neither. When both gates are enabled,
the operation creates, or idempotently returns, one `audio_hosted` creative
manifest from a promoted managed audio source. The caller supplies an opaque
source identity, never an object-storage URL. Interchange issues the manifest's
bounded HTTPS asset URL server-side only after it confirms the exact source
belongs to the authenticated buyer, advertiser, and storefront connection.

<Warning>
  This operation is capability-gated: it is available only when both the account
  capability and bounded origin are explicitly enabled, and this change enables
  neither. Even when enabled, supplying `campaign_id` records the manifest's
  campaign association only. It never starts seller or destination delivery,
  creates delivery state, attaches to a media buy, or makes anything live.
</Warning>

## Request shape when both gates are enabled

```bash theme={null}
curl -X POST https://api.interchange.io/api/v2/buyer/creatives/adopt-managed-audio-source \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_uid": "0f8b7a2e-6cf4-4db4-9a7f-09db4430ae91",
    "advertiser_id": "900",
    "storefront_id": "7",
    "name": "Loetje audio cut",
    "campaign_id": "cmp_123"
  }'
```

| Field           | Type   | Required | Notes                                                                |
| --------------- | ------ | -------- | -------------------------------------------------------------------- |
| `source_uid`    | UUID   | Yes      | A managed audio source that completed inspection and is `promoted`   |
| `advertiser_id` | string | Yes      | Must match the source and, when supplied, the campaign               |
| `storefront_id` | string | Yes      | The authenticated connection that owns the source                    |
| `name`          | string | Yes      | Advertiser-scoped creative name (1–255 characters)                   |
| `campaign_id`   | string | No       | Records an idempotent campaign association; no delivery is initiated |

## Response when both gates are enabled

An enabled request returns `201` with the manifest identity, opaque source and
publication identities, and bounded hosted-audio URL:

```json theme={null}
{
  "creative_id": "cm_abcdef",
  "source_uid": "0f8b7a2e-6cf4-4db4-9a7f-09db4430ae91",
  "publication_uid": "2e5c0f2e-cf68-44ed-a032-91c0ac9e4bfe",
  "delivery_url": "https://delivery.example.com/delivery/v1/audio/2e5c0f2e-cf68-44ed-a032-91c0ac9e4bfe",
  "name": "Loetje audio cut",
  "campaign_id": "cmp_123",
  "created": true
}
```

`created` is `false` on a replay that finds the already-adopted source. Reusing
the same `source_uid` and `name` is safe; if `campaign_id` is included, the
call also retries the campaign association. A different name is refused rather
than silently renaming the existing creative.

The hosted URL is a revocable, time-bounded publication, not a private GCS URL.
It is never a caller-supplied value, and the response never exposes the private
object-storage URL or location.

## Errors

* `404 NOT_FOUND` — the source is missing or is not owned by the authenticated
  buyer/advertiser/storefront triple. Those cases are intentionally
  indistinguishable.
* `409 CONFLICT` — the source/name identity is already held, an earlier
  adoption is still resolving, the adopted asset is no longer available, or
  the source's delivery was revoked. Read `details.reason`; only the two
  `*_in_progress` reasons are automatically retryable.
* `422 CAPABILITY_NOT_SUPPORTED` — the bounded delivery origin is disabled or
  empty, or the requesting account's managed-audio capability is not enabled.
  A source that is not a promoted, unexpired audio source or a campaign from
  another advertiser is also refused with a `422` validation error.
* `503 SERVICE_UNAVAILABLE` — the bounded delivery origin is non-empty but
  invalid or otherwise misconfigured, so no bounded URL can be issued.

Revocation, retention expiry, and deletion requests fail closed. Upload a new
source rather than attempting to refresh or reattach a source whose publication
is no longer active.

## Related

<CardGroup cols={2}>
  <Card title="Bring your own creative" href="/v2/buyer/creatives/bring-your-own-creative" icon="upload">
    Managed-media adoption and its delivery boundary
  </Card>

  <Card title="Creative overview" href="/v2/object-guides/creative" icon="image">
    Manifest identity and creative transport
  </Card>
</CardGroup>