SFXMint Library API

openapi: 3.2.0
info:
  title: SFXMint Sound Effects Library API
  version: 1.0.0
  summary: Free CC0 sound effects for apps and games, no API key.
  description: 'JSON API for 9,700+ AI-generated CC0 sound effects: search by description, look up a sound by the event it is for, fetch a set for a whole app or game, and download WAV or MP3 files. The library needs no key or signup. Generating a sound the library lacks needs an API key from https://sfxmint.com/dashboard/keys. The same tools are an MCP server at https://sfxmint.com/mcp.'
  termsOfService: https://sfxmint.com/terms
  contact:
    name: SFXMint
    url: https://sfxmint.com/contact
    email: hello@sfxmint.com
  license:
    name: CC0-1.0 (the sounds)
    identifier: CC0-1.0
  x-logo:
    url: https://sfxmint.com/icon.png
servers:
- url: https://sfxmint.com
tags:
- name: Library
  description: Keyless library endpoints.
paths:
  /api/v1/search:
    get:
      tags:
      - Library
      operationId: searchSounds
      summary: Search sounds by description
      description: 'Keyword search over sound titles and tags, backed by a semantic layer. Constraints are applied before the limit. The default response is an array: sounds showing every word first (fit: full), then the closest ones that meet every condition but not every word (fit: closest, with missing_terms). response=structured returns parsed constraints, per-candidate checks, closest sounds, library_fit and diagnostics.'
      parameters:
      - name: q
        in: query
        required: false
        description: What the sound is, in plain words.
        schema:
          type: string
        example: coin pickup
      - name: category
        in: query
        required: false
        description: Library category slug.
        schema:
          type: string
        example: ui
      - name: limit
        in: query
        required: false
        description: Number of results.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
      - name: response
        in: query
        required: false
        description: structured for the detailed response object.
        schema:
          type: string
          enum:
          - legacy
          - structured
          default: legacy
      - name: max_duration_ms
        in: query
        required: false
        description: Longest the sound itself may be, in milliseconds (a longer file with near-silence after the sound qualifies).
        schema:
          type: number
          exclusiveMinimum: 0
        example: 1000
      - name: loop
        in: query
        required: false
        description: Only sounds made to loop (true) or only one-shots (false).
        schema:
          type: boolean
      - name: format
        in: query
        required: false
        description: Only sounds that have this file format.
        schema:
          type: string
          enum:
          - wav
          - mp3
          - ogg
      responses:
        '200':
          description: Matching sounds (an array), or the structured response.
          content:
            application/json:
              schema:
                oneOf:
                - type: array
                  items:
                    $ref: '#/components/schemas/SearchResult'
                - $ref: '#/components/schemas/StructuredSearch'
        '400':
          description: Invalid parameter values (invalid_parameters).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/sounds/{slug}:
    get:
      tags:
      - Library
      operationId: getSound
      summary: Get one sound
      parameters:
      - name: slug
        in: path
        required: true
        description: The sound's id.
        schema:
          type: string
        example: ui-click-30
      responses:
        '200':
          description: The sound's metadata and file URLs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoundDetail'
        '404':
          description: No such sound (not_found).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/roles:
    get:
      tags:
      - Library
      operationId: listRoles
      summary: List sound roles
      description: 'Every role: what a sound is for in an app, game or video (button-click, purchase-success, coin-pickup).'
      responses:
        '200':
          description: All roles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
  /api/v1/roles/{role}:
    get:
      tags:
      - Library
      operationId: getRoleSound
      summary: Get the default sound for a role
      description: One deterministic default sound for the role, with alternates. The role may be its id or an alias.
      parameters:
      - name: role
        in: path
        required: true
        description: Role id or alias.
        schema:
          type: string
        example: button-click
      - name: style
        in: query
        required: false
        description: balanced is the most typical variant; the others re-rank by measured acoustics.
        schema:
          type: string
          enum:
          - balanced
          - crisp
          - soft
          - spacious
          default: balanced
      - name: max_duration_ms
        in: query
        required: false
        description: Longest the sound itself may be, in milliseconds (a longer file with near-silence after the sound qualifies).
        schema:
          type: number
          exclusiveMinimum: 0
        example: 1000
      - name: loop
        in: query
        required: false
        description: Only sounds made to loop (true) or only one-shots (false).
        schema:
          type: boolean
      - name: format
        in: query
        required: false
        description: Only sounds that have this file format.
        schema:
          type: string
          enum:
          - wav
          - mp3
          - ogg
      responses:
        '200':
          description: The role's default sound.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleSound'
        '400':
          description: Invalid parameter values (invalid_parameters).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown role (not_found, with roles_url).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/sets:
    get:
      tags:
      - Library
      operationId: listSets
      summary: List sound sets
      description: 'Sound sets grouped by event and style: style kits, scenario kits and one-shot kits.'
      responses:
        '200':
          description: All sets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SetSummary'
  /api/v1/sets/{id}:
    get:
      tags:
      - Library
      operationId: getSoundSet
      summary: Get a sound set
      description: One sound per role with alternates, a role → URL map (urls, MP3) and download_urls in the chosen format; missing_roles lists events the set cannot fill.
      parameters:
      - name: id
        in: path
        required: true
        description: Set id.
        schema:
          type: string
          enum:
          - ui-crisp
          - ui-soft
          - ui-spacious
          - retro-game
          - chat-app
          - saas-app
          - checkout
          - learning
          - puzzle-game
          - platformer
          - horror-game
          - video-editing
          - smart-device
          - wellness
          - ai-coding-tool
          - acoustic-drum-kit
          - animal-calls
          - dungeon-traps
        example: platformer
      - name: format
        in: query
        required: false
        description: File format of download_urls.
        schema:
          type: string
          enum:
          - wav
          - mp3
          - ogg
          default: mp3
      responses:
        '200':
          description: The set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoundSet'
        '404':
          description: No such set (not_found).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /dl/{file}:
    get:
      tags:
      - Library
      operationId: downloadSound
      summary: Download a sound file
      description: Permanent, immutable, CORS-enabled audio URL, free to hotlink. Playing a file in a browser is never counted; downloads by scripts, the API and MCP are limited to 20 different sounds a day per network without an API key, 50 with a free account's key. Past the limit the answer is 429 download_limit with Retry-After. Never append query parameters.
      parameters:
      - name: file
        in: path
        required: true
        description: 'The sound''s id and format: <slug>.wav, <slug>.mp3 or <slug>.ogg (OGG for older sounds only).'
        schema:
          type: string
        example: ui-click-30.mp3
      responses:
        '200':
          description: The audio file.
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
            audio/wav:
              schema:
                type: string
                format: binary
            audio/ogg:
              schema:
                type: string
                format: binary
        '404':
          description: No such file.
        '429':
          description: The day's download allowance is used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadLimit'
