Shutterstock API Reference — audio

naftiko: 1.0.0-alpha2
info:
  label: Shutterstock API Reference — audio
  description: 'Shutterstock API Reference — audio. 17 operations. Lead operation: List audio tracks. Self-contained Naftiko
    capability covering one Shutterstock business surface.'
  tags:
  - Shutterstock
  - audio
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    SHUTTERSTOCK_API_KEY: SHUTTERSTOCK_API_KEY
capability:
  consumes:
  - type: http
    namespace: shutterstock-audio
    baseUri: https://api.shutterstock.com
    description: Shutterstock API Reference — audio business capability. Self-contained, no shared references.
    resources:
    - name: v2-audio
      path: /v2/audio
      operations:
      - name: gettracklist
        method: GET
        description: List audio tracks
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: query
          type: array
          description: One or more audio IDs
          required: true
        - name: view
          in: query
          type: string
          description: Amount of detail to render in the response
    - name: v2-audio-collections
      path: /v2/audio/collections
      operations:
      - name: createsoundbox
        method: POST
        description: Create audio collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: getsoundboxlist
        method: GET
        description: List audio collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: page
          in: query
          type: integer
          description: Page number
        - name: per_page
          in: query
          type: integer
          description: Number of results per page
    - name: v2-audio-collections-id
      path: /v2/audio/collections/{id}
      operations:
      - name: getsoundbox
        method: GET
        description: Get the details of audio collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
      - name: renamesoundbox
        method: POST
        description: Rename audio collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: deletesoundbox
        method: DELETE
        description: Delete audio collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
    - name: v2-audio-collections-id-items
      path: /v2/audio/collections/{id}/items
      operations:
      - name: addsoundboxitems
        method: POST
        description: Add audio tracks to collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: getsoundboxitems
        method: GET
        description: Get the contents of audio collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
        - name: page
          in: query
          type: integer
          description: Page number
        - name: per_page
          in: query
          type: integer
          description: Number of results per page
        - name: sort
          in: query
          type: string
          description: Sort order
      - name: deletesoundboxitems
        method: DELETE
        description: Remove audio tracks from collections
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Collection ID
          required: true
        - name: item_id
          in: query
          type: array
          description: One or more item IDs to remove from the collection
    - name: v2-audio-genres
      path: /v2/audio/genres
      operations:
      - name: getgenres
        method: GET
        description: List audio genres
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v2-audio-instruments
      path: /v2/audio/instruments
      operations:
      - name: getinstruments
        method: GET
        description: List audio instruments
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v2-audio-licenses
      path: /v2/audio/licenses
      operations:
      - name: licensetrack
        method: POST
        description: License audio tracks
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: license
          in: query
          type: string
          description: License type
        - name: search_id
          in: query
          type: string
          description: The ID of the search that led to licensing this track
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: getaudiolicenselist
        method: GET
        description: List audio licenses
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: audio_id
          in: query
          type: string
          description: Show licenses for the specified track ID
    - name: v2-audio-licenses-id-downloads
      path: /v2/audio/licenses/{id}/downloads
      operations:
      - name: downloadtracks
        method: POST
        description: Download audio tracks
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: License ID
          required: true
    - name: v2-audio-moods
      path: /v2/audio/moods
      operations:
      - name: getmoods
        method: GET
        description: List audio moods
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v2-audio-search
      path: /v2/audio/search
      operations:
      - name: searchaudio
        method: GET
        description: Search for tracks
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: artists
          in: query
          type: array
          description: Show tracks with one of the specified artist names or IDs
        - name: bpm
          in: query
          type: integer
          description: (Deprecated; use bpm_from and bpm_to instead) Show tracks with the specified beats per minute
        - name: bpm_from
          in: query
          type: integer
          description: Show tracks with the specified beats per minute or faster
        - name: bpm_to
          in: query
          type: integer
          description: Show tracks with the specified beats per minute or slower
        - name: duration
          in: query
          type: integer
          description: Show tracks with the specified duration in seconds
        - name: duration_from
          in: query
          type: integer
          description: Show tracks with the specified duration or longer in seconds
        - name: duration_to
          in: query
          type: integer
          description: Show tracks with the specified duration or shorter in seconds
        - name: genre
          in: query
          type: array
          description: Show tracks with each of the specified genres; to get the list of genres, use `GET /v2/audio/genres`
        - name: is_instrumental
          in: query
          type: boolean
          description: Show instrumental music only
        - name: instruments
          in: query
          type: array
          description: Show tracks with each of the specified instruments; to get the list of instruments, use `GET /v2/audio/instruments`
        - name: moods
          in: query
          type: array
          description: Show tracks with each of the specified moods; to get the list of moods, use `GET /v2/audio/moods`
        - name: page
          in: query
          type: integer
          description: Page number
        - name: per_page
          in: query
          type: integer
          description: Number of results per page
        - name: query
          in: query
          type: string
          description: One or more search terms separated by spaces
        - name: sort
          in: query
          type: string
          description: Sort by
        - name: sort_order
          in: query
          type: string
          description: Sort order
        - name: vocal_description
          in: query
          type: string
          description: Show tracks with the specified vocal description (male, female)
        - name: view
          in: query
          type: string
          description: Amount of detail to render in the response
        - name: fields
          in: query
          type: string
          description: Fields to display in the response; see the documentation for the fields parameter in the overview section
        - name: library
          in: query
          type: string
          description: Which library to search
        - name: language
          in: query
          type: string
          description: Which language to search in
    - name: v2-audio-id
      path: /v2/audio/{id}
      operations:
      - name: gettrack
        method: GET
        description: Get details about audio tracks
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Audio track ID
          required: true
        - name: view
          in: query
          type: string
          description: Amount of detail to render in the response
    authentication:
      type: bearer
      token: '{{env.SHUTTERSTOCK_API_KEY}}'
  exposes:
  - type: rest
    namespace: shutterstock-audio-rest
    port: 8080
    description: REST adapter for Shutterstock API Reference — audio. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/v2/audio
      name: v2-audio
      description: REST surface for v2-audio.
      operations:
      - method: GET
        name: gettracklist
        description: List audio tracks
        call: shutterstock-audio.gettracklist
        with:
          id: rest.id
          view: rest.view
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/audio/collections
      name: v2-audio-collections
      description: REST surface for v2-audio-collections.
      operations:
      - method: POST
        name: createsoundbox
        description: Create audio collections
        call: shutterstock-audio.createsoundbox
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getsoundboxlist
        description: List audio collections
        call: shutterstock-audio.getsoundboxlist
        with:
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/audio/collections/{id}
      name: v2-audio-collections-id
      description: REST surface for v2-audio-collections-id.
      operations:
      - method: GET
        name: getsoundbox
        description: Get the details of audio collections
        call: shutterstock-audio.getsoundbox
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: renamesoundbox
        description: Rename audio collections
        call: shutterstock-audio.renamesoundbox
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deletesoundbox
        description: Delete audio collections
        call: shutterstock-audio.deletesoundbox
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/audio/collections/{id}/items
      name: v2-audio-collections-id-items
      description: REST surface for v2-audio-collections-id-items.
      operations:
      - method: POST
        name: addsoundboxitems
        description: Add audio tracks to collections
        call: shutterstock-audio.addsoundboxitems
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getsoundboxitems
        description: Get the contents of audio collections
        call: shutterstock-audio.getsoundboxitems
        with:
          id: rest.id
          page: rest.page
          per_page: rest.per_page
          sort: rest.sort
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deletesoundboxitems
        description: Remove audio tracks from collections
        call: shutterstock-audio.deletesoundboxitems
        with:
          id: rest.id
          item_id: rest.item_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/audio/genres
      name: v2-audio-genres
      description: REST surface for v2-audio-genres.
      operations:
      - method: GET
        name: getgenres
        description: List audio genres
        call: shutterstock-audio.getgenres
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/audio/instruments
      name: v2-audio-instruments
      description: REST surface for v2-audio-instruments.
      operations:
      - method: GET
        name: getinstruments
        description: List audio instruments
        call: shutterstock-audio.getinstruments
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/audio/licenses
      name: v2-audio-licenses
      description: REST surface for v2-audio-licenses.
      operations:
      - method: POST
        name: licensetrack
        description: License audio tracks
        call: shutterstock-audio.licensetrack
        with:
          license: rest.license
          search_id: rest.search_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getaudiolicenselist
        description: List audio licenses
        call: shutterstock-audio.getaudiolicenselist
        with:
          audio_id: rest.audio_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/audio/licenses/{id}/downloads
      name: v2-audio-licenses-id-downloads
      description: REST surface for v2-audio-licenses-id-downloads.
      operations:
      - method: POST
        name: downloadtracks
        description: Download audio tracks
        call: shutterstock-audio.downloadtracks
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/audio/moods
      name: v2-audio-moods
      description: REST surface for v2-audio-moods.
      operations:
      - method: GET
        name: getmoods
        description: List audio moods
        call: shutterstock-audio.getmoods
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/audio/search
      name: v2-audio-search
      description: REST surface for v2-audio-search.
      operations:
      - method: GET
        name: searchaudio
        description: Search for tracks
        call: shutterstock-audio.searchaudio
        with:
          artists: rest.artists
          bpm: rest.bpm
          bpm_from: rest.bpm_from
          bpm_to: rest.bpm_to
          duration: rest.duration
          duration_from: rest.duration_from
          duration_to: rest.duration_to
          genre: rest.genre
          is_instrumental: rest.is_instrumental
          instruments: rest.instruments
          moods: rest.moods
          page: rest.page
          per_page: rest.per_page
          query: rest.query
          sort: rest.sort
          sort_order: rest.sort_order
          vocal_description: rest.vocal_description
          view: rest.view
          fields: rest.fields
          library: rest.library
          language: rest.language
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/audio/{id}
      name: v2-audio-id
      description: REST surface for v2-audio-id.
      operations:
      - method: GET
        name: gettrack
        description: Get details about audio tracks
        call: shutterstock-audio.gettrack
        with:
          id: rest.id
          view: rest.view
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: shutterstock-audio-mcp
    port: 9090
    transport: http
    description: MCP adapter for Shutterstock API Reference — audio. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: list-audio-tracks
      description: List audio tracks
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shutterstock-audio.gettracklist
      with:
        id: tools.id
        view: tools.view
      outputParameters:
      - type: object
        mapping: $.
    - name: create-audio-collections
      description: Create audio collections
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: shutterstock-audio.createsoundbox
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: list-audio-collections
      description: List audio collections
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shutterstock-audio.getsoundboxlist
      with:
        page: tools.page
        per_page: tools.per_page
      outputParameters:
      - type: object
        mapping: $.
    - name: get-details-audio-collections
      description: Get the details of audio collections
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shutterstock-audio.getsoundbox
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: rename-audio-collections
      description: Rename audio collections
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: shutterstock-audio.renamesoundbox
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-audio-collections
      description: Delete audio collections
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: shutterstock-audio.deletesoundbox
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: add-audio-tracks-collections
      description: Add audio tracks to collections
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: shutterstock-audio.addsoundboxitems
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contents-audio-collections
      description: Get the contents of audio collections
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shutterstock-audio.getsoundboxitems
      with:
        id: tools.id
        page: tools.page
        per_page: tools.per_page
        sort: tools.sort
      outputParameters:
      - type: object
        mapping: $.
    - name: remove-audio-tracks-collections
      description: Remove audio tracks from collections
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: shutterstock-audio.deletesoundboxitems
      with:
        id: tools.id
        item_id: tools.item_id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-audio-genres
      description: List audio genres
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shutterstock-audio.getgenres
      outputParameters:
      - type: object
        mapping: $.
    - name: list-audio-instruments
      description: List audio instruments
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shutterstock-audio.getinstruments
      outputParameters:
      - type: object
        mapping: $.
    - name: license-audio-tracks
      description: License audio tracks
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: shutterstock-audio.licensetrack
      with:
        license: tools.license
        search_id: tools.search_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: list-audio-licenses
      description: List audio licenses
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shutterstock-audio.getaudiolicenselist
      with:
        audio_id: tools.audio_id
      outputParameters:
      - type: object
        mapping: $.
    - name: download-audio-tracks
      description: Download audio tracks
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: shutterstock-audio.downloadtracks
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-audio-moods
      description: List audio moods
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shutterstock-audio.getmoods
      outputParameters:
      - type: object
        mapping: $.
    - name: search-tracks
      description: Search for tracks
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shutterstock-audio.searchaudio
      with:
        artists: tools.artists
        bpm: tools.bpm
        bpm_from: tools.bpm_from
        bpm_to: tools.bpm_to
        duration: tools.duration
        duration_from: tools.duration_from
        duration_to: tools.duration_to
        genre: tools.genre
        is_instrumental: tools.is_instrumental
        instruments: tools.instruments
        moods: tools.moods
        page: tools.page
        per_page: tools.per_page
        query: tools.query
        sort: tools.sort
        sort_order: tools.sort_order
        vocal_description: tools.vocal_description
        view: tools.view
        fields: tools.fields
        library: tools.library
        language: tools.language
      outputParameters:
      - type: object
        mapping: $.
    - name: get-details-about-audio-tracks
      description: Get details about audio tracks
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shutterstock-audio.gettrack
      with:
        id: tools.id
        view: tools.view
      outputParameters:
      - type: object
        mapping: $.