task_id: task_create_api_respond_to_invitation
entity_id: api_respond_to_invitation
generated_at: '2025-12-18T17:43:33.718125'
workflow_version: v003
target:
  type: api
  definition:
    id: api_respond_to_invitation
    method: POST
    path: /api/artists/[id]/invitations/[invitationId]/respond
    summary: Respond to invitation
    description: Accept or decline a label invitation
    tags:
    - artists
    - invitations
    path_params:
    - name: id
      type: string
      description: Artist ID
    - name: invitationId
      type: string
      description: Invitation ID
    request_body:
      content_type: application/json
      schema:
        type: object
        properties:
        - name: response
          type: string
          required: true
          description: Accept or decline (accept/decline)
    responses:
    - status: 200
      description: Response recorded
      schema:
        type: object
        properties:
        - name: status
          type: string
        - name: label
          type: object
    - status: 400
      description: Invalid response or invitation already processed
    - status: 401
      description: Unauthorized
    - status: 403
      description: Not the invited artist
    - status: 404
      description: Invitation not found
    depends_on_models:
    - model_label_invitation
    depends_on_apis: []
    auth:
      required: true
      roles:
      - artist
related:
  models:
  - id: model_label_invitation
    definition: &id001
      id: model_label_invitation
      name: LabelInvitation
      description: Invitations from labels to artists to join their roster
      table_name: label_invitations
      fields:
      - name: id
        type: uuid
        constraints:
        - primary_key
        description: Unique identifier
      - name: labelId
        type: uuid
        constraints:
        - foreign_key
        - not_null
        - indexed
        description: Reference to the inviting label (FK to labels table)
      - name: artistId
        type: uuid
        constraints:
        - foreign_key
        - not_null
        - indexed
        description: Reference to the invited artist (FK to artists table)
      - name: status
        type: enum
        enum_values:
        - pending
        - accepted
        - declined
        - expired
        constraints:
        - not_null
        - default
        default: pending
        description: Current status of the invitation
      - name: message
        type: text
        constraints: []
        description: Optional message from label to artist
      - name: expiresAt
        type: datetime
        constraints:
        - not_null
        description: When the invitation expires
      - name: createdAt
        type: datetime
        constraints:
        - not_null
        description: When invitation was created
      - name: updatedAt
        type: datetime
        constraints:
        - not_null
        description: When invitation was last updated
      relations: []
      indexes:
      - fields:
        - labelId
        - artistId
        unique: true
        name: label_artist_unique
      - fields:
        - artistId
        - status
        unique: false
        name: artist_pending_invitations
      timestamps: true
      soft_delete: false
      validations:
      - field: expiresAt
        rule: future_date
        message: Expiration date must be in the future
  apis: []
  components: []
dependencies:
  entity_ids:
  - model_label_invitation
  definitions:
  - id: model_label_invitation
    type: model
    definition: *id001
files:
  to_create:
  - app/api/artists/[id]/invitations/[invitationId]/respond/route.ts
  reference: []
acceptance:
- criterion: POST /api/artists/[id]/invitations/[invitationId]/respond returns success
    response
  verification: curl -X POST /api/artists/[id]/invitations/[invitationId]/respond
- criterion: Request validation implemented
  verification: Test with invalid data
- criterion: Error responses match contract
  verification: Test error scenarios