components:
  schemas:
    RoleSound:
      type: object
      properties:
        role:
          type: string
        label:
          type: string
        aliases:
          type: array
          items:
            type: string
        audiences:
          type: array
          items:
            type: string
        style:
          type: string
          enum:
          - balanced
          - crisp
          - soft
          - spacious
        slug:
          type: string
        title:
          type: string
        duration_ms:
          type: integer
        audible_ms:
          type: integer
        loopable:
          type: boolean
        license:
          type: string
        acoustics:
          $ref: '#/components/schemas/Acoustics'
        format_metadata:
          type: object
        mp3_url:
          type: string
          format: uri
        wav_url:
          type: string
          format: uri
        ogg_url:
          type: string
          format: uri
          description: Sounds published before 2026-10-14.
        page_url:
          type: string
          format: uri
        alternates:
          type: array
          items:
            type: object
        family:
          type: string
        family_url:
          type: string
          format: uri
        url:
          type: string
          format: uri
    SoundDetail:
      type: object
      properties:
        slug:
          type: string
        title:
          type: string
        category:
          type: string
        tags:
          type: array
          items:
            type: string
        description:
          type: string
        duration_ms:
          type: integer
          description: Length of the file.
        loopable:
          type: boolean
          description: Legacy flag; use loop_status=prepared for a checked loop.
        loop_status:
          type: string
        license:
          type: string
          example: CC0-1.0
        acoustics:
          $ref: '#/components/schemas/Acoustics'
        format_metadata:
          type: object
          description: 'Per format (wav, mp3, ogg): sha256, bytes, duration_ms, sample_rate, channels, codec and decode checks.'
        mp3_url:
          type: string
          format: uri
        wav_url:
          type: string
          format: uri
        ogg_url:
          type: string
          format: uri
          description: Sounds published before 2026-10-14.
        page_url:
          type: string
          format: uri
        license_url:
          type: string
          format: uri
        peaks_url:
          type: string
          format: uri
        created_at:
          type: integer
    DownloadLimit:
      type: object
      properties:
        error:
          const: download_limit
        message:
          type: string
        limit:
          type: integer
        used:
          type: integer
        tier:
          type: string
        upgrade_url:
          type: string
          format: uri
    Acoustics:
      type:
      - object
      - 'null'
      description: 'Measured from the WAV; null when not measured. Numbers, not a judgement of how a sound suits its use: listen.'
      properties:
        onset_ms:
          type: number
          description: Silence before the sound starts.
        peak_ms:
          type: number
          description: The loudest sample, from the start of the file. Align this with an event.
        audible_ms:
          type: number
          description: First to last moment within 40 dB of the peak.
        attack_ms:
          type:
          - number
          - 'null'
          description: Rise from the sound's start to its loudest window; does not count silence before it.
        tail_ms:
          type:
          - number
          - 'null'
          description: Fall from the loudest window to -40 dB.
        centroid_hz:
          type:
          - number
          - 'null'
          description: Spectral brightness.
        peak_dbfs:
          type: number
        rms_dbfs:
          type: number
          description: Average level across the audible span.
        character:
          type: array
          items:
            type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        message:
          type: string
    StructuredSearch:
      type: object
      properties:
        request_id:
          type: string
        query:
          type: object
        constraints:
          type: object
        candidates:
          type: array
          items:
            type: object
        closest:
          type: array
          items:
            type: object
        near_matches:
          type: array
          items:
            type: object
        library_fit:
          type: string
          enum:
          - full
          - close
          - weak
          - none
        unverified_requirements:
          type: array
          items: {}
        diagnostics:
          type: object
    SearchResult:
      type: object
      properties:
        slug:
          type: string
        title:
          type: string
        category:
          type: string
        tags:
          type: array
          items:
            type: string
        description:
          type: string
        duration_ms:
          type: integer
          description: Length of the file.
        loopable:
          type: boolean
          description: Legacy flag; use loop_status=prepared for a checked loop.
        loop_status:
          type: string
        license:
          type: string
          example: CC0-1.0
        acoustics:
          $ref: '#/components/schemas/Acoustics'
        format_metadata:
          type: object
          description: 'Per format (wav, mp3, ogg): sha256, bytes, duration_ms, sample_rate, channels, codec and decode checks.'
        mp3_url:
          type: string
          format: uri
        wav_url:
          type: string
          format: uri
        ogg_url:
          type: string
          format: uri
          description: Sounds published before 2026-10-14.
        page_url:
          type: string
          format: uri
        fit:
          type: string
          enum:
          - full
          - closest
        missing_terms:
          type: array
          items:
            type: string
        audible_ms:
          type: integer
          description: Length of the sound itself.
        score:
          type: number
          description: Ranking signal, not a probability.
        match:
          type: string
    SetSummary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        tagline:
          type: string
        use_for:
          type: string
        style:
          type: string
        roles:
          type: array
          items:
            type: string
        url:
          type: string
          format: uri
        page_url:
          type: string
          format: uri
    SoundSet:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        tagline:
          type: string
        use_for:
          type: string
        style:
          type: string
        format:
          type: string
          enum:
          - wav
          - mp3
          - ogg
        license:
          type: string
        page_url:
          type: string
          format: uri
        sounds:
          type: object
          additionalProperties:
            type: object
          description: Role → the role's sound, with alternates.
        urls:
          type: object
          additionalProperties:
            type: string
            format: uri
          description: Role → MP3 URL.
        download_urls:
          type: object
          additionalProperties:
            type: string
            format: uri
          description: Role → URL in the chosen format.
        missing_roles:
          type: array
          items:
            type: string
    Role:
      type: object
      properties:
        role:
          type: string
        label:
          type: string
        aliases:
          type: array
          items:
            type: string
        families:
          type: array
          items:
            type: string
        audiences:
          type: array
          items:
            type: string
        url:
          type: string
          format: uri
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: An SFXMint API key (sfx_live_…). X-API-Key is accepted too.
externalDocs:
  description: API documentation
  url: https://sfxmint.com/api/docs