task_id: task_create_api_get_song
entity_id: api_get_song
generated_at: '2025-12-18T15:16:50.247175'
workflow_version: v001
target:
  type: api
  definition:
    id: api_get_song
    method: GET
    path: /api/songs/:id
    description: Get song details
    responses:
    - status: 200
      description: Song details
      schema:
        id: uuid
        title: string
        duration: integer
        file_url: string
        cover_art_url: string
        artist:
          id: uuid
          stage_name: string
        album:
          id: uuid
          title: string
        genres: array
        play_count: integer
    auth:
      required: false
    depends_on_models:
    - model_song
    - model_artist
    - model_album
related:
  models:
  - id: model_artist
    definition: &id001
      id: model_artist
      name: Artist
      table_name: artists
      description: Extended profile for musicians
      fields:
      - name: id
        type: uuid
        constraints:
        - primary_key
      - name: user_id
        type: uuid
        constraints:
        - not_null
        - foreign_key
        references: users.id
      - name: stage_name
        type: string
        constraints:
        - not_null
      - name: bio
        type: text
        constraints:
        - nullable
      - name: cover_image_url
        type: string
        constraints:
        - nullable
      - name: social_links
        type: jsonb
        description: JSON object with {twitter, instagram, facebook, website}
        constraints:
        - nullable
      - name: verified
        type: boolean
        default: false
      - name: created_at
        type: timestamp
        constraints:
        - not_null
      - name: updated_at
        type: timestamp
        constraints:
        - not_null
      relations:
      - type: belongs_to
        to: model_user
        foreign_key: user_id
      - type: has_many
        to: model_song
        foreign_key: artist_id
      - type: has_many
        to: model_album
        foreign_key: artist_id
      - type: belongs_to
        to: model_label
        foreign_key: label_id
        optional: true
      indexes:
      - fields:
        - user_id
        unique: true
      - fields:
        - stage_name
      timestamps: true
  - id: model_album
    definition: &id002
      id: model_album
      name: Album
      table_name: albums
      description: Collection of songs
      fields:
      - name: id
        type: uuid
        constraints:
        - primary_key
      - name: artist_id
        type: uuid
        constraints:
        - not_null
        - foreign_key
        references: artists.id
      - name: title
        type: string
        constraints:
        - not_null
      - name: description
        type: text
        constraints:
        - nullable
      - name: cover_art_url
        type: string
        constraints:
        - nullable
      - name: release_date
        type: date
        constraints:
        - nullable
      - name: album_type
        type: enum
        values:
        - album
        - ep
        - single
        default: album
      - name: created_at
        type: timestamp
        constraints:
        - not_null
      - name: updated_at
        type: timestamp
        constraints:
        - not_null
      relations:
      - type: belongs_to
        to: model_artist
        foreign_key: artist_id
      - type: has_many
        to: model_song
        foreign_key: album_id
      indexes:
      - fields:
        - artist_id
      - fields:
        - release_date
      timestamps: true
  - id: model_song
    definition: &id003
      id: model_song
      name: Song
      table_name: songs
      description: Audio track with metadata
      fields:
      - name: id
        type: uuid
        constraints:
        - primary_key
      - name: artist_id
        type: uuid
        constraints:
        - not_null
        - foreign_key
        references: artists.id
      - name: album_id
        type: uuid
        constraints:
        - nullable
        - foreign_key
        references: albums.id
      - name: title
        type: string
        constraints:
        - not_null
      - name: duration
        type: integer
        description: Duration in seconds
        constraints:
        - not_null
      - name: file_url
        type: string
        description: Cloud storage URL for audio file
        constraints:
        - not_null
      - name: file_format
        type: enum
        values:
        - mp3
        - wav
        constraints:
        - not_null
      - name: file_size
        type: integer
        description: File size in bytes
        constraints:
        - not_null
      - name: waveform_data
        type: jsonb
        description: Waveform visualization data
        constraints:
        - nullable
      - name: cover_art_url
        type: string
        constraints:
        - nullable
      - name: release_date
        type: date
        constraints:
        - nullable
      - name: play_count
        type: integer
        default: 0
      - name: is_public
        type: boolean
        default: true
      - name: track_number
        type: integer
        description: Position in album
        constraints:
        - nullable
      - name: created_at
        type: timestamp
        constraints:
        - not_null
      - name: updated_at
        type: timestamp
        constraints:
        - not_null
      relations:
      - type: belongs_to
        to: model_artist
        foreign_key: artist_id
      - type: belongs_to
        to: model_album
        foreign_key: album_id
        optional: true
      - type: has_many
        to: model_genre
        through: song_genres
        foreign_key: song_id
      - type: has_many
        to: model_playlist_song
        foreign_key: song_id
      indexes:
      - fields:
        - artist_id
      - fields:
        - album_id
      - fields:
        - release_date
      - fields:
        - play_count
      - fields:
        - is_public
      timestamps: true
  apis: []
  components: []
dependencies:
  entity_ids:
  - model_artist
  - model_album
  - model_song
  definitions:
  - id: model_artist
    type: model
    definition: *id001
  - id: model_album
    type: model
    definition: *id002
  - id: model_song
    type: model
    definition: *id003
files:
  to_create:
  - app/api/songs/id/route.ts
  reference: []
acceptance:
- criterion: GET /api/songs/:id returns success response
  verification: curl -X GET /api/songs/:id
- criterion: Request validation implemented
  verification: Test with invalid data
- criterion: Error responses match contract
  verification: Test error scenarios