Partner API · v1

Detection & Federated Embed

Asynchronous watermark detection via job polling, plus federated embed so attribution resolves against your catalog — not ours. Sign up or login to your developer account to get started.

Detection jobs
POST Submit a detection job

Upload an audio file to start asynchronous watermark detection. Returns a job_id immediately — processing happens in the background.

POST https://wavlinq.com/api/detect/jobs
Content-Type multipart/form-data — field name audio_file
Auth Authorization: Bearer <key> or X-API-Key: <key>
Idempotency Pass Idempotency-Key on retries — same key returns the same job_id
Response 202 with job_id  ·  200 on idempotent replay
GET Poll job status

Poll until status is succeeded or failed. Use exponential backoff — typical jobs complete in 2–8 s.

GET https://wavlinq.com/api/detect/jobs/<job_id>
Auth Same API key used to submit the job
Auth errors 401 missing key  ·  403 wrong key for that job  (when DETECTION_API_REQUIRE_AUTH=1)
// 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" } }
direct partner_registry:live partner_registry:cache partner_registry:registry_only
Rate limits
Over limit 429 with Retry-After header
Server config DETECTION_RATE_LIMIT_PER_MINUTE
Federated embed
How it works: you embed a watermark and register a resolver URL pointing to your catalog. When anyone runs detection, Wav Linq calls your HTTPS endpoint to fetch track metadata — we never store it ourselves.
POST Embed + register resolver

Watermarks audio and registers your resolver URL in one step. Apply partner_registry.sql in your database before first use.

POST https://wavlinq.com/api/v1/partner/embed
Required audio_file (multipart field)
Auth Same DB-backed key as detection jobs
Response Watermarked audio/wav attachment
Headers X-WavLinq-Signature  ·  X-WavLinq-Partner-Account-ID  ·  X-WavLinq-Key-Fingerprint
Optional track_id or song_title — used as the track identifier in signature generation

Resolver URL — pick one approach

Option Field(s) Notes
Full URL resolver_endpoint Pass the complete URL per request, e.g. if you generate signed URLs server-side.
Base + template resolver_base_url
resolver_path_template		 Wav Linq builds the URL: base/resolve/{signature}. Template defaults to resolve/{signature}. Use {SIG} for uppercase hex.
Your resolver (implement on your side)
Your database can be anything. Wav Linq only stores a pointer to your resolver in our partner_registry table. We never connect to your DB — we just GET your HTTPS endpoint. Use PostgreSQL, DynamoDB, MongoDB, a bespoke service, anything.
GET Resolver contract

Wav Linq calls your registered URL when detection finds a partner-embedded Linq. Return JSON track metadata.

Always sent X-WavLinq-Signature: <20-char composite>
HMAC (optional) If PARTNER_RESOLVER_HMAC_SECRET is set, Wav Linq also sends X-WavLinq-Timestamp (Unix s) and X-WavLinq-HMAC — hex HMAC-SHA256 of "{timestamp}.{SIGNATURE_UPPER}". Reject if skew is too large or MAC fails.
If unknown 404 — detection still succeeds with registry-only attribution, no metadata

200 response body

{ "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 */ } }

The attribution_source field in detection responses reflects how metadata was resolved:

direct partner_registry:live partner_registry:cache partner_registry:registry_only