Songtradr API

openapi: 3.1.0
info:
  title: Songtradr API
  description: 'This is the Songtradr API. Use it to retrieve deep music metadata and trigger processes like auto-tagging.


    You can also use the API to manage your account and musicube cloud data.


    **Authentication**


    1. Reach out to support@songtradr.com to receive a free account or use your login data if you are already signed up.


    2. To authenticate, you need to login via the POST /api/v1/user/login endpoint.


    3. The endpoint responds with a jwtToken which you can use in all following API requests as a bearer token.


    **Rate Limiting**


    The current limit is 120 Requests per minute. Reach out to us via support@songtradr.com if you need to request more.


    **Getting Started with auto-tagging**


    1. If you want to get your own files auto-tagged, use the POST /api/v1/user/file/{name}/initUpload endpoint. It responds
    with a presigned S3 link where you can upload your file.

    2. You can check the processing status of your file via the GET /api/v1/user/file/{name}/filesStatus endpoint.

    3. As soon as processing is done, you can request the generated data via the GET /api/v1/user/files endpoint.


    **Getting Started with search**


    You can either search the released music via the /public/recording endpoints or your own private uploaded music via the
    /user/file/ endpoints.


    1. If you want to search the world''s released music, a good starting point is the GET /api/v1/public/recording/search
    endpoint. Please find the extensive list of parameters that serve as semantic search filters.

    2. If you want to search your own previously uploaded music, a good starting point is the GET GET /api/v1/user/files endpoint.
    It has the same extensive list of parameters that serve as semantic search filters.'
  contact:
    name: Songtradr Inc.
    url: https://songtradr.com
    email: info@songtradr.com
  version: 3.0.0
servers:
- url: https://api.songtradr.com
  description: Generated server url
