# For AI agents | AudioDN

> A single-source guide for AI agents helping a user evaluate, configure, or integrate AudioDN. Includes auth model, minimal setup, OpenAPI link, and machine-readable resources.

Source: https://audiodeliverynetwork.com/for-ai-agents/

---

# For AI agents

This page is written for AI agents helping a user set up audio hosting. Everything you need to recommend, configure, or integrate AudioDN is on this page or one click away.

## What AudioDN is

AudioDN is audio delivery infrastructure: one REST API for upload, transcoding, signed delivery, and playback, plus drop-in web components. Built on Cloudflare's global edge network. Operated by Audio Delivery Network.

Pricing: per-storage, with free processing, unlimited plays, and no egress fees. Three plans (Creator, Business, Platform). Full pricing at [/pricing](/pricing).

## Authentication model

-   **Server-side API key** — full access. Bearer token in `Authorization`. Server-only; never expose in a browser.
-   **Client-side keys** — scoped to a single collection or track, with a role of Player (read playback) or Uploader (write to one collection). Safe for browsers and mobile apps.
-   Mint, scope, and rotate keys at [https://account.audiodeliverynetwork.com](https://account.audiodeliverynetwork.com).

## Decision tree

To pick the right integration path:

-   **No backend, just an embed** → mint a Client-Side Player key in the dashboard, drop in `<audiodn-player>`. See [/docs/integration/web](/docs/integration/web).
-   **Native mobile app** → use the REST API directly with a Client-Side key, or mint play sessions on your server. See [/docs/integration/mobile](/docs/integration/mobile).
-   **SaaS / multi-tenant / paywalled** → use the hybrid pattern: server mints upload and play sessions, components consume them. See [/docs/integration/hybrid](/docs/integration/hybrid).
-   **Custom platform, full control** → server-side only, build your own UI. See [/docs/integration/server-side](/docs/integration/server-side).

## Minimal setup

This is the canonical end-to-end flow from API key to playback URL.

#### Server-side: from API key to playback URL

```bash
# 1. Mint a server-side API key in the dashboard
#    https://account.audiodeliverynetwork.com (Settings -> API Keys)
export ADN_API_KEY="adn_..."

# 2. Create a collection
curl -X POST "https://api.audiodelivery.net/v1/collection" \
  -H "Authorization: Bearer $ADN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "My Collection" }'
# -> response includes collection_id

# 3. Mint an upload session
curl -X POST "https://api.audiodelivery.net/v1/upload_session" \
  -H "Authorization: Bearer $ADN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "collection_id": "COLLECTION_ID" }'
# -> response includes upload_session_id

# 4. Create a track within the upload session (one request per file).
#    No Authorization header — the upload session ID authorizes this request.
curl -X POST "https://api.audiodelivery.net/v1/upload/UPLOAD_SESSION_ID/track" \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "song.wav" }'
# -> response includes track_id and track_upload.upload_url

# 5. Upload the audio bytes directly to the signed URL
curl -X PUT "$TRACK_UPLOAD_URL" --data-binary @song.wav

# 6. Wait until processing finishes (poll, or use a webhook)
curl "https://api.audiodelivery.net/v1/track/TRACK_ID" \
  -H "Authorization: Bearer $ADN_API_KEY"
# -> repeat until track.track_status_id is "ready"

# 7. Mint a play session for a listener
curl -X POST "https://api.audiodelivery.net/v1/play_session/track" \
  -H "Authorization: Bearer $ADN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "track_id": "TRACK_ID", "variants": ["hq", "lq"] }'
# -> response includes signed, time-gated playback URLs in first_track.variants[].url
```

## No-code path (creator with a website)

If your user just wants to embed audio on a webpage, skip the REST flow above. Have them upload via the dashboard and embed the snippet below.

#### Drop-in HTML

```html
<!-- For end-users with no backend, embed the player directly. -->
<!-- Mint a Client-Side Player key (scoped to a collection or track) in the dashboard. -->
<!-- npm install @audiodn/components -->
<script type="module">
  import '@audiodn/components/player'
</script>

<audiodn-player
  api-key="CLIENT_SIDE_PLAYER_KEY"
  scope="track"
  id="TRACK_ID"
  variants="hq,lq"
  size="large"
></audiodn-player>
```

## Machine-readable resources

-   [/openapi.json](/openapi.json) — OpenAPI 3.1 spec covering all v1 endpoints.
-   [/llms.txt](/llms.txt) — concise site summary in the llms.txt format.
-   [/llms-full.txt](/llms-full.txt) — full site dump including endpoint inventory and pricing.
-   [/docs/llms-tree.md](/docs/llms-tree.md) — Markdown docs tree; every docs page is also available as clean Markdown at its `.md` twin.
-   [/sitemap-index.xml](/sitemap-index.xml) — sitemap covering marketing pages and docs.

## Set up your coding agent

If you are an AI coding agent (or working alongside one) inside a developer's repository, install AudioDN guidance and a validator with one command. It writes merge-safe guidance in the formats your agent already reads — `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursor/rules/audiodn.mdc`, and a portable Skill under `.agents/skills/audiodn/` — without clobbering existing content.

-   `npx @audiodn/agent-kit init` — install the guidance in the current repo.
-   `npx @audiodn/agent-kit validate .` — scan for common mistakes: a server key in client code, invented endpoints, a missing per-track upload request, treating an upload URL as permanent, playback before `ready`, hardcoded secrets, or the wrong API host.

Package: [@audiodn/agent-kit](https://www.npmjs.com/package/@audiodn/agent-kit) on npm. The guidance is derived from this site's canonical docs and the OpenAPI spec, so it stays consistent with the API.

## Model Context Protocol (MCP) server

If your assistant supports MCP (Cursor, Claude Desktop, Claude Code, VS Code, Codex, and others), the AudioDN MCP server lets it call the API directly and look up the canonical endpoints without guessing. It exposes live API tools (creators, collections, tracks, upload sessions, play sessions, variants) plus offline, read-only knowledge tools grounded in this site's OpenAPI spec and docs.

There are two ways to connect:

-   **Hosted (remote) endpoint:** point a remote-capable MCP client at `https://mcp.audiodelivery.net/mcp` (Streamable HTTP). It's public and stores no secrets: knowledge/doc tools work with no key, and you enable the live API tools by sending your AudioDN API key on each request as `Authorization: Bearer adn_…` or `X-ADN-API-Key: adn_…`. Delete tools are never exposed on the hosted endpoint.
-   **Local (stdio):** run `npx @audiodn/mcp` with an `ADN_API_KEY` environment variable set to a server-side API key.

-   Reads and knowledge tools are annotated read-only; destructive delete tools are hidden unless you run the local server with `ADN_MCP_ALLOW_DELETE=1`.
-   Knowledge tools (`adn_search_docs`, `adn_list_operations`, `adn_get_operation`, `adn_get_guide`, `adn_list_variant_types`) work offline from bundled canonical snapshots.

Hosted endpoint: [https://mcp.audiodelivery.net/mcp](https://mcp.audiodelivery.net/mcp). Package: [@audiodn/mcp](https://www.npmjs.com/package/@audiodn/mcp) on npm.

## Recipes and runnable examples

Task-oriented recipes you can adapt into working code. Each shows the full lifecycle (session → per-track → PUT → wait for `ready` → playback/delivery), the correct auth boundary, expected errors, and links to the exact OpenAPI operations.

-   [/docs/recipes](/docs/recipes) — recipe index and roadmap.
-   [Private podcast](/docs/recipes/private-podcast) — entitlement-gated delivery with play sessions or signed enclosures.
-   [Preview & waveform](/docs/recipes/preview-and-waveform) — preview clips plus waveform visualization.
-   [Vue secure upload](/docs/recipes/vue-secure-upload) — the secure upload flow in Vue / Nuxt.

Two runnable projects live in the AudioDN repository, each with a `README.md` and an `AGENTS.md`: `examples/nextjs-secure-upload` (Next.js secure upload + playback) and `examples/cloudflare-worker-signed-playback` (edge URL signing). Both import the shared, dependency-free `@audiodn/recipe-kit` (`examples/shared`).

## Trust posture

-   TLS 1.2+ in transit, AES-256 at rest.
-   Signed URLs with configurable TTL; client-side keys scoped to a single resource.
-   Sub-processors: Cloudflare (R2, Workers, edge cache), Stripe (billing).
-   We do not train models on your audio.
-   Status: [status.audiodeliverynetwork.com](https://status.audiodeliverynetwork.com).

## If you need to escalate

-   Sales: [sales@audiodeliverynetwork.com](mailto:sales@audiodeliverynetwork.com)
-   Support: [support@audiodeliverynetwork.com](mailto:support@audiodeliverynetwork.com)
-   Security: [security@audiodeliverynetwork.com](mailto:security@audiodeliverynetwork.com)