Sound Server API reference
One search API for free music samples: drums, 808s, loops, vocals, FX, foley and instruments, with licence verdicts. Version 0.1.0, base URL https://sound.shep.bot. Machine-readable:OpenAPI 3.1 JSON. Want to send requests from the browser? Open theinteractive API playground.
- Authentication: none on the public server. Self-hosted servers may require
Authorization: Bearer <key>orx-api-key. - Rate limits: 120 requests per minute per client, announced in
RateLimit-Policy/RateLimitheaders;429comes withRetry-After. See versioning & rate limits. - Errors: JSON
{ "error": "message" }with a 4xx/5xx status.
Search
Find samples across every source in one call.
GET
/v1/searchSearch every sourceFans out to every enabled source in parallel (each with its own timeout), then merges and ranks. Words like 140 bpm, F minor or one shot in q become filters (see filters in the response); explicit parameters win. Unknown BPM, key, form or duration stay in the list, ranked below known matches, unless strict=true. A slow or failing source never fails the search: it shows up in providers with its status.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| q | query | string | Short query, written like a producer would. |
| category | query | string | Comma-separated categories; a parent includes its children. Top level: drums, bass, vocals, fx, foley, ambience, keys, guitar, synth, strings, brass, woodwind, mallets, other; children like drums.kick, bass.808, vocals.chop, fx.riser. |
| form | query | string | Comma-separated forms: one-shot, loop, phrase, multisample, pack, midi, preset. |
| bpm | query | string | Tempo or range: "140" or "120-128". |
| key | query | string | Musical key: "F minor", "F#m", "Eb", "A major". |
| min_duration | query | number | Minimum length in seconds. |
| max_duration | query | number | Maximum length in seconds (e.g. 2 for one-shots). |
| commercial | query | boolean | Only samples whose licence verdict is yes or yes-with-credit. |
| free | query | boolean | Only free samples. |
| downloadable | query | boolean | Only samples this server can download directly. |
| strict | query | boolean | Drop samples whose BPM, key, form or duration is unknown when that filter is set. |
| providers | query | string | Comma-separated source ids (see /v1/providers). |
| limit | query | integer | Max results (default 24). |
| offset | query | integer | Per-source offset for paging (e.g. 24 for page 2). |
| x-freesound-token | header | string | Optional: your own Freesound OAuth2 access token. Freesound serves its original WAV/AIFF/FLAC files only to a logged-in user, so without it Freesound samples download as their high-quality MP3/OGG preview. The token is passed to Freesound for this request only and is never logged or stored. |
Responses
200Ranked results, the filters in force and a per-source report.SearchResponseheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset400Invalid parameters or unknown source id.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset401API key required (self-hosted servers only).Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl "https://sound.shep.bot/v1/search?category=drums.kick&form=one-shot&bpm=140&key=F%20minor&providers=freesound%2Cwikimedia"Samples
Details, previews, file selection and downloads for one sample.
GET
/v1/samples/{id}Sample details with filesFull metadata, the licence with its verdict and credit line, the preview and every file for one sample.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id * | path | string | Sample id <provider>:<nativeId>, URL-encoded (: may stay as is). Take it from a search result. |
| x-freesound-token | header | string | Optional: your own Freesound OAuth2 access token. Freesound serves its original WAV/AIFF/FLAC files only to a logged-in user, so without it Freesound samples download as their high-quality MP3/OGG preview. The token is passed to Freesound for this request only and is never logged or stored. |
Responses
200The sample and its files.SampleDetailsheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset400Malformed id or unknown source.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset404Unknown sample.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy501The source has no detail pages here; openurlon the source site.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset502The source site failed.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
Example
curl "https://sound.shep.bot/v1/samples/freesound:2086"GET
/v1/samples/{id}/filesPick the right filesThe best file for a format and role (the original WAV by default), or every file with all=true, with sizes and the licence.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id * | path | string | Sample id <provider>:<nativeId>, URL-encoded (: may stay as is). Take it from a search result. |
| format | query | string | Preferred file format. The closest match wins; omitted = the best quality available (WAV, then AIFF, FLAC, OGG, MP3). |
| role | query | "original" | "preview" | "pack" | "stem" | "midi" | Which kind of file: the original upload, the preview, a pack archive, a stem or midi part of a construction kit. |
| all | query | boolean | Every file instead of the best single one. |
| x-freesound-token | header | string | Optional: your own Freesound OAuth2 access token. Freesound serves its original WAV/AIFF/FLAC files only to a logged-in user, so without it Freesound samples download as their high-quality MP3/OGG preview. The token is passed to Freesound for this request only and is never logged or stored. |
Responses
200Selected files and total size.FileSelectionheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset404Unknown sample.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl "https://sound.shep.bot/v1/samples/freesound:2086/files?format=wav"GET
/v1/samples/{id}/downloadDownloadOne plain file redirects (302) to the source, so the bytes never pass through this server. Several files, files the source only serves with extra request headers, or bundle=true stream as one zip with ATTRIBUTION.md and credits.json next to the audio. X-License and X-Attribution carry the licence on both. Samples that are only available on the source site (an account, a purchase, a login wall) answer 409 with the page url.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id * | path | string | Sample id <provider>:<nativeId>, URL-encoded (: may stay as is). Take it from a search result. |
| format | query | string | Preferred file format. The closest match wins; omitted = the best quality available (WAV, then AIFF, FLAC, OGG, MP3). |
| role | query | "original" | "preview" | "pack" | "stem" | "midi" | Which kind of file: the original upload, the preview, a pack archive, a stem or midi part of a construction kit. |
| all | query | boolean | Every file instead of the best single one. |
| bundle | query | boolean | Always answer with a zip that includes ATTRIBUTION.md and credits.json. |
| x-freesound-token | header | string | Optional: your own Freesound OAuth2 access token. Freesound serves its original WAV/AIFF/FLAC files only to a logged-in user, so without it Freesound samples download as their high-quality MP3/OGG preview. The token is passed to Freesound for this request only and is never logged or stored. |
Responses
200Zip bundle with the files, ATTRIBUTION.md and credits.json.string (binary)headers: X-License, X-Attribution, RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset302Redirect to the single file on the source.headers: X-License, X-Attribution, RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset404Unknown sample or no file matches the format/role.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset409No direct download here; get the file from the source page (url).Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl -L -O "https://sound.shep.bot/v1/samples/freesound:2086/download?format=wav"GET
/v1/samples/{id}/previewPlay the previewRedirects (302) to the sample's preview. Previews the source only serves with a Referer, and any preview with proxy=1, are streamed through this server with Access-Control-Allow-Origin: *, so browser players, Strudel and web DAWs can load them. Previews only, at most 25 MB: this is not a general proxy.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id * | path | string | Sample id <provider>:<nativeId>, URL-encoded (: may stay as is). Take it from a search result. |
| proxy | query | boolean | Stream the preview through this server (CORS enabled) instead of redirecting. |
| x-freesound-token | header | string | Optional: your own Freesound OAuth2 access token. Freesound serves its original WAV/AIFF/FLAC files only to a logged-in user, so without it Freesound samples download as their high-quality MP3/OGG preview. The token is passed to Freesound for this request only and is never logged or stored. |
Responses
200The preview audio.string (binary)headers: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset302Redirect to the preview on the source.headers: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset404Unknown sample, or it has no preview.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset413Preview too large to proxy.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl "https://sound.shep.bot/v1/samples/freesound:2086/preview"GET
/v1/samples/{id}/peaksWaveform peaksMin/max pairs (-1..1) for drawing the sample's waveform, computed from its preview and cached. Pass them to wavesurfer.js as peaks with duration.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id * | path | string | Sample id <provider>:<nativeId>, URL-encoded (: may stay as is). Take it from a search result. |
| points | query | integer | Number of min/max pairs (50–4000, default 800). |
Responses
200Peaks.objectheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset404Unknown sample, or no audio file to analyse.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl "https://sound.shep.bot/v1/samples/freesound:2086/peaks"GET
/v1/samples/{id}/similarSounds like this oneNearest sounds by audio embedding (CLAP) among the samples this server has indexed, when embeddings are turned on; otherwise Freesound's own similarity for freesound: ids. method says which was used.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id * | path | string | Sample id <provider>:<nativeId>, URL-encoded (: may stay as is). Take it from a search result. |
| limit | query | integer | Max results (default 12, max 30). |
Responses
200Similar samples.objectheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset404Unknown sample.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy501Embeddings are off on this server and the sample is not from Freesound.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
Example
curl "https://sound.shep.bot/v1/samples/freesound:2086/similar"GET
/v1/samples/{id}/midiMIDI from a melodic sampleTranscribes a melodic sample (bass line, lead, arpeggio, vocal line) one note at a time and returns a Standard MIDI File, or the notes as JSON with format=json. Notes snap to the grid when the tempo is known (bpm, or the sample's own). Chords and drums are not transcribed; a warning says so.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| id * | path | string | Sample id <provider>:<nativeId>, URL-encoded (: may stay as is). Take it from a search result. |
| bpm | query | number | Tempo of the loop (40–300). |
| quantize | query | string | Steps per beat: 1, 2, 4 (16ths, default) or 8; false keeps the played timing. |
| format | query | "json" | json for the notes instead of the file. |
Responses
200The MIDI file, or the notes.string (binary)headers: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset400Invalid bpm or quantize.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset404Unknown sample.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl "https://sound.shep.bot/v1/samples/freesound:2086/midi"Kits
Assemble a matching drum kit in one call.
POST
/v1/kitsBuild a drum kitOne search per slot (default kick, snare, clap, closed hat, open hat, 808), steered by style, bpm and key, returning the best pick per slot with alternatives and the reason it won. Commercial-safe picks only unless commercialOnly: false. The response includes a Strudel sample map and snippet that play the picks through this server's preview proxy, a General MIDI / SFZ drum map, how many picks fall under each licence verdict, and the credit lines.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| x-freesound-token | header | string | Optional: your own Freesound OAuth2 access token. Freesound serves its original WAV/AIFF/FLAC files only to a logged-in user, so without it Freesound samples download as their high-quality MP3/OGG preview. The token is passed to Freesound for this request only and is never logged or stored. |
Responses
200The kit plan.Kitheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset400Invalid body (e.g. an unreadable key).Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl -X POST "https://sound.shep.bot/v1/kits" \
-H "content-type: application/json" -H "accept: application/json, text/event-stream" \
-d '{}'Sources
The sample sites this server searches, what they hold, and how the server is used.
GET
/v1/providersList sourcesEvery sample site with the categories it carries, pricing, licence, the filters it applies itself and whether files can be downloaded directly.
Responses
200Sources.objectheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl "https://sound.shep.bot/v1/providers"GET
/v1/catalogCatalog censusHow many samples every source holds, counted once a day: listings per source, by top-level category, licence and the source's own categories, free counts, listings added in the last 30 days, and highlights such as the most downloaded sample. atLeast: true marks lower bounds (sources that cap their counts). Sources whose count failed today keep their last good numbers with stale. The same file is at /catalog.json; one point per day is in /catalog-history.json.
Responses
200Catalog census.Catalogheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset404The census has not been built on this server.Errorheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl "https://sound.shep.bot/v1/catalog"GET
/v1/statsUsage statisticsAggregate usage of this server: searches by surface (web, API, MCP), downloads, MCP tool calls, the client families and categories searched most, and per-source health (success rate, p50/p95 latency). Counts come from Prometheus (source: prometheus, last 24 hours and 7 days) or, when it is unavailable, from this process since it started (source: process). No queries, IPs or user agents are exposed. Cached for 60 seconds.
Responses
200Usage statistics.Statsheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl "https://sound.shep.bot/v1/stats"MCP
Model Context Protocol endpoint for AI agents.
POST
/mcpMCP endpoint (Streamable HTTP)Stateless Model Context Protocol endpoint for AI agents. Tools: search_samples, get_sample, build_kit, find_similar, list_sources (and download_sample on local installs, which saves files with their credits). Point any MCP client at this URL; see /docs/mcp for per-client setup.
Responses
200JSON-RPC 2.0 response.objectheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl -X POST "https://sound.shep.bot/mcp" \
-H "content-type: application/json" -H "accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_samples","arguments":{"query":"punchy kick","categories":["drums.kick"],"commercial_only":true}}}'System
Health and machine-readable descriptions.
GET
/v1/embeddingsEmbedding index statusWhether audio embeddings are on, the model, how many samples are indexed and the indexing queue.
Responses
200Status.objectheaders: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset429Rate limit exceeded. WaitRetry-Afterseconds.Errorheaders: Retry-After, RateLimit, RateLimit-Policy
Example
curl "https://sound.shep.bot/v1/embeddings"GET
/healthHealth checkResponses
200OKobject
Example
curl "https://sound.shep.bot/health"GET
/openapi.jsonThis OpenAPI documentResponses
200OpenAPI 3.1object
Example
curl "https://sound.shep.bot/openapi.json"Schemas
Category
One of: drums, drums.kick, drums.snare, drums.clap, drums.hat, drums.hat.closed, drums.hat.open, drums.cymbal, drums.cymbal.crash, drums.cymbal.ride, drums.tom, drums.perc, drums.fill, drums.break, bass, bass.808, bass.sub, vocals, vocals.acapella, vocals.chop, vocals.shout, vocals.spoken, vocals.choir, fx, fx.riser, fx.downlifter, fx.impact, fx.sweep, fx.zap, fx.noise, fx.glitch, fx.transition, foley, ambience, keys, guitar, synth, synth.pad, synth.lead, synth.pluck, synth.stab, strings, brass, woodwind, mallets, other
SampleForm
One of: one-shot, loop, phrase, multisample, pack, midi, preset
CommercialVerdict
One of: yes, yes-with-credit, restricted, clearance-required, check-terms, no
NativeFilter
One of: categories, forms, bpm, key, duration, commercialOnly, freeOnly
MusicalKey
| tonic * | "C" | "C#" | "D" | "D#" | "E" | "F" | "F#" | "G" | "G#" | "A" | "A#" | "B" | |
| mode * | "major" | "minor" |
License
| id * | string | SPDX id where one exists (CC0-1.0, CC-BY-4.0, CC-BY-NC-4.0…), else LicenseRef-*. |
| name * | string | |
| url | string (uri) | |
| commercialUse | boolean | |
| attributionRequired | boolean | |
| shareAlike | boolean | |
| redistribution | boolean | May the sample itself be passed on (in a pack, repo or dataset)? Almost always false. |
| assertedBy * | "source" | "site" | "uploader" | source: recorded per item by the site; site: one licence for the whole site; uploader: claimed by an anonymous uploader and not verified (capped at check-terms). |
| verdict * | CommercialVerdict | |
| note | string | One line on why the verdict is what it is. |
Price
| free * | boolean | |
| amount | number | |
| currency | string |
Sample
| id * | string | Globally unique <provider>:<nativeId>. |
| provider * | string | |
| nativeId * | string | |
| title * | string | |
| description | string | |
| url * | string (uri) | The sample's page on the source site. |
| author | string | |
| authorUrl | string (uri) | |
| tags * | string[] | |
| genres | string[] | |
| category * | Category | |
| categoryEvidence | object | How the category was decided: by the source, the file name, word rules or a model, and how sure (0..1). |
| form | SampleForm | |
| unit * | "sample" | "pack" | "instrument" | One sound, a pack of many, or a playable instrument. |
| packSize | integer | Number of sounds when unit is pack or instrument. |
| bpm | number | |
| key | MusicalKey | |
| rootNote | integer | MIDI note of a pitched one-shot (60 = C4). |
| durationSec | number | |
| sampleRate | integer | |
| bitDepth | integer | |
| channels | integer | |
| loudnessLufs | number | |
| previewUrl | string (uri) | Always-playable lower quality file (MP3/OGG) for auditioning. |
| previewNeedsReferer | boolean | Play it through /v1/samples/{id}/preview instead of previewUrl. |
| thumbnailUrl | string (uri) | Pack artwork or a waveform image. |
| formats | string[] | Known file formats: wav, aiff, flac, ogg, mp3, mid, zip… |
| license | License | |
| attribution | string | Ready-to-paste credit line, when the licence asks for one. |
| price | Price | |
| requiresAccount | boolean | The full-quality file needs an account on the source site (e.g. Freesound originals). |
| downloadable * | boolean | True when this server can fetch the files directly. |
| createdAt | string | |
| popularity | integer | Downloads or plays on the source, when published. |
| sameAs | string[] | Ids of the same sound on other sources. |
| score | number | Relevance 0..1 assigned by the ranker. |
SampleFile
| url * | string (uri) | |
| filename * | string | |
| format * | string | Lowercase extension: wav, aiff, flac, ogg, mp3, zip, mid… |
| role * | "original" | "preview" | "pack" | "stem" | "midi" | |
| sampleRate | integer | |
| bitDepth | integer | |
| channels | integer | |
| sizeBytes | integer | |
| requiresAuth | boolean | Needs a login, a purchase or your own token on the source site. |
SampleDetails
Sample & object
SampleFilters
| categories | Category[] | |
| forms | SampleForm[] | |
| bpm | object | |
| key | object | |
| maxDurationSec | number | |
| minDurationSec | number | |
| commercialOnly | boolean | |
| freeOnly | boolean |
ProviderSearchReport
| provider * | string | |
| name * | string | |
| status * | "ok" | "error" | "timeout" | "skipped" | "link" | link = the site forbids or blocks automated access; use searchUrl to run the same search there. skipped says why in error. |
| count * | integer | |
| total | integer | Total hits the source reported. |
| searchUrl | string (uri) | The same search on the source website. |
| error | string | |
| filteredLocally | NativeFilter[] | Filters this source could not apply itself; the server applied them to the page it returned, so it may hold fewer results than limit. |
| tookMs * | integer |
SearchResponse
| query * | string | The free text left after BPM, key and form words were parsed out. |
| filters * | SampleFilters | |
| results * | Sample[] | Merged and ranked; a sound mirrored by several sources appears once. |
| providers * | ProviderSearchReport[] | One status line per source. |
Provider
| id * | string | |
| name * | string | |
| homepage * | string (uri) | |
| description * | string | |
| categories * | Category[] | Top-level categories the source carries. |
| forms | SampleForm[] | Forms it carries; absent = any. |
| access * | "api" | "static" | "scrape" | "link" | api official API; static a curated manifest filtered locally; scrape public pages; link deep links only (the site forbids or blocks automated access). |
| pricing * | "free" | "freemium" | "paid" | |
| license | License | |
| apiKeyEnv | string | Environment variable holding the source's API key on a self-hosted server. |
| supportsDownload * | boolean | |
| nativeFilters | NativeFilter[] | Filters the source applies itself; the rest are applied locally. |
| enabled | boolean |
FileSelection
| id * | string | |
| license | License | |
| attribution | string | |
| totalBytes | integer | |
| files * | SampleFile[] |
KitRequest
| style | string | Genre or character words added to every slot's search. |
| slots | string[] | Slot names: category ids (drums.kick), short ids (hat.closed) or words (crash, perc, riser, vocal chop). Default: kick, snare, clap, hat.closed, hat.open, 808. |
| bpm | number | |
| key | string | Key for pitched slots (808, bass, synth), e.g. "F minor" or "F#m". |
| commercialOnly | boolean | Only picks whose verdict is yes or yes-with-credit. |
| providers | string[] | |
| perSlot | integer | Alternatives per slot. |
KitSample
| id * | string | |
| title * | string | |
| category * | Category | |
| form | SampleForm | |
| duration | number | Seconds. |
| key | string | |
| source * | string | Provider id. |
| url * | string (uri) | |
| preview | string (uri) | Playable URL (through this server's CORS-enabled preview proxy). |
| license * | string | Licence name and verdict label. |
| verdict * | CommercialVerdict | |
| attribution | string |
KitSlot
| slot * | string | |
| category * | Category | |
| pick | KitSample | |
| alternatives * | KitSample[] | |
| reason * | string | Why this pick won, or why the slot is empty. |
Kit
| name * | string | Short kit id (from the style); also the Strudel bank name. |
| style | string | |
| bpm | number | |
| key | string | |
| slots * | KitSlot[] | |
| warnings | string[] | |
| licences * | object | Number of picks per licence verdict. |
| creditsNeeded * | boolean | True when any pick must be credited. |
| credits | string[] | The credit lines to publish with your track. |
| strudel | object | |
| gm | object | General MIDI drum mapping (kick 36, snare 38, clap 39, closed hat 42, open hat 46, 808 on 35) and an SFZ file for any SFZ sampler. |
CountWithBound
| count * | integer | |
| atLeast | boolean | The count is a lower bound. |
SourceCensus
| id * | string | |
| name * | string | |
| homepage * | string (uri) | |
| license | string | The source's single licence id, when uniform. |
| pricing | "free" | "freemium" | "paid" | |
| supportsDownload | boolean | |
| total * | integer | Listings on the source (free and paid). |
| atLeast | boolean | |
| free | integer | |
| byCategory * | object | Listings per top-level category; each listing counts once. |
| byLicense | object | |
| categories | object | The source's own categories or tags (may overlap). |
| unit | "samples" | "packs" | |
| addedLast30Days | integer | |
| downloads | integer | Total downloads, when the source publishes them. |
| highlights | object[] | |
| method * | string | How the source was counted. |
| countedAt * | string (date-time) | |
| stale | object |
Catalog
| countedAt * | string (date-time) | |
| totals * | object | |
| byCategory * | object | Listings per top-level category across sources. |
| byLicense * | object | |
| sources * | SourceCensus[] | |
| linked | object[] |
UsageWindow
| key * | string | 24h, 7d, or process (since the last restart). |
| label * | string | |
| searches * | integer | |
| searchesWithResults * | integer | |
| bySurface * | object | |
| sampleViews * | integer | |
| downloads * | integer | |
| toolCalls * | integer | MCP tool calls. |
| pageViews * | integer | Website pages served. |
Ranked
| name * | string | |
| count * | integer |
ProviderHealth
| provider * | string | |
| requests * | integer | Searches that reached the source. |
| ok * | integer | |
| errors * | integer | |
| timeouts * | integer | |
| okRate * | number | null | |
| p50Ms * | integer | null | |
| p95Ms * | integer | null |
Stats
| generatedAt * | string (date-time) | |
| source * | "prometheus" | "process" | |
| since | string (date-time) | Start of counting for source: process. |
| windows * | UsageWindow[] | |
| breakdownLabel * | string | Period covered by clients, tools and assetTypes. |
| clients * | Ranked[] | Searches by client family (claude-code, cursor, browser, curl…). |
| tools * | Ranked[] | MCP tool calls by tool. |
| assetTypes * | Ranked[] | Searches by category filter (any = no filter). |
| providers * | ProviderHealth[] | Per-source health over the last 24 hours. |
| catalog * | object |
Error
| error * | string | |
| url | string (uri) | The sample's page on the source, when the file must be fetched there. |
| requiresAccount | boolean | |
| retryAfter | integer |
AI agent? This page is also available as markdown.