{"openapi":"3.1.0","info":{"title":"Soundza API","version":"1.0.0","description":"Search and download free sound effects, ambience, music beds and samples.\nEvery call needs an API key sent as `Authorization: Bearer <key>`. Get one at https://soundza.com/developers/keys.\nFree keys get 60 searches a minute, 200 downloads an hour and 1000 a day. Every response carries X-RateLimit-* headers.\nGuidelines: https://soundza.com/developers#guidelines\n\nUse classes (the `use` filter):\n- TRANSITION: whooshes, swipes, swooshes between shots\n- IMPACT: cinematic hits, booms, slams, punches\n- RISER: risers, uplifters, downlifters, tension builds\n- UI: clicks, taps, toggles, pops, hovers\n- NOTIFICATION: chimes, pings, success and error tones\n- AMBIENCE: the sound of a place (room tone, street, forest, rain, crowd murmur)\n- PAD_DRONE: sustained tonal beds and drones\n- FOLEY: one everyday action (footsteps, door, keys, paper, pour, applause)\n- VOCAL: a voice as an effect (laughs, cheers, gasps, shouts)\n- STINGER: a short musical sting or logo reveal, about 2-6 s\n- MUSIC: a full mix usable as a background bed\n- GAME_SFX: pickups, power-ups, jumps, lasers, retro blips\n- INSTRUMENT_SAMPLE: material for making music (drum hits, one-shots, loops, stems, vocal chops)","termsOfService":"https://soundza.com/terms","contact":{"email":"admin@soundza.com","url":"https://soundza.com/developers"},"license":{"name":"Sounds: Soundza Standard License","url":"https://soundza.com/license"}},"externalDocs":{"description":"Developer docs","url":"https://soundza.com/developers"},"servers":[{"url":"https://api.soundza.com/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/sounds/search":{"get":{"operationId":"searchSounds","summary":"Search sounds","description":"Give a q, at least one filter, or both.","parameters":[{"name":"q","in":"query","description":"Words to match, e.g. \"door slam\" or \"lofi drum loop\". Typos are forgiven.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"use","in":"query","description":"The job the sound does (see Use classes). Case-insensitive.","schema":{"type":"string","enum":["TRANSITION","IMPACT","RISER","UI","NOTIFICATION","AMBIENCE","PAD_DRONE","FOLEY","VOCAL","STINGER","MUSIC","GAME_SFX","INSTRUMENT_SAMPLE"]}},{"name":"sample_type","in":"query","description":"The file's shape: ONE_SHOT, LOOP, TEXTURE, FX, VOCAL or BEAT.","schema":{"type":"string","enum":["ONE_SHOT","LOOP","TEXTURE","FX","VOCAL","BEAT"]}},{"name":"min_duration","in":"query","description":"Shortest length, in seconds.","schema":{"type":"number","exclusiveMinimum":0}},{"name":"max_duration","in":"query","description":"Longest length, in seconds.","schema":{"type":"number","exclusiveMinimum":0}},{"name":"min_bpm","in":"query","description":"Slowest tempo. Only music has a tempo.","schema":{"type":"number","exclusiveMinimum":0}},{"name":"max_bpm","in":"query","description":"Fastest tempo.","schema":{"type":"number","exclusiveMinimum":0}},{"name":"key","in":"query","description":"Musical key, e.g. \"C\", \"F# minor\" or \"Bbm\". Only music has a key.","schema":{"type":"string"}},{"name":"feel","in":"query","description":"Comma-separated feel words; sounds matching any of them come back, and more matches rank higher. One of: airy, heavy, metallic, bright, dark, punchy, soft, warm, glitchy, organic, cinematic, cartoony, retro.","schema":{"minItems":1,"maxItems":13,"type":"array","items":{"type":"string","enum":["airy","heavy","metallic","bright","dark","punchy","soft","warm","glitchy","organic","cinematic","cartoony","retro"]}},"style":"form","explode":false},{"name":"loop_seamless","in":"query","description":"true for loops that repeat without a click.","schema":{"type":"boolean"}},{"name":"ucs_category","in":"query","description":"A Universal Category System CatID (\"CRWDCheer\") or a top-level category (\"CROWDS\").","schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number, from 1.","schema":{"default":1,"type":"integer","minimum":1}},{"name":"per_page","in":"query","description":"Results per page: default 15, at most 50. Results stop at 500 per query.","schema":{"default":15,"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"A page of sounds.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"invalid_request: a parameter is wrong; `details` says which.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_key, invalid_key or revoked_key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: wait Retry-After seconds, or ask for higher limits.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds until the call would be allowed.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"server_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sounds/{id}":{"get":{"operationId":"getSound","summary":"Get one sound","parameters":[{"name":"id","in":"path","required":true,"description":"A sound's id (or its slug).","schema":{"type":"string"}}],"responses":{"200":{"description":"The sound.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sound"}}}},"400":{"description":"invalid_request: a parameter is wrong; `details` says which.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_key, invalid_key or revoked_key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no public sound has that id.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: wait Retry-After seconds, or ask for higher limits.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds until the call would be allowed.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"server_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sounds/{id}/file":{"get":{"operationId":"downloadSound","summary":"Download the full-quality file","description":"Answers with a 302 to a signed link that works for 5 minutes; follow it (`curl -L`). Call this each time a sound is added to a project. Counts toward the download limits.","parameters":[{"name":"id","in":"path","required":true,"description":"A sound's id (or its slug).","schema":{"type":"string"}},{"name":"search_id","in":"query","description":"The search_id of the search this sound came from.","schema":{"type":"string"}},{"name":"user","in":"query","description":"Your own id for the end user who added the sound, for your usage reports. Up to 200 characters.","schema":{"type":"string","maxLength":200}}],"responses":{"302":{"description":"Redirect to the file.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}},"Location":{"description":"A signed link to the file, valid 5 minutes.","schema":{"type":"string"}}}},"400":{"description":"invalid_request: a parameter is wrong; `details` says which.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_key, invalid_key or revoked_key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no public sound has that id.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: wait Retry-After seconds, or ask for higher limits.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds until the call would be allowed.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"server_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/removals":{"get":{"operationId":"listRemovals","summary":"Sounds removed since a date","description":"If you store downloaded files, delete any sound listed here. Check at least monthly. Oldest first, 5,000 per page.","parameters":[{"name":"since","in":"query","required":true,"description":"An ISO date or date-time, e.g. 2026-09-01.","schema":{"type":"string"}}],"responses":{"200":{"description":"Removed sound ids.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemovalsResponse"}}}},"400":{"description":"invalid_request: a parameter is wrong; `details` says which.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_key, invalid_key or revoked_key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: wait Retry-After seconds, or ask for higher limits.","headers":{"X-RateLimit-Limit":{"description":"The limit of the window that applies to this call.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Calls left in that window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the window reopens when blocked; otherwise the window's length (windows roll).","schema":{"type":"integer"}},"X-RateLimit-Policy":{"description":"Which window: searches_per_minute, downloads_per_hour or downloads_per_day.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds until the call would be allowed.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"server_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A Soundza API key, starting sz_live_."}},"schemas":{"Sound":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","description":"The sound's page on soundza.com."},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"use":{"anyOf":[{"type":"string","enum":["TRANSITION","IMPACT","RISER","UI","NOTIFICATION","AMBIENCE","PAD_DRONE","FOLEY","VOCAL","STINGER","MUSIC","GAME_SFX","INSTRUMENT_SAMPLE"]},{"type":"null"}],"description":"The job the sound does."},"sample_type":{"anyOf":[{"type":"string","enum":["ONE_SHOT","LOOP","TEXTURE","FX","VOCAL","BEAT"]},{"type":"null"}]},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Seconds."},"bpm":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Music only; null on sound effects by design."},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"e.g. \"F minor\". Music only."},"feel":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"sync_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Where the sound's main hit lands, in milliseconds from the start."},"lufs":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Integrated loudness."},"loop_seamless":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"file_type":{"type":"string","description":"MIME type of the full-quality file, usually audio/wav."},"sample_rate":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"bit_depth":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"channels":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"size_bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ucs_category":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false},{"type":"null"}],"description":"Sound effects only."},"creator":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","url"],"additionalProperties":false},{"type":"null"}]},"preview_files":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"bitrate":{"type":"number"},"link":{"type":"string"}},"required":["type","bitrate","link"],"additionalProperties":false},"description":"128 kbps MP3 previews on media.soundza.com. Play them straight from there; they need no key. Empty until a preview is made."},"download_url":{"type":"string","description":"Stable address of the full-quality file. Needs the key; answers with a 302 to a short-lived link."},"license":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false},"attribution":{"type":"string","description":"A ready-made credit line."}},"required":["id","url","title","description","use","sample_type","duration","bpm","key","feel","tags","sync_ms","lufs","loop_seamless","file_type","sample_rate","bit_depth","channels","size_bytes","ucs_category","creator","preview_files","download_url","license","attribution"],"additionalProperties":false},"SearchResponse":{"type":"object","properties":{"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"per_page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total_results":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Capped at 500."},"next_page":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The next page's full URL, or null on the last page."},"search_id":{"type":"string","description":"Pass it to download_url as ?search_id= to link a download to this search."},"sounds":{"type":"array","items":{"$ref":"#/components/schemas/Sound"}}},"required":["page","per_page","total_results","next_page","search_id","sounds"],"additionalProperties":false},"RemovalsResponse":{"type":"object","properties":{"since":{"type":"string"},"removals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"removed_at":{"type":"string"}},"required":["id","removed_at"],"additionalProperties":false}},"next_page":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Present when this page is full (5,000 rows); it continues from the last removed_at."}},"required":["since","removals","next_page"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["missing_key","invalid_key","revoked_key","invalid_request","not_found","rate_limited","server_error"]},"message":{"type":"string"},"details":{"description":"invalid_request only: which parameter is wrong and why.","type":"array","items":{"type":"object","properties":{"param":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"type":"string"}},"required":["param","message"],"additionalProperties":false}},"limit":{"description":"rate_limited only: the window that was hit.","type":"string"},"retry_after":{"description":"rate_limited only: seconds to wait.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"contact":{"description":"rate_limited only: where to ask for higher limits.","type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}