openapi: 3.0.1
info:
  title: Audicin for Apps API
  description: |
    **Audicin for Apps API Authentication (REQUIRED)**

    All Audicin for Apps API  endpoints require the `X-API-KEY` header.

    Example:
    ```
    X-API-KEY: xxxxxxxxx
    ```

    Common error responses:
    - 401 → Missing or invalid API key
    - 402 → Subscription inactive / expired
    - 403 → License missing or quota exceeded
    - 404 → Resource not found
  version: 1.0.0
  termsOfService: https://audicin.com/our-terms-and-conditions/
  contact:
    name: TEAM
    email: developers@audicin.com
    url: https://audicin.com
  license:
    name: Proprietary License
    url: https://audicin.com/our-terms-and-conditions/
  x-generation-date: '2025-04-27T13:19:45.649Z'
servers:
  - url: https://dev.api-b2b.audicin.com/api/v1
    description: Generated server url
tags:
  - name: Artists
    description: Fetch artist metadata
  - name: Licenses
    description: Fetch license data
  - name: Categories
    description: Fetch category data
  - name: Streaming
    description: Generate presigned URLs for audio previews and full audios
  - name: Songs
    description: Fetch song data and metadata
  - name: Media
    description: Fetch media data
paths:
  /tenants/stream/songPreview/{songPreviewId}:
    get:
      tags:
        - Streaming
      summary: Generate presigned preview audio URL
      description: Returns a presigned GET URL for a song preview
      operationId: streamPreviewAudio
      parameters:
        - name: songPreviewId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamingTenantResponse'
              example:
                songId: 01HXZK9YF8A1B3C4D5E6F7G8H
                title: My Song
                url: https://example.com/get/abc
                method: GET
                expiresInSeconds: 300
                songDuration: 180
                objectMetadata:
                  contentType: audio/mpeg
                  size: 3456789
        '400':
          description: Bad Request – invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                validationError:
                  summary: Validation failed
                  value:
                    errorCode: COMMON-VALIDATION-400
                    error: Validation Failed
                    message: One or more fields are invalid
                    details: null
                    validationErrors:
                      size: must be less than or equal to 100
                invalidParameter:
                  summary: Invalid parameter
                  value:
                    errorCode: COMMON-ARGUMENT-400
                    title: Invalid Parameter
                    message: Invalid parameter value
                    details: null
                    validationErrors: null
        '401':
          description: Unauthorized – missing or invalid API key
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
              example: Unauthorized
        '402':
          description: Subscription inactive, expired, or canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-SUB-402
                title: Subscription Inactive
                message: ''
                ref: null
        '403':
          description: Forbidden – license missing, quota exceeded, or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-LIC-403
                title: License required
                message: ''
                ref: null
        '404':
          description: License not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-LIC-404
                title: License Not Found
                message: License not found
                ref: null
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-500
                title: Internal Server Error
                message: An unexpected error occurred
                ref: null
      security:
        - api-key: []
  /tenants/stream/song/{songId}:
    get:
      tags:
        - Streaming
      summary: Generate presigned download URL
      description: Returns a presigned GET URL
      operationId: streamSongAudio
      parameters:
        - name: songId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamingTenantResponse'
              example:
                songId: 01HXZK9YF8A1B3C4D5E6F7G8H
                title: My Song
                url: https://example.com/get/abc
                method: GET
                expiresInSeconds: 300
                songDuration: 180
                objectMetadata:
                  contentType: audio/mpeg
                  size: 3456789
        '400':
          description: Bad Request – invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                validationError:
                  summary: Validation failed
                  value:
                    errorCode: COMMON-VALIDATION-400
                    error: Validation Failed
                    message: One or more fields are invalid
                    details: null
                    validationErrors:
                      size: must be less than or equal to 100
                invalidParameter:
                  summary: Invalid parameter
                  value:
                    errorCode: COMMON-ARGUMENT-400
                    title: Invalid Parameter
                    message: Invalid parameter value
                    details: null
                    validationErrors: null
        '401':
          description: Unauthorized – missing or invalid API key
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
              example: Unauthorized
        '402':
          description: Subscription inactive, expired, or canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-SUB-402
                title: Subscription Inactive
                message: ''
                ref: null
        '403':
          description: Forbidden – license missing, quota exceeded, or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-LIC-403
                title: Forbidden
                message: License missing or quota exceeded
                ref: null
        '404':
          description: License not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-LIC-404
                title: License Not Found
                message: License not found
                ref: null
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-500
                title: Internal Server Error
                message: An unexpected error occurred
                ref: null
      security:
        - api-key: []
  /tenants/songs:
    get:
      tags:
        - Songs
      summary: List available songs in catalogue
      description: >-
        Returns a paginated list of songs from the Audicin catalogue that are
        visible to the authenticated tenant. Supports filtering by title and
        genre. Song availability does not imply licensing or streaming rights.
      operationId: getAllSongs
      parameters:
        - name: page
          in: query
          required: false
          schema:
            maximum: 100
            minimum: 0
            type: integer
            format: int32
            default: 0
        - name: size
          in: query
          required: false
          schema:
            maximum: 100
            minimum: 1
            type: integer
            format: int32
            default: 10
        - name: title
          in: query
          required: false
          schema:
            type: string
        - name: mainGenre
          in: query
          required: false
          schema:
            type: string
        - name: secondaryGenre
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of artists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistTenantPage'
              example:
                content: []
                number: 0
                size: 10
                totalElements: 0
                totalPages: 0
        '400':
          description: Bad Request – invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                validationError:
                  summary: Validation failed
                  value:
                    errorCode: COMMON-VALIDATION-400
                    error: Validation Failed
                    message: One or more fields are invalid
                    details: null
                    validationErrors:
                      size: must be less than or equal to 100
                invalidParameter:
                  summary: Invalid parameter
                  value:
                    errorCode: COMMON-ARGUMENT-400
                    title: Invalid Parameter
                    message: Invalid parameter value
                    details: null
                    validationErrors: null
        '401':
          description: Unauthorized – missing or invalid API key
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
              example: Unauthorized
        '402':
          description: Subscription inactive, expired, or canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-SUB-402
                title: Subscription Inactive
                message: Subscription inactive, expired, or canceled
                ref: null
        '403':
          description: Forbidden – access denied
          content:
            text/plain:
              schema:
                type: string
                example: Forbidden
              example: Forbidden
        '404':
          description: Resource not found – media, license, or entity does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-404
                title: Resource Not Found
                message: Resource not found
                ref: null
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-500
                title: Internal Server Error
                message: An unexpected error occurred
                ref: null
      security:
        - api-key: []
  /tenants/songs/{songId}:
    get:
      tags:
        - Songs
      summary: Get song details from catalogue
      description: >-
        Fetches detailed metadata for a single song available in the Audicin
        catalogue for the authenticated tenant. This endpoint does not grant a
        license or streaming access; it only returns song information.
      operationId: getSong
      parameters:
        - name: songId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SongTenantResponse'
              example:
                id: 01HXZK9YF8A1B3C4D5E6F7G8H
                title: Example Song
                mainArtist:
                  id: 01HXZK9YF8A1B3C4D5E6F7G8H0
                  firstName: Jane
                  lastName: Artist
                  description: Artist bio
                  avatar: null
                seconds: 180
                previewAudio: null
                coverMedia: null
                description: Song description
                categories: []
                artists: []
        '400':
          description: Bad Request – invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                validationError:
                  summary: Validation failed
                  value:
                    errorCode: COMMON-VALIDATION-400
                    error: Validation Failed
                    message: One or more fields are invalid
                    details: null
                    validationErrors:
                      size: must be less than or equal to 100
                invalidParameter:
                  summary: Invalid parameter
                  value:
                    errorCode: COMMON-ARGUMENT-400
                    title: Invalid Parameter
                    message: Invalid parameter value
                    details: null
                    validationErrors: null
        '401':
          description: Unauthorized – missing or invalid API key
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
              example: Unauthorized
        '402':
          description: Subscription inactive, expired, or canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-SUB-402
                title: Subscription Inactive
                message: Subscription inactive, expired, or canceled
                ref: null
        '403':
          description: Forbidden – access denied
          content:
            text/plain:
              schema:
                type: string
                example: Forbidden
              example: Forbidden
        '404':
          description: Resource not found – media, license, or entity does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-404
                title: Resource Not Found
                message: Resource not found
                ref: null
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-500
                title: Internal Server Error
                message: An unexpected error occurred
                ref: null
      security:
        - api-key: []
  /tenants/myLicenses:
    get:
      tags:
        - Licenses
      summary: List tenant licenses
      description: >-
        Returns a paginated list of licenses owned by the authenticated tenant.
        Results can be filtered by song and license validity.


        - When `onlyValidNow=true`, only currently active licenses are returned.

        - When `onlyValidNow=false`, historical licenses are also included.


        This endpoint is typically used to display license usage, quota
        tracking, and compliance status in the developer dashboard.
      operationId: getLicenses
      parameters:
        - name: songId
          in: query
          required: false
          schema:
            type: string
        - name: onlyValidNow
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: page
          in: query
          required: false
          schema:
            maximum: 1000
            minimum: 0
            type: integer
            format: int32
            default: 0
        - name: size
          in: query
          required: false
          schema:
            maximum: 1000
            minimum: 1
            type: integer
            format: int32
            default: 10
      responses:
        '200':
          description: Paginated list of artists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistTenantPage'
              example:
                content: []
                number: 0
                size: 10
                totalElements: 0
                totalPages: 0
        '400':
          description: Bad Request – invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                validationError:
                  summary: Validation failed
                  value:
                    errorCode: COMMON-VALIDATION-400
                    error: Validation Failed
                    message: One or more fields are invalid
                    details: null
                    validationErrors:
                      size: must be less than or equal to 100
                invalidParameter:
                  summary: Invalid parameter
                  value:
                    errorCode: COMMON-ARGUMENT-400
                    title: Invalid Parameter
                    message: Invalid parameter value
                    details: null
                    validationErrors: null
        '401':
          description: Unauthorized – missing or invalid API key
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
              example: Unauthorized
        '402':
          description: Subscription inactive, expired, or canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-SUB-402
                title: Subscription Inactive
                message: Subscription inactive, expired, or canceled
                ref: null
        '403':
          description: Forbidden – access denied
          content:
            text/plain:
              schema:
                type: string
                example: Forbidden
              example: Forbidden
        '404':
          description: Resource not found – media, license, or entity does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-404
                title: Resource Not Found
                message: Resource not found
                ref: null
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-500
                title: Internal Server Error
                message: An unexpected error occurred
                ref: null
      security:
        - api-key: []
  /tenants/myLicenses/check-access:
    get:
      tags:
        - Licenses
      summary: Check license access for a song
      description: >-
        Checks whether the authenticated tenant has an active or historical
        license for a specific song. This endpoint is commonly used before
        attempting playback or streaming.


        - When `onlyValid=true`, only currently active licenses are considered.

        - When `onlyValid=false`, expired or revoked licenses may also be
        returned.
      operationId: checkLicenseForSong
      parameters:
        - name: songId
          in: query
          required: true
          schema:
            type: string
        - name: onlyValid
          in: query
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseTenantResponse'
              example:
                id: 01HXZK9YF8A1B3C4D5E6F7G8H
                song:
                  songId: 01HXZK9YF8A1B3C4D5E6F7G8H
                  title: Example Song
                  categories: []
                  seconds: 180
                status: ACTIVE
                validFrom: '2025-01-01T00:00:00Z'
                validTo: '2026-01-01T00:00:00Z'
                createdAt: '2025-01-01T00:00:00Z'
        '400':
          description: Bad Request – invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                validationError:
                  summary: Validation failed
                  value:
                    errorCode: COMMON-VALIDATION-400
                    error: Validation Failed
                    message: One or more fields are invalid
                    details: null
                    validationErrors:
                      size: must be less than or equal to 100
                invalidParameter:
                  summary: Invalid parameter
                  value:
                    errorCode: COMMON-ARGUMENT-400
                    title: Invalid Parameter
                    message: Invalid parameter value
                    details: null
                    validationErrors: null
        '401':
          description: Unauthorized – missing or invalid API key
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
              example: Unauthorized
        '402':
          description: Subscription inactive, expired, or canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-SUB-402
                title: Subscription Inactive
                message: ''
                ref: null
        '403':
          description: Forbidden – access denied
          content:
            text/plain:
              schema:
                type: string
                example: Forbidden
              example: Forbidden
        '404':
          description: Resource not found – media, license, or entity does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-404
                title: Resource Not Found
                message: Resource not found
                ref: null
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-500
                title: Internal Server Error
                message: An unexpected error occurred
                ref: null
      security:
        - api-key: []
  /tenants/downloadable/images/{mediaId}:
    get:
      tags:
        - Media
      summary: Get image download URL by ID
      description: >-
        Returns a presigned download URL for image media for song cover or
        artist avatar
      operationId: getImageDownloadUrl
      parameters:
        - name: mediaId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
              example:
                url: https://example.com/presigned/image/abc123
                expiresInSeconds: 3600
        '400':
          description: Bad Request – invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                validationError:
                  summary: Validation failed
                  value:
                    errorCode: COMMON-VALIDATION-400
                    error: Validation Failed
                    message: One or more fields are invalid
                    details: null
                    validationErrors:
                      size: must be less than or equal to 100
                invalidParameter:
                  summary: Invalid parameter
                  value:
                    errorCode: COMMON-ARGUMENT-400
                    title: Invalid Parameter
                    message: Invalid parameter value
                    details: null
                    validationErrors: null
        '401':
          description: Unauthorized – missing or invalid API key
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
              example: Unauthorized
        '402':
          description: Subscription inactive, expired, or canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-SUB-402
                title: Subscription Inactive
                message: ''
                ref: null
        '403':
          description: Forbidden – access denied
          content:
            text/plain:
              schema:
                type: string
                example: Forbidden
              example: Forbidden
        '404':
          description: Resource not found – media, license, or entity does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-404
                title: Resource Not Found
                message: Resource not found
                ref: null
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-500
                title: Internal Server Error
                message: An unexpected error occurred
                ref: null
      security:
        - api-key: []
  /tenants/categories:
    get:
      tags:
        - Categories
      summary: List available song categories
      description: >-
        Returns a paginated list of song categories available to the tenant.
        Categories are used to organize and filter the music catalogue (e.g.
        genres, moods, or classification groups).


        This endpoint is typically used to populate filters, dropdowns, or
        navigation elements in the catalogue UI.
      operationId: getAllCategories
      parameters:
        - name: page
          in: query
          required: false
          schema:
            maximum: 100
            minimum: 0
            type: integer
            format: int32
            default: 0
        - name: size
          in: query
          required: false
          schema:
            maximum: 100
            minimum: 1
            type: integer
            format: int32
            default: 10
      responses:
        '200':
          description: Paginated list of categories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryTenantPage'
              example:
                content:
                  - id: 01HXZK9YF8A1B3C4D5E6F7G8H
                    name: Pop
                    type: main
                number: 0
                size: 10
                totalElements: 1
                totalPages: 1
        '400':
          description: Bad Request – invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                validationError:
                  summary: Validation failed
                  value:
                    errorCode: COMMON-VALIDATION-400
                    error: Validation Failed
                    message: One or more fields are invalid
                    details: null
                    validationErrors:
                      size: must be less than or equal to 100
                invalidParameter:
                  summary: Invalid parameter
                  value:
                    errorCode: COMMON-ARGUMENT-400
                    title: Invalid Parameter
                    message: Invalid parameter value
                    details: null
                    validationErrors: null
        '401':
          description: Unauthorized – missing or invalid API key
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
              example: Unauthorized
        '402':
          description: Subscription inactive, expired, or canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-SUB-402
                title: Subscription Inactive
                message: ''
                ref: null
        '403':
          description: Forbidden – access denied
          content:
            text/plain:
              schema:
                type: string
                example: Forbidden
              example: Forbidden
        '404':
          description: Resource not found – media, license, or entity does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-404
                title: Resource Not Found
                message: Resource not found
                ref: null
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-500
                title: Internal Server Error
                message: An unexpected error occurred
                ref: null
      security:
        - api-key: []
  /tenants/artists:
    get:
      tags:
        - Artists
      summary: List artists in catalogue
      description: >-
        Returns a paginated list of artists available in the Audicin catalogue.


        Supports optional filtering by artist first name and/or last name. This
        endpoint is commonly used for catalogue browsing, search, and artist
        discovery features.
      operationId: getAllArtists
      parameters:
        - name: page
          in: query
          required: false
          schema:
            maximum: 100
            minimum: 0
            type: integer
            format: int32
            default: 0
        - name: size
          in: query
          required: false
          schema:
            maximum: 100
            minimum: 1
            type: integer
            format: int32
            default: 10
        - name: artistFirstName
          in: query
          required: false
          schema:
            type: string
        - name: artistLastName
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of artists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistTenantPage'
              example:
                content: []
                number: 0
                size: 10
                totalElements: 0
                totalPages: 0
        '400':
          description: Bad Request – invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                validationError:
                  summary: Validation failed
                  value:
                    errorCode: COMMON-VALIDATION-400
                    error: Validation Failed
                    message: One or more fields are invalid
                    details: null
                    validationErrors:
                      size: must be less than or equal to 100
                invalidParameter:
                  summary: Invalid parameter
                  value:
                    errorCode: COMMON-ARGUMENT-400
                    title: Invalid Parameter
                    message: Invalid parameter value
                    details: null
                    validationErrors: null
        '401':
          description: Unauthorized – missing or invalid API key
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
              example: Unauthorized
        '402':
          description: Subscription inactive, expired, or canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-SUB-402
                title: Subscription Inactive
                message: ''
                ref: null
        '403':
          description: Forbidden – access denied
          content:
            text/plain:
              schema:
                type: string
                example: Forbidden
              example: Forbidden
        '404':
          description: Resource not found – media, license, or entity does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-404
                title: Resource Not Found
                message: Resource not found
                ref: null
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-500
                title: Internal Server Error
                message: An unexpected error occurred
                ref: null
      security:
        - api-key: []
  /tenants/artists/{artistId}:
    get:
      tags:
        - Artists
      summary: Fetch artist details
      description: >-
        Returns detailed information about a specific artist available in the
        Audicin catalogue.


        This endpoint is typically used to display artist profile pages, artist
        credits, or contextual information linked from songs.
      operationId: getArtist
      parameters:
        - name: artistId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistTenantResponse'
              example:
                id: 01HXZK9YF8A1B3C4D5E6F7G8H
                firstName: Jane
                lastName: Artist
                description: Artist bio
                avatar: null
        '400':
          description: Bad Request – invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
              examples:
                validationError:
                  summary: Validation failed
                  value:
                    errorCode: COMMON-VALIDATION-400
                    error: Validation Failed
                    message: One or more fields are invalid
                    details: null
                    validationErrors:
                      size: must be less than or equal to 100
                invalidParameter:
                  summary: Invalid parameter
                  value:
                    errorCode: COMMON-ARGUMENT-400
                    title: Invalid Parameter
                    message: Invalid parameter value
                    details: null
                    validationErrors: null
        '401':
          description: Unauthorized – missing or invalid API key
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
              example: Unauthorized
        '402':
          description: Subscription inactive, expired, or canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TENANT-SUB-402
                title: Subscription Inactive
                message: ''
                ref: null
        '403':
          description: Forbidden – access denied
          content:
            text/plain:
              schema:
                type: string
                example: Forbidden
              example: Forbidden
        '404':
          description: Resource not found – media, license, or entity does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-404
                title: Resource Not Found
                message: Resource not found
                ref: null
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                errorCode: COMMON-500
                title: Internal Server Error
                message: An unexpected error occurred
                ref: null
      security:
        - api-key: []
