1
Get your API key
Create a developer account and request a key from the API keys page. Pass it on every request as a Bearer token or X-API-Key header.
Partner API · v1
HTTP API for the Wav Linq attribution protocol — asynchronous detection via job polling, plus federated embed so credit resolves against your catalog, not ours. Sign up or login to your developer account to get started.
Base URL
https://wavlinq.com
2
Submit a detection job
POST /api/detect/jobs with an audio file. You receive a job_id immediately — processing runs in the background.
3
Poll until complete
GET /api/detect/jobs/{job_id} with exponential backoff until status is succeeded or failed. Typical jobs finish in 2–8 seconds.
4
Embed + register (optional)
Join the federated network — embed a Linq ID and register your resolver URL so attribution resolves against your catalog when others run detection.
1. Authentication
All endpoints require a partner API key. Include it on every request using one of the headers below.
Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY
Headers
| Name | Description |
|---|---|
| Authorizationrequired | Bearer <key> — standard OAuth-style header |
| X-API-Key | Alternative to Authorization — pass the raw key value |
Create and rotate keys on the API keys page. Live and test environments use separate keys. A missing key returns 401; an invalid key or a key not authorized for that job returns 403.
2. Detection jobs
Upload audio, receive a job_id, then poll until attribution is ready.
1
Submit a detection job
Upload an audio file to start asynchronous attribution detection. Returns a job_id immediately.
POST
https://wavlinq.com/api/detect/jobs
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data
Idempotency-Key: optional-unique-id
Body parameters
| Name | Type | Description |
|---|---|---|
| audio_filerequired | file | Audio file to analyze (multipart field) |
Response · 202 Accepted
{
"job_id": "abc123-def456",
"status": "processing"
}
Pass Idempotency-Key on retries — the same key returns the same job_id with 200 instead of 202.
2
Poll job status
Poll until status is succeeded or failed. Use exponential backoff — do not poll faster than once per second.
GET
https://wavlinq.com/api/detect/jobs/{job_id}
Authorization: Bearer YOUR_API_KEY
Response · 200 succeeded
// succeeded response
{
"status": "succeeded",
"watermark_found": true,
"signature": "A1B2C3D4E5F6G7H8I9J0",
"attribution_source": "partner_registry:live",
"metadata": {
"title": "Song Title",
"artist": "Artist Name",
"isrc": "USABC2400001",
"rights_holder": "Label Name"
}
}
attribution_source values
| Value | Description |
|---|---|
| direct | Metadata resolved from Wav Linq embed record |
| partner_registry:live | Live call to your resolver endpoint succeeded |
| partner_registry:cache | Metadata served from cache |
| partner_registry:registry_only | Signature found in registry but no metadata returned |
Rate limits
120 requests/minute per API key for POST /api/detect/jobs. Over limit returns 429 with a Retry-After header — honor it and do not tight-loop. Contact us for higher throughput on catalog backfills.
watermark_found: true means a Wav Linq Linq ID was recovered from the signal and passed the protocol's integrity validation (CRC checksum and cryptographic authentication).
3. Federated embed
How it works
Join the network as a node — embed a Linq ID and register a resolver URL pointing to your catalog. When anyone runs detection, Wav Linq calls your node's HTTPS endpoint to fetch track metadata. We never store it ourselves. Apply partner_registry.sql in your database before first use.
1
Embed + register resolver
Embeds a Linq ID and registers your resolver URL in one step. Returns attributed audio/wav as a download.
POST
https://wavlinq.com/api/v1/partner/embed
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data
Body parameters
| Name | Type | Description |
|---|---|---|
| audio_filerequired | file | Source audio to embed (multipart field) |
| track_id | string | Track identifier used in signature generation |
| song_title | string | Alternative to track_id for signature generation |
| resolver_endpoint | string | Full resolver URL per request (Option A) |
| resolver_base_url | string | Base URL — Wav Linq appends path template (Option B) |
| resolver_path_template | string | Defaults to resolve/{signature}. Use {SIG} for uppercase hex |
Response · 200 audio/wav
X-WavLinq-Signature: A1B2C3D4E5F6G7H8I9J0
X-WavLinq-Partner-Account-ID: your-account-id
X-WavLinq-Key-Fingerprint: key-fingerprint
For resolver URL, pick one approach: pass a full resolver_endpoint per request, or provide resolver_base_url + resolver_path_template and Wav Linq builds base/resolve/{signature}.
4. Your resolver
Implement on your side — Wav Linq only stores a pointer to your resolver in partner_registry. We GET your HTTPS endpoint; your database stays yours.
1
Resolver contract
Wav Linq calls your registered URL when detection finds a partner-embedded Linq. Return JSON track metadata.
GET
https://your-node.example/resolve/{signature}
X-WavLinq-Signature: A1B2C3D4E5F6G7H8I9J0
X-WavLinq-Timestamp: 1710000000 (if HMAC enabled)
X-WavLinq-HMAC: hex-hmac-sha256 (if HMAC enabled)
Request headers
| Name | Description |
|---|---|
| X-WavLinq-Signaturerequired | 20-character signature (Linq ID) from the detection result |
| X-WavLinq-Timestamp | Unix timestamp (seconds) — sent when HMAC verification is enabled |
| X-WavLinq-HMAC | Hex HMAC-SHA256 of "{timestamp}.{SIGNATURE_UPPER}" |
Response · 200 OK
{
"title": "Track Title", // required
"artist": "Artist Name", // required
"isrc": "USABC2400001", // optional
"rights_holder": "Label Name", // optional
"release_date": "2024-03-15", // optional
"custom": { /* any additional fields */ }
}
Return 404 for unknown signatures — detection still succeeds with registry-only attribution, metadata simply absent. Reject requests if HMAC skew is too large or MAC verification fails.
5. Operations
!
Failure handling
Design your pipeline for our worst case scenarios.
Error handling
| Situation | We return | Recommended behavior |
|---|---|---|
| Job not ready | status: processing | Keep polling with backoff; don't block user-facing flows |
| Rate limited | 429 + Retry-After | Back off per header; queue and retry |
| Degraded / unreachable | 5xx / timeout | Fail open — treat attribution as deferred, re-submit later |
| Auth problem | 401 / 403 | Surface as config error; verify key matches job owner |
| Unknown resolver | succeeds, registry_only | Detection succeeds; metadata absent |
Idempotency & versioning
Pass Idempotency-Key on retries — same key returns the same job_id (200 on replay vs 202 on first submit). The API is versioned (v1). Breaking changes ship under a new version with 90 days notice. Subscribe to API Status for advisories.