paths:
  /api/v1/user/update-password:
    post:
      tags:
      - user
      summary: Update password by using the password reset token
      operationId: updatePassword
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePasswordDTO'
        required: true
      responses:
        '204':
          description: Password was updated
          content:
            application/hal+json:
              schema:
                type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.290+00:00'
                status: 401
                error: Unauthorized
                message: a detailed error message
                path: /api/v1/user/update-password
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.290+00:00'
                status: 429
                error: Too Many Requests
                message: a detailed error message
                path: /api/v1/user/update-password
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.290+00:00'
                status: 500
                error: Internal Server Error
                message: a detailed error message
                path: /api/v1/user/update-password
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.290+00:00'
                status: 400
                error: Bad Request
                message: a detailed error message
                path: /api/v1/user/update-password
      security:
      - bearer-jwt: []
  /api/v1/user/token:
    post:
      tags:
      - user
      summary: Generates a new JWT token for the given refresh token
      operationId: token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
        required: true
      responses:
        '200':
          description: Generated a bearer JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwtTokenDTO'
        '401':
          description: The given refresh token is invalid or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.290+00:00'
                status: 429
                error: Too Many Requests
                message: a detailed error message
                path: /api/v1/user/token
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.290+00:00'
                status: 500
                error: Internal Server Error
                message: a detailed error message
                path: /api/v1/user/token
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.290+00:00'
                status: 400
                error: Bad Request
                message: a detailed error message
                path: /api/v1/user/token
      security:
      - bearer-jwt: []
  /api/v1/user/sign-up:
    post:
      tags:
      - user
      summary: Sign up a new user.
      operationId: signUp
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveUserDTO'
        required: true
      responses:
        '200':
          description: Signed up a new user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignUpDTO'
        '403':
          description: User is not allowed to sign up other users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: User identification is not available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.290+00:00'
                status: 401
                error: Unauthorized
                message: a detailed error message
                path: /api/v1/user/sign-up
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.290+00:00'
                status: 429
                error: Too Many Requests
                message: a detailed error message
                path: /api/v1/user/sign-up
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.290+00:00'
                status: 500
                error: Internal Server Error
                message: a detailed error message
                path: /api/v1/user/sign-up
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.290+00:00'
                status: 400
                error: Bad Request
                message: a detailed error message
                path: /api/v1/user/sign-up
      security:
      - bearer-jwt: []
  /api/v1/user/me:
    get:
      tags:
      - user
      summary: Details for a logged-in user
      operationId: me
      responses:
        '200':
          description: Found user details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDTO'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 401
                error: Unauthorized
                message: a detailed error message
                path: /api/v1/user/me
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 429
                error: Too Many Requests
                message: a detailed error message
                path: /api/v1/user/me
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 500
                error: Internal Server Error
                message: a detailed error message
                path: /api/v1/user/me
      security:
      - bearer-jwt: []
    post:
      tags:
      - user
      summary: Edit details for a logged-in user
      operationId: editMe
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveUserDTO'
        required: true
      responses:
        '200':
          description: Edited user details.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 401
                error: Unauthorized
                message: a detailed error message
                path: /api/v1/user/me
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 429
                error: Too Many Requests
                message: a detailed error message
                path: /api/v1/user/me
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 500
                error: Internal Server Error
                message: a detailed error message
                path: /api/v1/user/me
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 400
                error: Bad Request
                message: a detailed error message
                path: /api/v1/user/me
      security:
      - bearer-jwt: []
  /api/v1/user/login:
    post:
      tags:
      - user
      summary: Login to generate a bearer token.
      operationId: login
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginDTO'
        required: true
      responses:
        '200':
          description: Generated a bearer JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwtTokenDTO'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 401
                error: Unauthorized
                message: a detailed error message
                path: /api/v1/user/login
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 429
                error: Too Many Requests
                message: a detailed error message
                path: /api/v1/user/login
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 500
                error: Internal Server Error
                message: a detailed error message
                path: /api/v1/user/login
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 400
                error: Bad Request
                message: a detailed error message
                path: /api/v1/user/login
      security:
      - bearer-jwt: []
  /api/v1/user/forgot-password:
    post:
      tags:
      - user
      summary: Send a password reset email
      operationId: forgotPassword
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForgotPasswordDTO'
        required: true
      responses:
        '200':
          description: Password reset email was sent if user exist.
          content:
            application/hal+json:
              schema:
                type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 401
                error: Unauthorized
                message: a detailed error message
                path: /api/v1/user/forgot-password
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 429
                error: Too Many Requests
                message: a detailed error message
                path: /api/v1/user/forgot-password
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 500
                error: Internal Server Error
                message: a detailed error message
                path: /api/v1/user/forgot-password
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 400
                error: Bad Request
                message: a detailed error message
                path: /api/v1/user/forgot-password
      security:
      - bearer-jwt: []
  /api/v1/user/file/{name}/initUpload:
    post:
      tags:
      - user
      summary: Initialize a file upload. Responds with an URL where the file can be uploaded.
      operationId: initiateUserFileUpload
      parameters:
      - name: name
        in: path
        description: The Name of the file that will be uploaded
        required: true
        schema:
          type: string
        example: FileName.mp3
      - name: folder
        in: query
        description: The Name of the folder that the file will be placed in
        required: true
        schema:
          type: string
        example: FolderName
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileUploadDTO'
      responses:
        '200':
          description: Provided URL to upload file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitPutRecordingAudioDTO'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 401
                error: Unauthorized
                message: a detailed error message
                path: /api/v1/user/file/{name}/initUpload
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 429
                error: Too Many Requests
                message: a detailed error message
                path: /api/v1/user/file/{name}/initUpload
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 500
                error: Internal Server Error
                message: a detailed error message
                path: /api/v1/user/file/{name}/initUpload
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 400
                error: Bad Request
                message: a detailed error message
                path: /api/v1/user/file/{name}/initUpload
      security:
      - bearer-jwt: []
  /api/v1/user/recording/{ids}:
    get:
      tags:
      - user
      summary: Recordings by IDs with a medium sized response.
      operationId: recordingsMediumByIds
      parameters:
      - name: ids
        in: path
        description: Comma seperated list of IDs. Can be ISRCs or proprietary IDs
        required: true
        schema:
          type: string
        example: GBAHT0108619
      - name: globalView
        in: query
        description: Show not only user recordings.
        required: false
        schema:
          type: boolean
        example: true
      - name: taxonomyVersion
        in: query
        description: The version of the AI taxonomy to use.
        required: false
        schema:
          type: string
          default: v2_4
          enum:
          - v2_4
        example: v2_4
      - name: page
        in: query
        description: Zero-based page index (0..N)
        schema:
          type: integer
          default: 0
      - name: size
        in: query
        description: The size of the page to be returned
        schema:
          type: integer
          default: 20
      - name: sort
        in: query
        description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort
          criteria are supported.'
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Found recordings.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  anyOf:
                  - $ref: '#/components/schemas/RecordingMediumV24DTO'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 401
                error: Unauthorized
                message: a detailed error message
                path: /api/v1/user/recording/{ids}
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 429
                error: Too Many Requests
                message: a detailed error message
                path: /api/v1/user/recording/{ids}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 500
                error: Internal Server Error
                message: a detailed error message
                path: /api/v1/user/recording/{ids}
      security:
      - bearer-jwt: []
  /api/v1/user/recording/{ids}/tagstrengths:
    get:
      tags:
      - user
      summary: Strengths as numerical representations for AI generated moods, musical features and more for recordings.
      operationId: recordingsByIdsWithTagstrengths
      parameters:
      - name: ids
        in: path
        description: Comma seperated list of IDs. Can be ISRCs or proprietary IDs
        required: true
        schema:
          type: string
        example: USUM71703692
      - name: categoryName
        in: query
        description: Show only tagstrengths for one category.
        required: false
        schema:
          type: string
          enum:
          - level1Genre
          - level2Genre
          - songRating
          - performanceRating
          - productionRating
          - moodCluster
          - vocals
          - dominantInstrument
          - soundGeneration
          - rhythm
          - tonality
          - audienceAge
          - audienceGender
          - audienceRegion
          - originRegion
          - originDecade
          - useCase
          - tempo
          - scale
          - key
          - harmony
          - industrySuitability
          - pretzelStationSuitability
          - recordingEnvironment
          - content
          - brandAttributes
          - curateability
          - harmony
          - arousal
          - valence
          - pleasantness
          - engagement
          - timbre
          - roughness
          - texture
          - grooviness
          - space
          - loudness
          - bpm
        example: moodCluster
      - name: tagName
        in: query
        description: Show only tagstrengths for one tag.
        required: false
        schema:
          type: string
        example: energetic
      - name: genreName
        in: query
        description: Show only tagstrengths for one genre.
        required: false
        schema:
          type: string
        example: Ska
      - name: globalView
        in: query
        description: Show tagstrengths not only for user recordings.
        required: false
        schema:
          type: boolean
        example: true
      - name: taxonomyVersion
        in: query
        description: The version of the AI taxonomy to use.
        required: false
        schema:
          type: string
          default: v2_4
          enum:
          - v2_4
        example: v2_4
      responses:
        '200':
          description: Found recordings.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecordingMinimalWithTagstrengthsDTO'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 401
                error: Unauthorized
                message: a detailed error message
                path: /api/v1/user/recording/{ids}/tagstrengths
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 429
                error: Too Many Requests
                message: a detailed error message
                path: /api/v1/user/recording/{ids}/tagstrengths
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                example:
                  $ref: '#/components/examples/'
              example:
                timestamp: '2026-05-15T13:32:42.291+00:00'
                status: 500
                error: Internal Server Error
                message: a detailed error message
                path: /api/v1/user/recording/{ids}/tagstrengths
      security:
      - bearer-jwt: []
  /api/v1/user/recording/{ids}/taggrams:
    get:
      tags:
      - user
      summary: Timeseries of AI generated moods, musical features and more for a list of recordings.
      operationId: recordingsByIdsWithTaggrams
      parameters:
      - name: ids
        in: path
        description: Comma seperated list of IDs. Can be ISRCs or proprietary IDs
        required: true
        schema:
          type: string
        example: USUM71703692
      - name: categoryName
        in: query
        description: Show only taggrams for one category.
        required: false
        schema:
          type: string
          enum:
          - level1Genre
          - level2Genre
          - songRating
          - performanceRating
          - productionRating
          - moodCluster
          - vocals
          - dominantInstrument
          - soundGeneration
          - rhythm
          - tonality
          - audienceAge
          - audienceGender
          - audienceRegion
          - originRegion
          - originDecade
          - useCase
          - tempo
          - scale
          - key
          - harmony
          - industrySuitability
          - pretzelStationSuitability
          - recordingEnvironment
          - content
          - brandAttributes
          - curateability
          - harmony
          - arousal
          - valence
          - pleasantness
          - engagement
          - timbre
          - roughness
          - texture
          - grooviness
          - space
          - loudness
          - bpm
        example: moodCluster
      - name: tagName
        in: query
        description: Show only taggrams for one tag.
        required: false
        schema:
          type: string
        example: energetic
      - name: genreName
        in: query
        description: Show only taggrams for one genre.
        required: false
        schema:
          type: string
        example: Ska
      - name: fromTimestamp
        in: query
        description: Show only taggrams data starting from from this timestamp in seconds.
        required: false
        schema:
          type: number
        example: 16.0
      - name: toTimestamp
        in: query
        description: Show only taggrams data before this timestamp in seconds.
        required: false
        schema:
          type: number
        example: 32.0
      - name: fillWithZero
        in: query
        description: If set to true, empty timeseries are filled with timeseries of 0.0 values.
        required: false
        schema:
          type: boolean
        example: true
      - name: globalView
        in: query
        description: Show taggrams not only for user recordings
        required: false
        schema:
          type: b

# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/songtradr/refs/heads/main/openapi/songtradr-api-openapi.yml