Audio Share Cookbook

Reference scenarios, QA checks, and troubleshooting commands for audio-share links.

Last updated: 2026-06-17 01:46:21 UTC

Open Helper Run Base Example Back to Developers System Status Trust Center

Why This Cookbook Exists

This cookbook is part of the public project trust stack. It gives partners repeatable QA and incident-response examples that can be checked against the same live API, status, and reliability surfaces used elsewhere across the VETS Coin platform.

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