canonical: https://jentic.com/apis/freesound.org/freesound # Freesound Freesound is a collaborative database of Creative Commons audio samples used by musicians, sound designers, game developers, and researchers. The version 2 API exposes text search across the full sample library and a per-sound endpoint that returns metadata, tags, content-analysis features, preview URLs, and download links. The full Freesound API supports comments, ratings, similar-sound search, and uploads, but this spec focuses on the two endpoints that drive almost all read traffic. ## For AI agents Search the Freesound Creative Commons sample library by text and fetch metadata, previews, and download links for individual sounds. Authentication is an API token in the 'token' query parameter. ## Scope Does not handle music streaming, podcast hosting, or commercial-licensed track playback - use for searching and retrieving Creative Commons audio samples only. ## Capabilities - Search the Freesound library by free-text query via `/search/text` - Filter and sort results using Freesound's filter and sort syntax - Retrieve metadata for a single sound (name, description, tags, duration, license) via `/sounds/{soundId}` - Fetch low-quality preview URLs for in-app playback without downloading the full file - Get the high-quality original-file download URL for an authenticated user ## Use cases ### Sample Discovery for a DAW Plugin A digital-audio-workstation plugin lets producers search Freesound directly from inside the DAW. The plugin calls `/search/text` with the user's query plus filters for duration and license, then plays back previews fetched from `/sounds/{soundId}.` Producers can audition hundreds of samples without leaving their session. Example prompt: GET `/search/text`?query=thunderstorm&filter=duration:[0 TO 30]&token={token} and play the preview-hq-mp3 URL for the first result ### Game Audio Sourcing An indie game studio sources sound effects by searching Freesound for tagged Creative Commons clips that match the scene (footsteps on gravel, sci-fi door, ambient cave). The studio fetches previews to pre-screen, then downloads the original files for licensing-compliant inclusion in the game build. Example prompt: GET `/search/text`?query=footsteps gravel&filter=tag:loop&token={token}, then GET `/sounds/{soundId}` for each candidate to confirm license ### Acoustic Research Dataset Building Audio researchers assemble datasets by querying Freesound for specific acoustic phenomena (bird calls, urban traffic, machine noise) and pulling the metadata and content-analysis features. The two-endpoint flow is enough to build a labelled corpus when paired with the published license fields. Example prompt: Loop GET `/search/text` across each label term and persist the metadata returned from `/sounds/{soundId}` to the dataset manifest ### AI Agent Audio Briefing A creative AI agent gathers reference sounds for a brief by calling Freesound through Jentic, surfacing the top results with previews so a human can choose. The token is held in Jentic's vault and the agent only deals with structured search and sound objects. Example prompt: Search Jentic for 'find a sound effect on Freesound', execute `/search/text` with the user's query, and return the top three results with preview URLs ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/search/text` | Search the Freesound library by text query | | GET | `/sounds/{soundId}` | Retrieve metadata, previews, and downloads for a single sound | ## Key resources - **Search** — Text search across the Freesound sample library - **Sound** — Per-sound metadata, previews, downloads, and content-analysis features ## Why Jentic - **Setup:** Wiring Freesound by hand means passing your API token as a query parameter on every call and building the text-search filter syntax yourself against the www.freesound.org host. Through Jentic you install once, import Freesound from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Freesound here exposes only read operations, searching text and fetching a sound by id, so you limit the agent to the operations it needs, such as searching for a sample or retrieving one sound. You choose which of these it may call, and nothing outside that set runs. - **Credential handling:** Your Freesound token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find a sound effect on Freesound' or 'get details for a sound', and Jentic returns the matching `/search/text` or `/sounds/{soundId}` operation with its input schema so the agent calls the right endpoint without constructing the filter syntax from the reference docs. ## Related APIs - **SoundCloud** — SoundCloud hosts long-form music and podcasts rather than short Creative Commons samples - **Spotify** — Spotify Web API serves commercial music tracks rather than Creative Commons samples - **Pexels** — Pexels offers free Creative Commons photos and videos that pair with Freesound's audio ## FAQ ### What authentication does the Freesound API use? Freesound APIv2 takes an API token in the 'token' query parameter on every request. OAuth2 is also supported for write operations, but the search and per-sound read endpoints in this spec accept the token-based scheme. Through Jentic, the token is stored encrypted in the vault and replaced with a scoped execution token before the agent runs. ### Can I search the Freesound library by text with this API? Yes. GET `/search/text` with a query parameter returns paginated results matching the query, and Freesound's filter syntax lets you constrain by duration, tag, license, sample rate, and more. Each hit includes the sound ID and preview URLs for immediate playback. ### What are the rate limits for the Freesound API? Freesound applies per-token daily request quotas published in its developer documentation, typically 60 requests per minute and a few thousand requests per day for free accounts. Higher quotas are available on request for research and commercial use. ### How do I fetch a sound's metadata through Jentic? Search Jentic for 'get a Freesound sound by ID', load the `/sounds/{soundId}` schema, and execute it with the soundId integer. The response carries the sound's name, description, tags, license, preview URLs, and content-analysis features. ### Is the Freesound API free? Yes. Freesound is run by the Music Technology Group at Universitat Pompeu Fabra and the API is free to use within the published quotas. The audio content is Creative Commons, with each sample carrying its own specific license terms - check the license field before redistributing. ### How do I play back a sound without downloading the full file? Each sound returned by `/sounds/{soundId}` (and every search hit) includes preview URLs at high and low quality in MP3 and OGG formats. Stream the preview-hq-mp3 URL for an in-app audition, and only call the high-quality download endpoint when the user commits to using the sample. ### Can I limit what my agent is allowed to do with the Freesound API? Yes. Because you run Jentic One yourself, your own rules decide which Freesound operations and credentials the agent may use. This spec exposes only two read operations, searching the library with `/search/text` and fetching a single sound with `/sounds/{soundId}`, and you choose which of those the agent is allowed to call. Anything outside the set you permit does not run, so you can let an agent search for samples without ever granting it the per-sound fetch, or the reverse.