PostCollaboration

Post Collaboration

Allows to add a new Collaboration. This operation is only allowed when the requestor is the specified Song owner and the Song's mintingStatus is Undistributed.

Request

URL: /v1/collaborations

Method: POST

Path Parameters: None

Query Parameters: None

Headers:

Authorization: Bearer {accessToken}

Content-Type: application/json

Content:

Field	Type	Description	Requirement Type
songId	string	UUID of the Song.	Required
email	string	Email of the Collaborator.	Required
roles	string array	Collaborator roles.	Optional
royaltyRate	decimal	Percentage of total royalties owned to the Collaborator.	Optional
credited	boolean	Indicates whether or this Collaboration shoud be credited to the Collaborator.	Optional
featured	boolean	Indicates whether or this Collaboration is for a featured Collaborator.	Optional

Content example:

{
    "songId": "7bd2862f-8deb-4814-8943-156d9dab80dd",
    "email": "john.doe@email.com",
    "roles": ["Artist", "Producer"],
    "royaltyRate": 10.5,
    "credited": true,
    "featured": true
}

✅ Success Response

Code: 200 OK

Headers:

Content-Type: application/json

Content:

Field	Type	Description	Condition
collaborationId	string	UUID of the added Collaboration.	Always

Content example:

{
    "collaborationId": "46550a07-31f3-48b1-8e12-b7c2a9fcde93"
}

❌ Error Responses

1. Unauthorized

Code: 401 UNAUTHORIZED

Condition: If {accessToken} is invalid or expired.

2. Forbidden

Code: 403 FORBIDDEN

Condition: If the requestor is not the Song owner.

Headers:

Content-Type: application/json

Content example:

{
    "code": 403,
    "description": "Forbidden",
    "cause": "Operation allowed only by owner"
}

3. Not Found

Code: 404 NOT FOUND

Condition: If the specified Song (by songId) is not found.

Headers:

Content-Type: application/json

Content example:

{
    "code": 404,
    "description": "Not Found",
    "cause": "Entity SonglistEntity, id=d0907e3d-a9a7-43b1-93dc-f3b0ee929021 not found in the database"
}

4. Conflict

Code: 409 CONFLICT

Condition: If email was already used in another collaboration on the same song.

Headers:

Content-Type: application/json

Content example:

{
    "code": 409,
    "description": "Conflict",
    "cause": "Collaboration already exists: songId = a1031b4b-144e-4b97-93aa-d58e2c5c245f, email = john.doe@gmail.com"
}

5. Unprocessable Entity

Code: 422 UNPROCESSABLE ENTITY

Condition: If any field is malformed, exceeds maximum length allowed or operation attempted when mintingStatus is other thanUndistributed.

Headers:

Content-Type: application/json

Content example:

{
    "code": 422,
    "description": "Unprocessable Entity",
    "cause": "Operation only allowed when mintingStatus = Undistributed"
}

See Also

Patch Collaboration (Update Collaboration)

Get Collaboration

Get Collaborations

Get Collaboration Count

Delete Collaboration

Reply Collaboration

Get Collaborators

Get Collaborator Count