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

# Adopt a managed audio source

> Adopt one promoted managed audio source as an `audio_hosted` creative

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

This 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. Apostra 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>
  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

```bash theme={null}
curl -X POST https://api.apostra.com/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

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


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