components:
  schemas:
    StreamingTenantResponse:
      type: object
      properties:
        songId:
          type: string
          example: 01HXZK9YF8A1B3C4D5E6F7G8H
        title:
          type: string
          example: My Song
        url:
          type: string
          example: https://example.com/get/abc
        method:
          type: string
          example: GET
        expiresInSeconds:
          type: integer
          format: int32
          example: 300
        songDuration:
          type: integer
          format: int32
          example: 180
        objectMetadata:
          $ref: '#/components/schemas/TenantStorageObjectMetadataDTO'
    TenantStorageObjectMetadataDTO:
      type: object
      properties:
        contentType:
          type: string
          example: audio/mpeg
        size:
          type: integer
          format: int64
          example: 3456789
      description: Read-only object metadata
    ArtistTenantPage:
      type: object
      properties:
        content:
          type: array
          description: Page content
          items:
            $ref: '#/components/schemas/ArtistTenantResponse'
        number:
          type: integer
          format: int32
          example: 0
        size:
          type: integer
          format: int32
          example: 10
        totalElements:
          type: integer
          format: int64
          example: 42
        totalPages:
          type: integer
          format: int32
          example: 5
    ArtistTenantResponse:
      type: object
      properties:
        id:
          type: string
          description: Artist ULID
        firstName:
          type: string
          description: First name
        lastName:
          type: string
          description: Last name
        description:
          type: string
          description: Artist bio/description
        avatar:
          $ref: '#/components/schemas/MediaTenantResponse'
      description: Artist details as returned to the developer portal
    MediaTenantResponse:
      type: object
      properties:
        id:
          type: string
          description: Media ULID
        required:
          type: boolean
          description: Whether this media is required
        multiple:
          type: boolean
          description: Whether multiple files are allowed
        url:
          type: string
          description: Public or presigned URL to access the media
        allowedType:
          type: string
          description: Allowed MIME type category
          enum:
            - IMAGES
            - FILES
            - VIDEOS
            - AUDIOS
      description: Media asset (audio, image) metadata and URL
    CategoryTenantResponse:
      type: object
      properties:
        id:
          type: string
          description: Category ULID
        name:
          type: string
          description: Category name (e.g. genre)
        type:
          type: string
          description: Category type
          enum:
            - main
            - secondary
      description: Song category/genre as returned to the developer portal
    SongTenantResponse:
      type: object
      properties:
        id:
          type: string
          description: Song ULID
        title:
          type: string
          description: Song title
        mainArtist:
          $ref: '#/components/schemas/ArtistTenantResponse'
        seconds:
          type: integer
          description: Duration in seconds
          format: int32
        previewAudio:
          $ref: '#/components/schemas/MediaTenantResponse'
        coverMedia:
          $ref: '#/components/schemas/MediaTenantResponse'
        description:
          type: string
          description: Song description
        categories:
          type: array
          description: Categories/genres
          items:
            $ref: '#/components/schemas/CategoryTenantResponse'
        artists:
          type: array
          description: All contributing artists
          items:
            $ref: '#/components/schemas/ArtistTenantResponse'
      description: Song details as returned to the developer portal
    CategoryResponse:
      type: object
      properties:
        id:
          type: string
          description: Category ULID
        name:
          type: string
          description: Category name
        type:
          type: string
          description: Category type
          enum:
            - main
            - secondary
        createdDate:
          type: string
          description: Creation timestamp
          format: date-time
        lastModifiedDate:
          type: string
          description: Last modified timestamp
          format: date-time
      description: Category/genre with id, name, type and timestamps
    LicenseTenantResponse:
      type: object
      properties:
        id:
          type: string
          description: License ULID
        song:
          $ref: '#/components/schemas/SongSummary'
        status:
          type: string
          description: License status (ACTIVE, SUSPENDED, REVOKED, EXPIRED)
          enum:
            - ACTIVE
            - SUSPENDED
            - REVOKED
            - EXPIRED
        validFrom:
          type: string
          description: License valid from (inclusive)
          format: date-time
        validTo:
          type: string
          description: License valid until (inclusive)
          format: date-time
        createdAt:
          type: string
          description: Creation timestamp
          format: date-time
      description: License details as returned to the developer portal
    SongSummary:
      type: object
      properties:
        songId:
          type: string
          description: Song ULID
        title:
          type: string
          description: Song title
        categories:
          uniqueItems: true
          type: array
          description: Categories/genres
          items:
            $ref: '#/components/schemas/CategoryResponse'
        seconds:
          type: integer
          description: Duration in seconds
          format: int32
      description: Summary of a song (id, title, categories, duration)
    CategoryTenantPage:
      type: object
      properties:
        content:
          type: array
          description: Page content
          items:
            $ref: '#/components/schemas/CategoryTenantResponse'
        number:
          type: integer
          format: int32
          example: 0
        size:
          type: integer
          format: int32
          example: 10
        totalElements:
          type: integer
          format: int64
          example: 42
        totalPages:
          type: integer
          format: int32
          example: 5
    ApiError:
      type: object
      description: Error response body for 4xx and 5xx responses
      properties:
        errorCode:
          type: string
        title:
          type: string
        message:
          type: string
        ref:
          type: string
          nullable: true
        validationErrors:
          type: object
          additionalProperties:
            type: string
    BadRequestError:
      type: object
      description: Bad Request (400) – validation or invalid parameter
      properties:
        errorCode:
          type: string
        error:
          type: string
          description: e.g. Validation Failed
        title:
          type: string
          description: e.g. Invalid Parameter
        message:
          type: string
        details:
          type: string
          nullable: true
        validationErrors:
          type: object
          additionalProperties:
            type: string
  securitySchemes:
    api-key:
      type: apiKey
      name: X-API-KEY
      in: header
