The canonical OpenAPI 3.1 specification for the AudD music recognition API.
This repository is the source of truth that all official AudD SDKs build their typed models against. Third parties can also use this spec to generate their own clients.
| File | Purpose |
|---|---|
openapi.yaml |
OpenAPI 3.1 spec covering every public AudD endpoint |
fixtures/ |
Real captured API responses, PII scrubbed — used by every SDK's contract tests |
tests/validate.py |
Validates each fixture against its schema in openapi.yaml |
tests/capture_fixtures.py |
Re-capture fixtures from the live API (requires an api_token) |
- Standard recognition —
POST/GET https://api.audd.io/ - Enterprise recognition —
POST https://enterprise.audd.io/(hours- to days-long files) - Stream management —
setCallbackUrl,getCallbackUrl,addStream,getStreams,setStreamUrl,deleteStream - Longpoll —
GET /longpoll/ - Custom catalog upload —
POST /upload/(special access required) - Lyrics search —
POST /findLyrics/
The WebSocket recognition variant is intentionally not modeled — AudD recommends the HTTP endpoints for all use cases.
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
python tests/validate.pyTo re-capture fixtures from the live API:
AUDD_TEST_TOKEN_STD=... AUDD_TEST_TOKEN_ENTERPRISE=... \
python tests/capture_fixtures.py
python tests/scrub_fixtures.pyThis spec is hand-written and validates against real fixtures. You can use it with any OpenAPI-compatible code generator. Note that AudD's official SDKs are hand-written rather than generated — to maximize idiomatic feel in each language — but they validate against this same spec.
When this repo lands a change to openapi.yaml or fixtures/, a workflow fires repository_dispatch events at every audd-<lang> SDK repo to re-run their contract tests against the new spec. Each SDK also runs the same tests on a nightly cron as a safety net.
MIT — see LICENSE.
- Documentation: https://docs.audd.io
- Tokens: https://dashboard.audd.io
- Email: api@audd.io