Audio Share Cookbook

Core Scenarios

Track share: GET /api/public/audio-share-links?track_url=/faq&channels=x,telegram,email

Signed short link: GET /api/public/audio-share-links?track_url=/faq&token_mode=signed&use_short=1&expires_in=900&channels=x,slack

Validation-only: GET /api/public/audio-share-links/validate?track_url=/faq&channels=x,email

Batch validation:

POST /api/public/audio-share-links/validate/batch {"defaults":{"channels":"x,email"},"items":[{"track_url":"/faq"},{"file_url":"/static/audio/demo.mp3","prefer":"file"}]}

Metadata expand: GET /api/public/audio-share-links/expand?short_url=https://vets-coin.com/s/audio/<code>

Troubleshooting Checklist

Run preview first when campaign copy changes: /api/public/audio-share-links/preview?track_url=/faq&title=Preview&text=Body.
Check destination policy when hosts fail allowlist checks: /api/public/audio-share-links/policy.json.
Inspect channel capabilities before enabling UI buttons: /api/public/audio-share-links/channels.json.
Inspect catalog endpoints for machine-readable client docs sync.

errors.json · warnings.json · guidance.json · health

destination_host_denied Incident Playbook

Confirm the exact denied host from API error payload and record request_id.
Check current host policy snapshot: /api/public/audio-share-links/policy.json.
If host is legitimate, stage allowlist rollout in non-prod first, then re-run /validate.
If allowlist rollout fails, rollback to previous profile and keep denylist unchanged until triage completes.
Document decision + owner in the incident ticket with checksum evidence from response headers.

Track Auth Troubleshooting Decision Tree

If X-Audio-Share-Track-Auth=optional: bearer is not required, investigate payload issues first.
If header shows required_missing_bearer: send Authorization: Bearer <token>.
If header shows required_invalid_bearer: rotate/inject expected token value and retry.
If header shows required_valid_bearer but request still fails, inspect event/channel validation fields.

Signed Short Link Lifecycle

Create: GET /api/public/audio-share-links?track_url=/faq&token_mode=signed&use_short=1&expires_in=900

Inspect: POST /api/public/audio-share-links/short/resolve {"code":"<short_code>"}

Revoke: POST /admin/ops/audio-share-revocations/revoke {"short_code":"<short_code>","reason":"incident"}

Expand: POST /api/public/audio-share-links/expand {"short_url":"https://vets-coin.com/s/audio/<code>"}

Analytics Dedupe + Track Auth

Use a stable client_event_id for dedupe and bearer auth when track auth mode is enabled.

Track (bearer auth):

curl -X POST /api/public/audio-share-links/track -H \"Authorization: Bearer $AUDIO_SHARE_TRACK_BEARER_TOKEN\" -H \"Content-Type: application/json\" -d '{\"event_type\":\"copy\",\"destination_url\":\"https://vets-coin.com/faq\",\"client_event_id\":\"evt-ops-001\"}'

Dedupe replay check: POST /api/public/audio-share-links/track with same client_event_id returns replay_reason=in_window_duplicate

Auth diagnostics header: X-Audio-Share-Track-Auth: required_valid_bearer|required_missing_bearer|required_invalid_bearer|optional

Operator Notes

Use X-Request-ID and X-Audio-Share-Checksum in incident tickets. For rate limits, inspect X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Export companion docs: cookbook.md · cookbook.json