GetCollaborations

Get Collaborations

Allows to retrieve Collaborations. This endpoint supports pagination and filtering.

Request

URL: /v1/collaborations

Method: GET

Path Parameters: None

Query Parameters:

Parameter	Type	Description	Requirement Type
offset	integer	Start offset of paginated results to retrieve. Default is 0.	Optional
limit	integer	Maximum number of paginated results to retrieve. Default is 25.	Optional
sortOrder	string	Sort order of the results based on createdAt field. Valid values are desc (newest first) and asc (oldest first). Default is asc.	Optional
inbound	boolean	Selects inbound collaborations (requestor is collaborator) or outbound (requestor is owner). Default is false.	Optional
ids	string list	Comma-separated list of Collaboration UUID's for filtering results. Prefix each value with - to exclude and + (optional) to include. Defaults to inclusion if no prefix is specified.	Optional
songIds	string list	Comma-separated list of Song UUID's for filtering results. Prefix each value with - to exclude and + (optional) to include. Defaults to inclusion if no prefix is specified.	Optional
emails	string list	Comma-separated list of Collaboration emails for filtering results. Prefix each value with - to exclude and + (optional) to include. Defaults to inclusion if no prefix is specified.	Optional
statuses	string list	Comma-separated list of Collaboration statuses for filtering results. Prefix each value with - to exclude and + (optional) to include. Defaults to inclusion if no prefix is specified.	Optional
olderThan	string	ISO-8601 formated oldest (maximum) timestamp to filter-out results. If missing, defaults to no filtering out.	Optional
newerThan	string	ISO-8601 formated newest (minimum) timestamp to filter-out results. If missing, defaults to no filtering out.	Optional

Headers:

Authorization: Bearer {accessToken}

Accept: application/json

✅ Success Response

Code: 200 OK

Headers:

Content-Type: application/json

Content:

Field	Type	Description	Condition
id	string	UUID of the Collaboration.	Always
createdAt	string	Date and time when the Collaboration was created (ISO-8601 format).	Always
songId	string	UUID of the underying Song.	Always
email	string	Email of the Collaborator.	Always
role	string	Collaborator role.	Only if available
royaltyRate	decimal	Percentage of total royalties owned to the Collaborator.	Only if available
credited	boolean	Indicates whether or not the Collaboration has been credited to the Collaborator.	Always
featured	boolean	Indicates whether or this Collaboration is for a featured Collaborator.	Always
status	string	Collaboation status. Valid values are: Editing, Waiting, Accepted & Rejected	Always

Content example:

[
    {
        "id": "7bd2862f-8deb-4814-8943-156d9dab80dd",
        "createdAt": "2022-04-22T20:47:55.738918",
        "songId": "842f5460-76f8-41d8-add9-d043a7a381de",
        "email": "[email protected]",
        "role": "Composer",
        "royaltyRate": 10.5,
        "credited": true,
        "featured": false,
        "status":"Waiting"
    },
    {
        "id": "5cd11788-4cc1-4768-b4fa-4c0f519a94c5",
        "createdAt": "2022-05-22T20:46:46.738741",
        "songId": "842f5460-76f8-41d8-add9-d043a7a381de",
        "email": "[email protected]",
        "role": "Backup Singer",
        "royaltyRate": 3.1,
        "credited": false,
        "featured": true,
        "status":"Accepted"
    }
]

❌ Error Responses

1. Unauthorized

Code: 401 UNAUTHORIZED

Condition: If {accessToken} is invalid or expired.

2. Unprocessable Entity

Code: 422 UNPROCESSABLE ENTITY

Condition: If any of the UUID query parameters is malformed.

Headers:

Content-Type: application/json

Content example:

{
    "code": 422,
    "description": "Unprocessable Entity",
    "cause": "Invalid UUID string: 123456789"
}

See Also

Post Collaboration (Add New Collaboration)

Patch Collaboration (Update Collaboration)

Get Collaboration

Get Collaboration Count

Delete Collaboration

Reply Collaboration

Get Collaborators

Get Collaborator Count