{"openapi": "3.1.0", "info": {"title": "SongCleaner Corporate API", "version": "1", "description": "\nProgrammatic access to SongCleaner: submit a track, poll it, download the\ncleaned audio and the separated stems.\n\n**Authentication.** Every endpoint takes `Authorization: Bearer sc_live_...`.\nMissing, malformed, unknown, revoked and deactivated-account keys all fail\nidentically with `401 invalid_api_key`, so the API is not a key-existence\noracle. Session cookies grant nothing here.\n\n**Errors.** Every error response this API produces is the same envelope,\nand the `code` is the part to branch on. The `message` is for humans and may be reworded without\nnotice:\n\n```json\n{\"error\": {\"code\": \"invalid_api_key\", \"message\": \"Unauthorized.\"}}\n```\n\nEach operation below lists the codes it can raise. The full set is:\n`bad_request`, `invalid_api_key`, `forbidden`, `not_found`, `method_not_allowed`, `idempotency_conflict`, `not_ready`, `deletion_needs_review`, `gone`, `file_too_large`, `file_required`, `unsupported_media_type`, `no_audio_stream`, `invalid_artifact_kind`, `invalid_webhook_url`, `source_url_not_supported`, `review_mode_not_available`, `validation_error`, `rate_limited`, `too_many_in_flight`, `internal_error`.\n\nOne exception, and it is worth handling: a request body larger than the\nreverse proxy's own cap is rejected BEFORE it reaches the API, which\nanswers 413 with an HTML body rather than this envelope. Treat a 413 whose\nbody will not parse as JSON as \"upload too large\". Uploads within the\n200 MB limit never reach it.\n\n**Limits.** 200 MB per upload,\n60 requests per minute per account across all of its\nkeys, 100 tracks per page when listing.\n\nNew submissions are refused with `too_many_in_flight` once the account has\n20 or more tracks processing, counted across all of its keys.\nThat is an admission threshold, not a hard ceiling: submissions made at the\nsame moment on different keys are each checked before the others land, so\nan account can briefly run over it, by up to one track for each additional\nkey submitting at that moment. A replay of an already accepted submission\n(the same `Idempotency-Key`) is not a new submission and is never refused\nfor this.\n\nSubmissions carrying `Idempotency-Key` are replay-safe for\n24 hours.\n\n**Retention.** Tracks and their artifacts are deleted\n180 days after completion, and the deletion\nis confirmed against object storage before the record goes. Download what\nyou need inside that window.\n\n**Deleting one track.** `DELETE /api/v1/tracks/{track_id}` deletes a single\ntrack and its audio whenever you want, without waiting for the retention\nwindow. Processing still in flight is stopped rather than finished.\n\n**Deletion on request.** For a whole account, ask us in writing and we\ndelete the audio we hold \u2014 the stored artifacts, the working copies and the\nseparation stems \u2014 within 30 days. Your API\nkeys have to be revoked first, because erasure cannot outrun a key that\nstill authenticates. Deletion is confirmed against object storage before we\nreport it complete, and anything we cannot confirm keeps your records until\nit is resolved, with an explanation.\n\nBackups are covered by the same 30 days: we\nkeep backups of your audio no longer than that, so none outlives a deletion\nrequest.\n\nUploads that never became a track are not linked to an account, so they sit\noutside this process \u2014 the link would have been the track record, and it\nwas never written. They are removed by our periodic maintenance of\ntemporary files.\n\n**Versioning.** This is v1 and it is append-only: fields may be added, never\nrenamed or removed. A breaking change would ship as `/api/v2/`.\n\nThe walkthrough, with copy-pasteable curl and a webhook verification\nsnippet, is at [/api/docs/](/api/docs/).\n"}, "paths": {"/api/v1/tracks": {"get": {"operationId": "api_api_v1_list_tracks", "summary": "List tracks", "parameters": [{"name": "status", "in": "query", "required": false, "schema": {"type": "string", "enum": ["processing", "analyzed", "rendering", "complete", "failed"]}, "description": "`analyzed` is valid and matches nothing in v1."}, {"name": "reference", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 255}, "description": "Exact match on what you sent at submission."}, {"name": "page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "default": 1}}, {"name": "per_page", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}}], "responses": {"200": {"description": "A page of tracks.", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"type": "object", "description": "Fields appear as the data behind them becomes real, so a key is never present carrying a placeholder.", "properties": {"id": {"type": "string", "examples": ["trk_9dQ4vK2mR7xT1sPzYb3WgA"]}, "status": {"type": "string", "enum": ["processing", "analyzed", "rendering", "complete", "failed"]}, "reference": {"type": ["string", "null"], "description": "Whatever you sent at submission."}, "created_at": {"type": "string", "format": "date-time"}, "flagged_word_count": {"type": "integer", "description": "Present once analysis has run."}, "artifacts": {"type": "array", "items": {"type": "object", "properties": {"kind": {"type": "string", "enum": ["clean_mp3", "clean_flac", "instrumental"]}, "download_path": {"type": "string", "description": "Follow this for a fresh redirect. It is not a signed URL and does not expire."}, "size_bytes": {"type": "integer", "description": "The size verified in storage. Omitted for tracks stored before sizes were recorded."}}, "required": ["kind", "download_path"], "additionalProperties": false}, "description": "Present only while status is `complete`. Empty if the track is being deleted."}, "deletion_claimed_at": {"type": "string", "format": "date-time", "description": "Present once a deletion has been decided, by your DELETE or by the retention window. `status` still describes the pipeline; this is why the artifacts went away."}}, "required": ["id", "status", "reference", "created_at"], "additionalProperties": false}}, "page": {"type": "integer"}, "per_page": {"type": "integer"}, "count": {"type": "integer", "description": "Total matching tracks, not just this page."}, "has_more": {"type": "boolean"}}, "required": ["data", "page", "per_page", "count", "has_more"], "additionalProperties": false}}}}, "422": {"description": "`validation_error`: A parameter is wrong: an unknown status filter, a bad page size.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "401": {"description": "`invalid_api_key`: Missing, malformed, unknown, revoked or deactivated key. All four fail identically, so this is not a key-existence oracle.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "429": {"description": "`rate_limited`: Too many requests this minute. Retry-After says when to come back.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "500": {"description": "`internal_error`: Our fault. Retry, then tell us.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}}, "description": "\nEvery track submitted with this account's keys, newest first.\n\nFilter by `status` (`processing`, `analyzed`, `rendering`, `complete`, `failed`) or by\nthe `reference` you supplied at submission. `analyzed` is a valid filter\nthat matches nothing in v1: it belongs to review mode, which is not part of\nthis version.\n\nPaginated: `page` starts at 1, `per_page` defaults to 50 and caps at\n100.\n", "security": [{"ApiKeyAuth": []}]}, "post": {"operationId": "api_api_v1_create_track", "summary": "Submit a track", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "maxLength": 255, "pattern": "^[\\x20-\\x7e]+$"}, "description": "Your own unique id for this submission. Replay-safe for 24 hours."}], "responses": {"202": {"description": "Accepted. Processing is asynchronous and may begin before this response reaches you.", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string"}, "status": {"type": "string", "enum": ["processing", "analyzed", "rendering", "complete", "failed"]}, "reference": {"type": ["string", "null"]}}, "required": ["id", "status", "reference"], "additionalProperties": false}}}}, "400": {"description": "`bad_request`: Malformed request.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "422": {"description": "`file_required`: No file part in the multipart body. `unsupported_media_type`: Not an audio file we accept. MP3, FLAC, WAV and MP4 only. `no_audio_stream`: The container carries no audio stream. `invalid_webhook_url`: webhook_url is not an HTTPS URL we will deliver to. `source_url_not_supported`: Submit the audio itself; we do not fetch from a URL. `review_mode_not_available`: Review mode is not part of v1. Tracks are cleaned automatically. `validation_error`: A parameter is wrong: an unknown status filter, a bad page size.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "413": {"description": "`file_too_large`: The upload is over the size limit. A body over the reverse proxy's own cap is rejected before it reaches the API, and that 413 carries an HTML body rather than this envelope.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}, "text/html": {"schema": {"type": "string", "description": "The proxy's own rejection page. Sent instead of the JSON envelope when the body is refused before it reaches the API. Check the status code, not the body, for this one."}}}}, "409": {"description": "`idempotency_conflict`: That Idempotency-Key was already used with a different payload.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "429": {"description": "`too_many_in_flight`: The account is at or over its in-flight threshold, counting every key. New submissions are refused until tracks finish; a replay of an already accepted submission still returns the original. `rate_limited`: Too many requests this minute. Retry-After says when to come back.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "401": {"description": "`invalid_api_key`: Missing, malformed, unknown, revoked or deactivated key. All four fail identically, so this is not a key-existence oracle.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "500": {"description": "`internal_error`: Our fault. Retry, then tell us.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}}, "description": "\nSubmit audio for cleaning. Returns 202 with the track's id; the file is\nvalidated and its audio extracted before you get that, and the cleaning\nitself runs asynchronously afterwards.\n\nAsynchronously is the whole of the promise, and no ordering comes with it:\na worker can pick the track up while the 202 is still travelling to you, so\na webhook for it may arrive BEFORE your HTTP client returns. If you record the track id from the\nresponse and your webhook handler looks it up, handle the id you have not\nstored yet -- retry it, or key the handler off the `reference` you sent.\n\nSend `multipart/form-data` with a `file` up to 200\nMB (MP3, FLAC, WAV or MP4). Optional: `reference`, echoed back everywhere so\nyou can carry your own id; `webhook_url`, an HTTPS endpoint that receives\nsigned events; `engine`, only if you have been asked to pin one.\n\nSend an `Idempotency-Key` header and a repeat of the same request inside\n24 hours returns the original\ntrack instead of processing it twice. The same key with a different payload\nanswers `idempotency_conflict`.\n", "security": [{"ApiKeyAuth": []}], "requestBody": {"required": true, "content": {"multipart/form-data": {"schema": {"type": "object", "properties": {"file": {"type": "string", "format": "binary", "description": "MP3, FLAC, WAV or MP4."}, "reference": {"type": "string", "maxLength": 255, "description": "Your id for this track. Echoed back everywhere."}, "webhook_url": {"type": "string", "format": "uri", "maxLength": 2000, "description": "HTTPS endpoint for signed events. Optional: polling works just as well."}, "engine": {"type": "string", "enum": ["multilingual-v1", "studio-v1", "standard-v1", "pro-v1"], "description": "Only if you have been asked to pin one."}, "auto_clean": {"type": "string", "enum": ["true"], "description": "Accepted for forward compatibility and must be true: review mode is not part of v1, so auto_clean=false answers review_mode_not_available."}}, "required": ["file"], "additionalProperties": false}}}}}}, "/api/v1/tracks/{track_id}": {"get": {"operationId": "api_api_v1_retrieve_track", "summary": "Retrieve one track", "parameters": [{"in": "path", "name": "track_id", "schema": {"title": "Track Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "The track.", "content": {"application/json": {"schema": {"type": "object", "description": "Fields appear as the data behind them becomes real, so a key is never present carrying a placeholder.", "properties": {"id": {"type": "string", "examples": ["trk_9dQ4vK2mR7xT1sPzYb3WgA"]}, "status": {"type": "string", "enum": ["processing", "analyzed", "rendering", "complete", "failed"]}, "reference": {"type": ["string", "null"], "description": "Whatever you sent at submission."}, "created_at": {"type": "string", "format": "date-time"}, "flagged_word_count": {"type": "integer", "description": "Present once analysis has run."}, "artifacts": {"type": "array", "items": {"type": "object", "properties": {"kind": {"type": "string", "enum": ["clean_mp3", "clean_flac", "instrumental"]}, "download_path": {"type": "string", "description": "Follow this for a fresh redirect. It is not a signed URL and does not expire."}, "size_bytes": {"type": "integer", "description": "The size verified in storage. Omitted for tracks stored before sizes were recorded."}}, "required": ["kind", "download_path"], "additionalProperties": false}, "description": "Present only while status is `complete`. Empty if the track is being deleted."}, "deletion_claimed_at": {"type": "string", "format": "date-time", "description": "Present once a deletion has been decided, by your DELETE or by the retention window. `status` still describes the pipeline; this is why the artifacts went away."}}, "required": ["id", "status", "reference", "created_at"], "additionalProperties": false}}}}, "404": {"description": "`not_found`: No such track for this account. A track belonging to someone else answers exactly the same way, and so does one already deleted.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "401": {"description": "`invalid_api_key`: Missing, malformed, unknown, revoked or deactivated key. All four fail identically, so this is not a key-existence oracle.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "429": {"description": "`rate_limited`: Too many requests this minute. Retry-After says when to come back.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "500": {"description": "`internal_error`: Our fault. Retry, then tell us.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}}, "description": "\nOne track's current status, and its artifacts once it has them.\n\n`artifacts` is absent until `status` is `complete`, and it is present but\nempty for a track whose deletion has been claimed. `flagged_word_count`\nappears once analysis has run. A track belonging to another account answers\n`not_found`, exactly as an unknown id does.\n", "security": [{"ApiKeyAuth": []}]}, "delete": {"operationId": "api_api_v1_delete_track", "summary": "Delete a track", "parameters": [{"in": "path", "name": "track_id", "schema": {"title": "Track Id", "type": "string"}, "required": true}], "responses": {"202": {"description": "The deletion is claimed. The artifacts are removed within 48 hours.", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string"}, "status": {"type": "string", "enum": ["deleting"]}, "deletion_claimed_at": {"type": "string", "format": "date-time"}}, "required": ["id", "status", "deletion_claimed_at"]}}}}, "404": {"description": "`not_found`: No such track for this account. A track belonging to someone else answers exactly the same way, and so does one already deleted.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "409": {"description": "`deletion_needs_review`: The track cannot be deleted automatically: our own record of its stored objects is incomplete, and deleting on top of that would leave audio behind with nothing naming it. A human completes it.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "401": {"description": "`invalid_api_key`: Missing, malformed, unknown, revoked or deactivated key. All four fail identically, so this is not a key-existence oracle.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "429": {"description": "`rate_limited`: Too many requests this minute. Retry-After says when to come back.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "500": {"description": "`internal_error`: Our fault. Retry, then tell us.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}}, "description": "\nDelete one track and its audio, before the retention window would.\n\nThe decision is immediate and irreversible. New download requests are\nrefused at once; a download link issued before the deletion keeps working\nuntil it expires, at most 15 minutes later. Processing still in flight is\nstopped rather than finished.\n\nEvery live copy of the audio is removed within 48 hours, which is why this\nanswers `202` and not `204`. Usually it is the next daily pass; it waits one\nmore day only when the track was still being worked on when you deleted it,\nbecause we let work already under way finish rather than delete underneath\na file being written.\n\nBackups have their own deadline. A deleted track is never backed up again,\nand a backup copy made before the deletion expires within 30 days, the\nlimit every backup we keep is held to.\n\nIdempotent. Deleting a track that is already being deleted answers `202`\nagain with the original `deletion_claimed_at`, so a retry after a timeout\nis safe. Once the objects are gone the id stops resolving and you get\n`not_found`, which is the same answer an unknown id has always given.\n\nBilling is unaffected. A track that completed has already been priced, and\nthat usage row survives the deletion deliberately: deleting the audio must\nnot delete the invoice. A track deleted before it completed was never\npriced.\n\nA track whose stored artifacts are not fully recorded answers\n`deletion_needs_review` instead. That state means our own records disagree\nwith themselves, and deleting on top of it would leave audio behind with\nnothing naming it, so a human completes it.\n", "security": [{"ApiKeyAuth": []}]}}, "/api/v1/tracks/{track_id}/events": {"get": {"operationId": "api_api_v1_list_track_events", "summary": "List a track's events", "parameters": [{"in": "path", "name": "track_id", "schema": {"title": "Track Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "The delivery log, oldest first. Empty for a track submitted without a webhook_url.", "content": {"application/json": {"schema": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string", "examples": ["evt_7bK2mQ9xR4tL"]}, "type": {"type": "string", "enum": ["track.completed", "track.failed"]}, "state": {"type": "string", "enum": ["pending", "delivered", "dead", "superseded"], "description": "`superseded` means the event was retired from further attempts because the track later completed."}, "attempts": {"type": "integer"}, "url": {"type": "string"}, "payload": {"type": "object", "properties": {"id": {"type": "string", "examples": ["evt_7bK2mQ9xR4tL"]}, "type": {"type": "string", "enum": ["track.completed", "track.failed"]}, "created": {"type": "integer", "description": "Unix seconds, frozen when the event was created and identical on every retry. NOT the `t` in the signature header: that is regenerated per attempt, so the two differ on any delivery that is not instant. Verify against `t`, and use this only to order events."}, "data": {"type": "object", "properties": {"track_id": {"type": "string"}, "reference": {"type": ["string", "null"], "description": "Explicitly null when you sent none, never omitted."}, "status": {"type": "string", "enum": ["processing", "analyzed", "rendering", "complete", "failed"]}, "error": {"type": "object", "description": "Present on `track.failed` only.", "properties": {"code": {"type": "string", "enum": ["processing_failed"]}, "message": {"type": "string"}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["track_id", "reference", "status"], "additionalProperties": false}}, "required": ["id", "type", "created", "data"], "additionalProperties": false, "allOf": [{"if": {"properties": {"type": {"const": "track.failed"}}, "required": ["type"]}, "then": {"properties": {"data": {"required": ["track_id", "reference", "status", "error"]}}}, "else": {"properties": {"data": {"not": {"required": ["error"]}}}}}], "description": "The event body, as an object. Reproducing the exact signed bytes takes the full recipe: keys sorted, no spaces after the separators, and non-ASCII escaped as \\uXXXX (Python json.dumps defaults). A reference containing an accent serialised literally as UTF-8 will not match. Verifying the raw request body instead is simpler and cannot drift."}, "created_at": {"type": "string", "format": "date-time"}, "first_attempt_at": {"type": "string", "format": "date-time"}, "next_attempt_at": {"type": "string", "format": "date-time", "description": "Present only while more attempts are coming."}, "delivered_at": {"type": "string", "format": "date-time"}, "last_status_code": {"type": "integer", "description": "Your endpoint's response code."}, "last_error": {"type": "string", "description": "Your response preview, or a fixed transport category."}}, "required": ["id", "type", "state", "attempts", "url", "payload", "created_at"], "additionalProperties": false}}}}}, "404": {"description": "`not_found`: No such track for this account. A track belonging to someone else answers exactly the same way, and so does one already deleted.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "401": {"description": "`invalid_api_key`: Missing, malformed, unknown, revoked or deactivated key. All four fail identically, so this is not a key-existence oracle.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "429": {"description": "`rate_limited`: Too many requests this minute. Retry-After says when to come back.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "500": {"description": "`internal_error`: Our fault. Retry, then tell us.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}}, "description": "\nThe delivery log for this track's webhooks: what was sent, how many attempts\nit took, and what your endpoint answered.\n\nThis is a diagnostic for configured webhooks, NOT a way to follow a track's\nprogress. Events exist only for tracks submitted with a `webhook_url`, so a\ntrack without one has an empty log however far it gets. Poll\n`GET /tracks/{track_id}` for the lifecycle.\n", "security": [{"ApiKeyAuth": []}]}}, "/api/v1/tracks/{track_id}/lyrics": {"get": {"operationId": "api_api_v1_retrieve_track_lyrics", "summary": "Retrieve a track's lyrics", "parameters": [{"in": "path", "name": "track_id", "schema": {"title": "Track Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "The transcribed words.", "content": {"application/json": {"schema": {"type": "object", "properties": {"track_id": {"type": "string", "examples": ["trk_9dQ4vK2mR7xT1sPzYb3WgA"]}, "words": {"type": "array", "description": "Every transcribed word, in order.", "items": {"type": "object", "properties": {"text": {"type": "string"}, "start": {"type": "number", "description": "Seconds from the start of the audio, to the millisecond."}, "end": {"type": "number", "description": "Seconds from the start of the audio, to the millisecond."}, "flagged": {"type": "boolean", "description": "Selected for censorship. The clean version mutes each selected word plus about 50 ms on either side, so the muted span is slightly wider than start and end."}}, "required": ["text", "start", "end", "flagged"], "additionalProperties": false}}}, "required": ["track_id", "words"], "additionalProperties": false}}}}, "404": {"description": "`not_found`: No such track for this account. A track belonging to someone else answers exactly the same way, and so does one already deleted.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "409": {"description": "`not_ready`: The track has not reached that stage yet: downloads need it complete, lyrics need analysis finished.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "410": {"description": "`gone`: The track is being deleted and its audio is no longer available.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "401": {"description": "`invalid_api_key`: Missing, malformed, unknown, revoked or deactivated key. All four fail identically, so this is not a key-existence oracle.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "429": {"description": "`rate_limited`: Too many requests this minute. Retry-After says when to come back.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "500": {"description": "`internal_error`: Our fault. Retry, then tell us.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}}, "description": "\nThe words we transcribed, in order, each with its timing and whether it\nwas selected for censorship.\n\nAvailable from the moment rendering starts, so you can read them while the\ntrack is still `rendering`. That is later than analysis finishing: stem\nseparation runs in between, so expect the lyrics a few minutes after\nsubmission rather than seconds. Earlier than that answers `not_ready`, and\na track whose deletion has been claimed answers `gone`. The selection is\nfinal once served: nothing changes it after rendering has started.\n\nA `failed` track serves its lyrics too, as a diagnostic: they are what\nanalysis had selected when the track failed, whether or not rendering had\nstarted, and no clean version is available for it. A track that failed\nbefore analysis finished has no lyrics and answers `not_ready` for good;\ncheck `status` rather than waiting.\n\nTimes are seconds from the start of the audio, to the millisecond, and\nthey are the word's timing in the transcript, not the exact muted span.\nThe clean version mutes each selected word plus about 50 ms on either\nside, with a short crossfade, so a word right next to a selected one can\nlose its edge.\n\n`flagged` marks every selected occurrence, so a word that occurs three\ntimes is flagged three times. `flagged_word_count` on the track counts\nwhat analysis flagged and need not equal the number of flagged entries\nhere.\n", "security": [{"ApiKeyAuth": []}]}}, "/api/v1/usage": {"get": {"operationId": "api_api_v1_usage", "summary": "Usage and accrued cost", "parameters": [], "responses": {"200": {"description": "Usage for the current month, and everything uninvoiced.", "content": {"application/json": {"schema": {"type": "object", "properties": {"as_of": {"type": "string", "format": "date-time"}, "currency": {"type": "string"}, "period_start": {"type": "string", "format": "date-time"}, "period_end": {"type": "string", "format": "date-time"}, "period": {"type": "object", "properties": {"tracks": {"type": "integer"}, "amount_cents": {"type": "integer"}, "by_day": {"type": "array", "items": {"type": "object", "properties": {"date": {"type": "string", "format": "date"}, "tracks": {"type": "integer"}, "amount_cents": {"type": "integer"}}, "required": ["date", "tracks", "amount_cents"], "additionalProperties": false}}}, "required": ["tracks", "amount_cents", "by_day"], "additionalProperties": false}, "outstanding": {"type": "object", "properties": {"tracks": {"type": "integer"}, "amount_cents": {"type": "integer"}}, "required": ["tracks", "amount_cents"], "additionalProperties": false, "description": "Every completed track not yet invoiced, which can span earlier months."}, "trial_tracks_remaining": {"type": "integer", "minimum": 0, "description": "How many more completed tracks are free on this account. 0 for an account with no trial. Each completion uses one until it reaches 0."}}, "required": ["as_of", "currency", "period_start", "period_end", "period", "outstanding", "trial_tracks_remaining"], "additionalProperties": false}}}}, "401": {"description": "`invalid_api_key`: Missing, malformed, unknown, revoked or deactivated key. All four fail identically, so this is not a key-existence oracle.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "429": {"description": "`rate_limited`: Too many requests this minute. Retry-After says when to come back.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "500": {"description": "`internal_error`: Our fault. Retry, then tell us.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}}, "description": "\nThis calendar month's tracks and cost, plus everything uninvoiced.\n\n`period` covers the current month with a per-day breakdown; `outstanding` is\nevery completed track not yet on an invoice, which can span earlier months.\nAmounts are integer cents in `currency`. Priced at completion, so a track in\nflight is not counted yet.\n\nA trial account has a number of free tracks, shown as\n`trial_tracks_remaining`. They are used at completion, one per track, so a\ntrack that fails or that you delete before it finishes costs nothing and\nuses no credit. Free tracks still appear in `tracks` and in `by_day`, at an\namount of 0, so the counts always add up.\n", "security": [{"ApiKeyAuth": []}]}}, "/api/v1/tracks/{track_id}/download/{kind}": {"get": {"operationId": "api_api_v1_download_artifact", "summary": "Download an artifact", "parameters": [{"in": "path", "name": "track_id", "schema": {"title": "Track Id", "type": "string"}, "required": true}, {"in": "path", "name": "kind", "schema": {"title": "Kind", "type": "string"}, "required": true}], "responses": {"302": {"description": "Redirect to a short-lived signed URL.", "headers": {"Location": {"description": "The signed URL. Expires in minutes; do not store it.", "schema": {"type": "string", "format": "uri"}}}}, "404": {"description": "`not_found`: No such track for this account. A track belonging to someone else answers exactly the same way, and so does one already deleted.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "422": {"description": "`invalid_artifact_kind`: Unknown download kind. The kinds are clean_mp3, clean_flac and instrumental.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "409": {"description": "`not_ready`: The track has not reached that stage yet: downloads need it complete, lyrics need analysis finished.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "410": {"description": "`gone`: The track is being deleted and its audio is no longer available.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "401": {"description": "`invalid_api_key`: Missing, malformed, unknown, revoked or deactivated key. All four fail identically, so this is not a key-existence oracle.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "429": {"description": "`rate_limited`: Too many requests this minute. Retry-After says when to come back.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}, "500": {"description": "`internal_error`: Our fault. Retry, then tell us.", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string", "enum": ["bad_request", "invalid_api_key", "forbidden", "not_found", "method_not_allowed", "idempotency_conflict", "not_ready", "deletion_needs_review", "gone", "file_too_large", "file_required", "unsupported_media_type", "no_audio_stream", "invalid_artifact_kind", "invalid_webhook_url", "source_url_not_supported", "review_mode_not_available", "validation_error", "rate_limited", "too_many_in_flight", "internal_error"], "description": "Stable. Branch on this."}, "message": {"type": "string", "description": "For humans. May be reworded."}}, "required": ["code", "message"], "additionalProperties": false}}, "required": ["error"], "additionalProperties": false}}}}}, "description": "\nRedirects (302) to a short-lived signed URL for one artifact. Follow the\nredirect and do not store the URL you land on; it expires in minutes.\n\n`kind` is one of `clean_mp3`, `clean_flac`, `instrumental`.\n\nThree ways this says no, and they mean different things. A track still\nprocessing answers `not_ready`. A track whose deletion has been claimed\nanswers `gone`. A track already deleted, at the end of its\n180 day retention window, is simply\n`not_found`, the same as an id that never existed. Age alone does not\ndecide: a track past the window that the sweep has not reached yet still\ndownloads normally.\n", "security": [{"ApiKeyAuth": []}]}}}, "components": {"schemas": {}, "securitySchemes": {"ApiKeyAuth": {"type": "http", "scheme": "bearer"}}}, "servers": []}