{"openapi":"3.1.0","info":{"title":"Meloyab Recognition API","version":"0.9.83","description":"Sequential or independent parallel search. Per-engine metrics are not calibrated probabilities. No audio retention after operations."},"servers":[{"url":"/"}],"paths":{"/v1/recognize":{"post":{"summary":"Recognize a short audio sample","operationId":"recognizeAudio","security":[{"BearerKey":[]}],"parameters":[{"name":"mode","in":"query","schema":{"enum":["auto","classic","sequential","adaptive","chromaprint","landmark"],"default":"auto"}},{"name":"engines","in":"query","schema":{"type":"string","example":"chromaprint,landmark"},"description":"Optional comma-separated engines, in search order. Empty: the panel search engines. Only with mode=auto."},{"name":"strategy","in":"query","schema":{"enum":["auto","parallel","sequential","fallback"],"default":"auto"},"description":"parallel: chosen engines at once; sequential: one after another; fallback: one after another, stop at the first engine with a match; auto: panel strategy. Only with mode=auto."},{"name":"details","in":"query","schema":{"type":"boolean"},"description":"Compact responses: add Details (search plan, timings, engine attempts). Default: the key response profile."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"400":{"description":"Invalid request","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"401":{"description":"Invalid or disabled key","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"404":{"description":"Track or route missing","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"408":{"description":"Upload deadline","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"413":{"description":"Upload too large","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"415":{"description":"Send raw file bytes, not multipart or JSON","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"422":{"description":"Invalid audio","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"429":{"description":"Customer minute or concurrency budget exceeded","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"500":{"description":"Internal failure","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"503":{"description":"Live mode rejects new work only on real resource pressure; reserved mode also enforces saved worker budgets. Honor Retry-After; not_ready may instead contain a recognition result.","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/Recognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"200":{"description":"Full or compact recognition result according to customer profile; multiple songs are alternatives, not one selected winner.","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Recognition"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}}},"description":"Response profile is configured per customer key. Compact all_unique mode searches all enabled engines for auto/classic/sequential/adaptive requests and returns the union of threshold-qualified tracks. An explicitly named engine still searches only that engine. Existing keys keep configured selection and full responses."}},"/v1/recognize-clip":{"post":{"summary":"Recognize audio in a short video or audio clip","operationId":"recognizeClip","security":[{"BearerKey":[]}],"parameters":[{"name":"mode","in":"query","schema":{"enum":["auto","classic","sequential","adaptive","chromaprint","landmark"],"default":"auto"}},{"name":"engines","in":"query","schema":{"type":"string","example":"chromaprint,landmark"},"description":"Optional comma-separated engines, in search order. Empty: the panel search engines. Only with mode=auto."},{"name":"strategy","in":"query","schema":{"enum":["auto","parallel","sequential","fallback"],"default":"auto"},"description":"parallel: chosen engines at once; sequential: one after another; fallback: one after another, stop at the first engine with a match; auto: panel strategy. Only with mode=auto."},{"name":"details","in":"query","schema":{"type":"boolean"},"description":"Compact responses: add Details (search plan, timings, engine attempts). Default: the key response profile."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"400":{"description":"Invalid request","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"401":{"description":"Invalid or disabled key","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"404":{"description":"Track or route missing","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"408":{"description":"Upload deadline","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"413":{"description":"Upload too large","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"415":{"description":"Send raw file bytes, not multipart or JSON","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"422":{"description":"Invalid audio","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"429":{"description":"Customer minute or concurrency budget exceeded","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"500":{"description":"Internal failure","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"503":{"description":"Live mode rejects new work only on real resource pressure; reserved mode also enforces saved worker budgets. Honor Retry-After; not_ready may instead contain a recognition result.","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/Recognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"200":{"description":"Full or compact recognition result according to customer profile; multiple songs are alternatives, not one selected winner.","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Recognition"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}}},"description":"Response profile is configured per customer key. Compact all_unique mode searches all enabled engines for auto/classic/sequential/adaptive requests and returns the union of threshold-qualified tracks. An explicitly named engine still searches only that engine. Existing keys keep configured selection and full responses."}},"/v1/capabilities":{"get":{"summary":"Effective limits and search policy","security":[{"BearerKey":[]}],"responses":{"200":{"description":"Deployment capabilities","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"401":{"description":"Invalid or disabled key","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"404":{"description":"Track or route missing","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"408":{"description":"Upload deadline","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"413":{"description":"Upload too large","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"415":{"description":"Send raw file bytes, not multipart or JSON","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"422":{"description":"Invalid audio","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"429":{"description":"Customer minute or concurrency budget exceeded","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"500":{"description":"Internal failure","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"503":{"description":"Capacity, maintenance or index unavailable","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tracks/{track_id}":{"get":{"summary":"Resolve stable track identity to channel post","security":[{"BearerKey":[]}],"parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"Metadata, engine readiness, archive locator and telegram delivery credentials if permitted","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"401":{"description":"Invalid or disabled key","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"404":{"description":"Track or route missing","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"408":{"description":"Upload deadline","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"413":{"description":"Upload too large","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"415":{"description":"Send raw file bytes, not multipart or JSON","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"422":{"description":"Invalid audio","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"429":{"description":"Customer minute or concurrency budget exceeded","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"500":{"description":"Internal failure","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"503":{"description":"Capacity, maintenance or index unavailable","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tracks/{track_id}/refresh-delivery":{"post":{"summary":"Verify reported failed FileId and repair archive ownership now","security":[{"BearerKey":[]}],"description":"Requires telegram_credentials permission. Submit the exact failed FileId. Stale reports return current credentials; transient network failures do not invalidate a file.","parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["FileId"],"additionalProperties":false,"properties":{"FileId":{"type":"string","minLength":1,"maxLength":1024}}}}}},"responses":{"200":{"description":"IsSuccess, ErrorMessages, TrackId, FileId, TelegramToken and RepairStatus; inspect IsSuccess before delivery","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"401":{"description":"Invalid or disabled key","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"404":{"description":"Track or route missing","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"408":{"description":"Upload deadline","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"413":{"description":"Upload too large","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"415":{"description":"Send raw file bytes, not multipart or JSON","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"422":{"description":"Invalid audio","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"429":{"description":"Customer minute or concurrency budget exceeded","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"500":{"description":"Internal failure","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"503":{"description":"Capacity, maintenance or index unavailable","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tracks/{track_id}/download-link":{"get":{"summary":"Create a revocable download URL valid for 5 minutes","security":[{"BearerKey":[]}],"parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"Signed URL, expiry, streaming delivery and telegram object (bot_id, file_id, bot_token, available, reason); tokens require permission","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"401":{"description":"Invalid or disabled key","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"404":{"description":"Track or route missing","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"408":{"description":"Upload deadline","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"413":{"description":"Upload too large","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"415":{"description":"Send raw file bytes, not multipart or JSON","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"422":{"description":"Invalid audio","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"429":{"description":"Customer minute or concurrency budget exceeded","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"500":{"description":"Internal failure","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"503":{"description":"Capacity, maintenance or index unavailable","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tracks/{track_id}/download":{"get":{"summary":"Stream from Telegram without a server audio file","security":[{"BearerKey":[]},{}],"description":"Requires BearerKey or a signed URL from download-link. A range request is a new request. Customer rate/concurrency quotas are optional in live mode. When enabled they cover link issuance and streaming. Inspect capabilities for enforced policies and effective limits.","parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}},{"name":"Range","in":"header","schema":{"type":"string"}},{"name":"key","in":"query","schema":{"type":"string"}},{"name":"expires","in":"query","schema":{"type":"string"}},{"name":"signature","in":"query","schema":{"type":"string"}}],"responses":{"400":{"description":"Invalid request","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"401":{"description":"Invalid or disabled key","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"404":{"description":"Track or route missing","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"408":{"description":"Upload deadline","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"413":{"description":"Upload too large","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"415":{"description":"Send raw file bytes, not multipart or JSON","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"422":{"description":"Invalid audio","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"429":{"description":"Customer minute or concurrency budget exceeded","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"500":{"description":"Internal failure","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"503":{"description":"Capacity, maintenance or index unavailable","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"200":{"description":"Audio bytes","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"Partial audio bytes","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"416":{"description":"Invalid/unsatisfiable byte range"}}}},"/v1/search-music":{"post":{"summary":"Find ready catalog songs by normalized exact title and artist","security":[{"BearerKey":[]}],"operationId":"searchMusic","description":"No audio engines. Both names required; normalization handles case, Persian/Arabic letter and spacing variants. No fuzzy matching or longest-song preference. Every same-name recording is an alternative. Existing key response fields, download signing, archive repair and token permissions apply. During the resumable initial metadata migration returns 503 catalog_search_initializing, never a false absence. Use X-Next-Cursor with the same names to page results; concurrent additions can appear on later searches.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["MusicName","ArtistName"],"additionalProperties":false,"properties":{"MusicName":{"type":"string","minLength":1,"maxLength":300},"ArtistName":{"type":"string","minLength":1,"maxLength":300},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10},"after":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}}}},"responses":{"400":{"description":"Invalid request","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"401":{"description":"Invalid or disabled key","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"404":{"description":"Track or route missing","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"408":{"description":"Upload deadline","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"413":{"description":"Upload too large","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"415":{"description":"Send raw file bytes, not multipart or JSON","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"422":{"description":"Invalid audio","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"429":{"description":"Customer minute or concurrency budget exceeded","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"500":{"description":"Internal failure","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"503":{"description":"Capacity, maintenance or index unavailable","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/CompactRecognition"}]}}}},"200":{"description":"Full catalog result or configured compact response. IsFounded is metadata availability, not audio confidence.","headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}},"X-RateLimit-Limit":{"schema":{"type":"string"}},"X-RateLimit-Remaining":{"schema":{"type":"string"}},"X-RateLimit-Reset":{"schema":{"type":"string"}},"X-Concurrency-Enforced":{"schema":{"type":"string"}},"Server-Timing":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"string"}},"X-Next-Cursor":{"schema":{"type":"string"},"description":"Absent on last page"},"X-Catalog-Match":{"schema":{"const":"normalized_exact"}}},"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CompactRecognition"},{"type":"object","required":["status","method","complete","matches","match","lookup_ms","request_id","next_cursor"],"properties":{"status":{"enum":["matched","multiple_matches","no_match"]},"method":{"const":"catalog"},"complete":{"const":true},"matches":{"type":"array","items":{"$ref":"#/components/schemas/Match"}},"match":{"anyOf":[{"$ref":"#/components/schemas/Match"},{"type":"null"}]},"lookup_ms":{"type":"integer"},"request_id":{"type":"string"},"next_cursor":{"type":["string","null"]}}}]}}}}}}}},"components":{"securitySchemes":{"BearerKey":{"type":"http","scheme":"bearer"}},"schemas":{"TelegramDelivery":{"type":"object","required":["available","bot_id","file_id","bot_token","reason"],"properties":{"available":{"type":"boolean"},"bot_id":{"type":["integer","null"]},"file_id":{"type":["string","null"]},"bot_token":{"type":["string","null"],"description":"Full bot credential. Returned only to internal/operator access or keys with telegram_credentials enabled. Store server-side only."},"reason":{"type":["string","null"]}}},"Quality":{"type":"object","properties":{"match_percent":{"type":["number","null"],"minimum":0,"maximum":100},"metric":{"type":"string","enum":["fingerprint_bit_similarity","query_anchor_coverage","matched_time_coverage"]},"confidence_percent":{"type":"null"},"confidence_calibrated":{"const":false},"hits":{"type":"number"},"span":{"type":"number"},"score":{"type":"number"},"coverage":{"type":"number"},"similarity":{"type":"number"},"margin":{"type":"number"},"time_factor":{"type":"number"},"frequency_factor":{"type":"number"},"recovery_transform":{"type":"object","properties":{"kind":{"enum":["original","rate","pitch","tempo"]},"value":{"type":"number"},"time_scale":{"type":"number"}},"description":"Input transform used by optional difficult clip recovery; not a calibrated estimate of the original edit."},"recovery_confirmations":{"type":"integer","minimum":0,"description":"Consistent nearby transforms, not independent engine agreement."},"sequence_min_similarity":{"type":"number","minimum":0,"maximum":1},"sequence_segments":{"type":"array","items":{"type":"number"},"minItems":3,"maxItems":3}}},"Archive":{"type":"object","required":["chat_id","message_id","post_url","kind"],"properties":{"chat_id":{"type":"string","pattern":"^-100[0-9]+$"},"message_id":{"type":"integer","minimum":1},"post_url":{"type":"string","format":"uri","description":"Channel post link; private channels require membership."},"kind":{"enum":["audio","document"]},"bot_id":{"type":"integer"},"file_id":{"type":"string","description":"Reusable only by bot_id; never use as a cross-bot identity."},"file_unique_id":{"type":"string","description":"Identity hint only; cannot be used to download."},"file_size":{"type":"integer"}}},"Match":{"type":"object","required":["track_id"],"properties":{"track_id":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of original audio bytes; stable across bot changes."},"download_url":{"type":"string","format":"uri"},"download_expires_at":{"type":"integer"},"title":{"type":"string"},"artist":{"type":"string"},"filename":{"type":"string"},"offset_seconds":{"type":"number"},"duration_seconds":{"type":["number","null"],"description":"Duration of the catalog track, not processing or match span."},"archive":{"anyOf":[{"$ref":"#/components/schemas/Archive"},{"type":"null"}]},"telegram":{"$ref":"#/components/schemas/TelegramDelivery"},"quality":{"anyOf":[{"$ref":"#/components/schemas/Quality"},{"type":"null"}],"description":"Null for consensus; inspect evidence per engine."},"evidence":{"type":"object","additionalProperties":{"type":"object","properties":{"quality":{"$ref":"#/components/schemas/Quality"},"offset_seconds":{"type":"number"}}}},"duplicate_tracks":{"type":"array","description":"Other catalog entries with the same title and artist as this match; they are not separate answers.","items":{"type":"object","required":["track_id"],"properties":{"track_id":{"type":"string"},"archive":{"anyOf":[{"$ref":"#/components/schemas/Archive"},{"type":"null"}]},"duration_seconds":{"type":["number","null"]},"quality":{"anyOf":[{"$ref":"#/components/schemas/Quality"},{"type":"null"}]}}}}}},"Attempt":{"type":"object","required":["engine","status","elapsed_ms"],"properties":{"engine":{"enum":["chromaprint","landmark"]},"status":{"enum":["matched","no_match","not_indexed","search_limited","recovery_limited","error"]},"elapsed_ms":{"type":"integer"},"error_type":{"type":"string"},"match":{"$ref":"#/components/schemas/Match"},"engine_wait_ms":{"type":"integer","minimum":0},"reader_wait_ms":{"type":"integer","minimum":0},"engine_decode_ms":{"type":"integer","minimum":0},"engine_extract_ms":{"type":"integer","minimum":0},"search_elapsed_ms":{"type":"integer","minimum":0},"engine_error_code":{"type":"string"},"engine_error_type":{"type":"string"},"engine_service":{"type":"string"},"engine_admission_reason":{"type":"string"},"engine_descriptors_available":{"type":"integer","minimum":0},"engine_descriptors_used":{"type":"integer","minimum":0},"engine_descriptors_soft_limit":{"type":"integer","minimum":0},"engine_descriptors_hard_limit":{"type":"integer","minimum":0},"engine_http_status":{"type":"integer","minimum":100,"maximum":599},"accepted_count":{"type":"integer"},"search_scope":{"enum":["complete_index","bounded"]},"matches":{"type":"array","items":{"$ref":"#/components/schemas/Match"}},"limited_reason":{"type":"string","enum":["hit_budget","retrieval_deadline","candidate_deadline","candidate_budget","recovery_time_budget"]},"projected_hits":{"type":"integer","minimum":0},"retrieved_hits":{"type":"integer","minimum":0},"hit_budget":{"type":"integer","minimum":0},"candidate_count":{"type":"integer","minimum":0},"candidate_batches":{"type":"integer","minimum":0},"skipped_common_tokens":{"type":"integer","minimum":0},"cached":{"type":"boolean"},"coalesced":{"type":"boolean"},"source_elapsed_ms":{"type":"integer"},"recovery":{"type":"object","description":"Optional recovery for original files up to the configured recovery_max_seconds (default 12). The selected sample keeps the normal window length. An exhausted optional budget is recovery_limited, not a failed index search; the result remains inconclusive without a verified match. max_probes is the optional-recovery allowance including ordinary queries; explicitly configured ordinary windows are preserved even above it. The shared request time budget includes ordinary processing and stops new transforms, not running searches. Short clips with at least 16 fingerprint frames may use their actual attainable span under stronger similarity (at least 90%), coverage (95%) and segment (82%) checks; original-only acceptance requires 95% similarity. Saved thresholds and original-file cutoff remain intact. elapsed_ms covers every probe; other internal attempt timings describe the first probe only.","properties":{"enabled":{"type":"boolean"},"source_seconds":{"type":["number","null"],"minimum":0},"max_source_seconds":{"type":"integer","minimum":4,"maximum":3600},"probes":{"type":"array","maxItems":16,"items":{"type":"object","properties":{"kind":{"enum":["original","rate","pitch","tempo"]},"value":{"type":"number"},"elapsed_ms":{"type":"integer","minimum":0},"short_span":{"type":"boolean"},"effective_min_span":{"type":"number","minimum":0},"verified":{"type":"integer","minimum":0}}}},"sample_seconds":{"type":"number","minimum":0},"complete":{"type":"boolean"},"stop_reason":{"enum":["time_budget","probe_budget",null]},"status":{"enum":["recovered","original_verified","not_confirmed","span_setting_too_high","incomplete","original_unconfirmed","budget_exhausted","source_too_long","source_duration_unknown"]},"elapsed_ms":{"type":"integer","minimum":0},"probe_count":{"type":"integer","minimum":0},"request_probe_count":{"type":"integer","minimum":0},"max_probes":{"type":"integer","minimum":0},"verified_tracks":{"type":"integer","minimum":0},"budget_seconds":{"type":"integer","minimum":0}}}}},"Recognition":{"type":"object","required":["status","match","elapsed_ms","request_id","strategy","attempts","complete","agreement","candidates"],"properties":{"result_reason":{"enum":["engine_unavailable","search_incomplete","index_unavailable","insufficient_agreement","recovery_incomplete"]},"status":{"enum":["matched","no_match","not_ready","search_limited","conflict","inconclusive","multiple_matches"]},"method":{"enum":["chromaprint","landmark","consensus",null]},"strategy":{"enum":["sequential","adaptive"]},"request_id":{"type":"string"},"elapsed_ms":{"type":"integer","description":"Current recognition processing, including decoding and lookup. Upload is excluded; Server-Timing includes HTTP handling. Requests are assigned immediately to an available recognition worker."},"complete":{"type":"boolean","description":"Every attempted engine completed; a sequential early match does not inspect later engines."},"result_policy":{"type":"object","properties":{"mode":{"enum":["best","all","top"]},"prefer_longest":{"type":"boolean"},"max_results":{"type":"integer","minimum":1,"maximum":1000}}},"match_count":{"type":"integer","description":"Number of returned matches."},"total_match_count":{"type":"integer","description":"Distinct accepted matches before the presentation limit."},"results_truncated":{"type":"boolean"},"result_order":{"enum":["engine_priority_then_score","chromaprint_score_desc"],"description":"engine_priority_then_score: matches of the first engine in conflict_priority first, each engine by its own score"},"conflict_policy":{"enum":["reject","priority","all"]},"selection_reason":{"type":"string"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/Match"}},"match":{"anyOf":[{"$ref":"#/components/schemas/Match"},{"type":"null"}]},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/Attempt"}},"candidates":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Match"},{"type":"object","properties":{"engine":{"type":"string"}}}]}},"agreement":{"type":"object","properties":{"count":{"type":"integer"},"required":{"type":"integer"},"engines":{"type":"array","items":{"type":"string"}},"conflict":{"type":"boolean"}}},"cache":{"type":"object","properties":{"hit":{"type":"boolean"},"source_elapsed_ms":{"type":"integer"}}}}},"CompactRecognition":{"type":"object","required":["IsFounded","IsSuccess","ErrorMessages","Matches"],"additionalProperties":false,"properties":{"IsFounded":{"type":"boolean"},"IsSuccess":{"type":"boolean"},"ErrorMessages":{"type":"array","items":{"type":"string"}},"Matches":{"type":"array","items":{"$ref":"#/components/schemas/CompactMatch"}},"Details":{"type":"object","description":"Only when requested (details=true or the key profile): Search (engines, strategy, requested), Timing (TotalMs so far, InputMs, DecodeMs, ProbeMs, SearchMs, RecognitionMs, IndexWaitMaxMs, IndexExecutionAtMaxWaitMs), Cache, Attempts (per engine and clip window: Status, ElapsedMs, IndexWaitMs, IndexExecutionMs, Candidates, Accepted, Error), Status."}},"description":"Per-key compact response. Matches contains each accepted TrackId once. Missing selected values are null. No match can be successful; partial engine failure sets IsSuccess=false even when Matches is nonempty."},"CompactMatch":{"type":"object","additionalProperties":false,"properties":{"TrackId":{"type":["string","null"]},"MusicName":{"type":["string","null"]},"ArtistName":{"type":["string","null"]},"FileId":{"type":["string","null"]},"TelegramToken":{"type":["string","null"]},"musicDirectUrl":{"type":["string","null"]},"TelegramBotId":{"type":["integer","null"]},"ArchivePostUrl":{"type":["string","null"],"format":"uri","description":"Current Telegram archive post URL; private channels require membership. Optional per-key field, independent of bot token permission."},"Engines":{"type":"array","items":{"type":"string"}},"Engine":{"type":["string","null"],"description":"Engine whose result was returned"},"OffsetSeconds":{"type":["number","null"],"description":"Where the clip starts in the song"},"DurationSeconds":{"type":["number","null"],"description":"Song duration"},"Position":{"type":["string","null"],"description":"OffsetSeconds / DurationSeconds as m:ss / m:ss"},"ClipOffsetSeconds":{"type":["number","null"],"description":"Start of the matching window inside the uploaded clip"},"MatchPercent":{"type":["number","null"]},"EngineEvidence":{"type":"array","items":{"type":"object","properties":{"Engine":{"type":"string"},"OffsetSeconds":{"type":["number","null"]},"MatchPercent":{"type":["number","null"]}}}}}},"Error":{"type":"object","required":["detail","request_id"],"properties":{"detail":{"type":"string"},"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}