Composers API Documentation

Composers are the writers credited on tracks. Each belongs to one library and is addressed by your own external ID. A composer can also be created on the fly when uploading a track.

Endpoints

GET /api/v1/libraries/{library_id}/composers

Retrieve the composers in a library, ordered by external ID.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes

Query Parameters

Name	Type	Description
page	integer	Page number for pagination (default: 1)
per_page	integer	Records per page, up to 200 (default: 25)
q	string	List only the composers with this in their name, whatever its case

Response

{
    "pagination": {
        "total_entries": 10523,
        "per_page": 25,
        "current_page": 1,
        "total_pages": 421,
        "next_page": 2,
        "next_page_url": "https://app.spondulix.ai/api/v1/libraries/2/composers?page=2"
    },
    "composers": [
        {
            "id": 1,
            "library_id": 2,
            "name": "Ilze E. Platais",
            "birth_date": null,
            "death_date": null,
            "pro_id": 10,
            "ipi_number": 49448942,
            "created_at": "2024-08-19T13:30:26.166-05:00",
            "updated_at": "2024-08-19T13:36:56.251-05:00",
            "tracks_count": 10,
            "pro_abbreviation": "BMI",
            "url": "https://app.spondulix.ai/api/v1/libraries/2/composers/1",
            "tracks_url": "https://app.spondulix.ai/api/v1/libraries/2/composers/1/tracks"
        },
        {
            "id": 2,
            "library_id": 2,
            "name": "Neal Busby",
            "birth_date": null,
            "death_date": null,
            "pro_id": 101,
            "ipi_number": 229835933,
            "created_at": "2024-08-19T13:36:56.263-05:00",
            "updated_at": "2024-08-19T13:36:56.263-05:00",
            "tracks_count": 10,
            "pro_abbreviation": "BMI",
            "url": "https://app.spondulix.ai/api/v1/libraries/2/composers/2",
            "tracks_url": "https://app.spondulix.ai/api/v1/libraries/2/composers/2/tracks"
        }
    ]
}

Response Fields

Field	Type	Description
pagination	object	Contains pagination information
composers	array	List of composer objects
id	integer	Your external ID for the composer
library_id	integer	ID of the library the composer belongs to
name	string	Name of the composer
birth_date	string \| null	Birth date of the composer
death_date	string \| null	Death date of the composer
pro_id	integer \| null	ID of the composer’s PRO
ipi_number	integer \| null	IPI (Interested Parties Information) number
created_at	string	Timestamp of when the composer was created
updated_at	string	Timestamp of when the composer was last updated
tracks_count	integer	Number of tracks the composer is credited on
pro_abbreviation	string \| null	Abbreviation of the composer’s PRO
url	string	URL of the composer
tracks_url	string	URL of the composer’s tracks

HTTP Response Codes

Code	Description
`200 OK`	Successful request
`404 Not Found`	Invalid library ID

POST /api/v1/libraries/{library_id}/composers

Create a composer.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes

Request Body

Wrap the fields in a composer key.

Field	Type	Description	Required
external_id	integer	Your identifier for the composer, unique within the library	Yes
name	string	Name of the composer	Yes
birth_date	string (YYYY-MM-DD)	Birth date of the composer	No
death_date	string (YYYY-MM-DD)	Death date of the composer	No
pro_id	integer	ID of the composer’s PRO	No
ipi_number	integer	IPI (Interested Parties Information) number	No

{
    "composer": {
        "external_id": 125,
        "name": "Johann Sebastian Bach",
        "birth_date": "1685-03-31",
        "death_date": "1750-07-28",
        "pro_id": 35,
        "ipi_number": 116
    }
}

Response

Returns the created composer as shown in the list response.

HTTP Response Codes

Code	Description
`201 Created`	Successful creation
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID
`422 Unprocessable Content`	Invalid request (see response body for details)

POST /api/v1/libraries/{library_id}/composers/bulk

Create or update up to 1000 composers in one request. Each is what POST .../composers takes, with id accepted in place of external_id, and pro accepted in place of pro_id as the PRO’s abbreviation (in any case) or its ID. A composer whose id is already in the library is updated, and one whose id is not is created. Each stands or falls alone: one that fails is reported and the others are saved.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes

Request Body

Field	Type	Description	Required
composers	array	The composers, up to 1000, each with the fields `POST .../composers` takes	Yes

{
    "composers": [
        { "id": 125, "name": "Johann Sebastian Bach", "pro": "GEMA" },
        { "id": 126, "name": "" }
    ]
}

Response

{
    "created": 1,
    "updated": 0,
    "failures": [
        { "index": 1, "id": 126, "errors": { "name": ["can't be blank"] } }
    ]
}

Response Fields

Field	Type	Description
created	integer	Number of composers created
updated	integer	Number of composers updated
failures	array	The composers that were not saved; empty when all were
index	integer	Place of the composer in the list, counting from 0
id	integer \| null	The `id` it was sent with
errors	object	Field name to list of messages, as in a `422` from `POST .../composers`

HTTP Response Codes

Code	Description
`200 OK`	The request was understood. Some composers may have failed; see `failures`.
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID
`422 Unprocessable Content`	`composers` is missing, is not a list, or holds more than 1000

GET /api/v1/libraries/{library_id}/composers/{id}

Retrieve a composer.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	External ID of the composer	Yes

Response

{
    "id": 1,
    "library_id": 2,
    "name": "Ilze E. Platais",
    "birth_date": null,
    "death_date": null,
    "pro_id": 10,
    "ipi_number": 49448942,
    "created_at": "2024-08-19T13:30:26.166-05:00",
    "updated_at": "2024-08-19T13:36:56.251-05:00",
    "tracks_count": 10,
    "pro_abbreviation": "BMI",
    "url": "https://app.spondulix.ai/api/v1/libraries/2/composers/1",
    "tracks_url": "https://app.spondulix.ai/api/v1/libraries/2/composers/1/tracks"
}

HTTP Response Codes

Code	Description
`200 OK`	Successful request
`404 Not Found`	Invalid library ID or composer ID

PUT /api/v1/libraries/{library_id}/composers/{id}

Update a composer. PATCH works the same way, and only the fields you send change.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	External ID of the composer	Yes

Request Body

{
    "composer": {
        "name": "Updated Composer Name",
        "birth_date": "1990-01-01",
        "death_date": null,
        "pro_id": 20,
        "ipi_number": 123456789
    }
}

Response

Returns the updated composer.

HTTP Response Codes

Code	Description
`200 OK`	Successful update
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID or composer ID
`422 Unprocessable Content`	Invalid request (see response body for details)

DELETE /api/v1/libraries/{library_id}/composers/{id}

Delete a composer.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	External ID of the composer	Yes

Response

(no response body)

HTTP Response Codes

Code	Description
`204 No Content`	Successful deletion
`403 Forbidden`	Your role does not allow editing
`404 Not Found`	Invalid library ID or composer ID

GET /api/v1/libraries/{library_id}/composers/{id}/tracks

Retrieve the tracks the composer is credited on, ordered by title, each as the tracks endpoint gives it, under tracks.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	External ID of the composer	Yes

Query Parameters

Name	Type	Description
page	integer	Page number for pagination (default: 1)
per_page	integer	Records per page, up to 200 (default: 25)

Response

A list of tracks with a pagination object, as GET .../tracks returns.

HTTP Response Codes

Code	Description
`200 OK`	Successful request
`404 Not Found`	Invalid library ID or composer ID