Publishers API Documentation

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

Endpoints

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

Retrieve the publishers 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 publishers with this in their name, whatever its case

Response

{
    "pagination": {
        "total_entries": 25,
        "per_page": 25,
        "current_page": 1,
        "total_pages": 1
    },
    "publishers": [
        {
            "id": 1,
            "library_id": 2,
            "name": "Mike's Awesome Music",
            "pro_id": 10,
            "ipi_number": 292898239823,
            "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/publishers/1",
            "tracks_url": "https://app.spondulix.ai/api/v1/libraries/2/publishers/1/tracks"
        }
    ]
}

Response Fields

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

HTTP Response Codes

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

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

Create a publisher.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes

Request Body

Wrap the fields in a publisher key.

Field	Type	Description	Required
external_id	integer	Your identifier for the publisher, unique within the library	Yes
name	string	Name of the publisher	Yes
pro_id	integer	ID of the publisher’s PRO	No
ipi_number	integer	IPI (Interested Parties Information) number	No

{
    "publisher": {
        "external_id": 12,
        "name": "Mike's Awesome Music",
        "pro_id": 21,
        "ipi_number": 2389239892
    }
}

Response

Returns the created publisher 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}/publishers/bulk

Create or update up to 1000 publishers in one request. Each is what POST .../publishers 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 publisher 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
publishers	array	The publishers, up to 1000, each with the fields `POST .../publishers` takes	Yes

{
    "publishers": [
        { "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 publishers created
updated	integer	Number of publishers updated
failures	array	The publishers that were not saved; empty when all were
index	integer	Place of the publisher 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 .../publishers`

HTTP Response Codes

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

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

Retrieve a publisher.

Path Parameters

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

Response

{
    "id": 1,
    "library_id": 2,
    "name": "Mike's Awesome Music",
    "pro_id": 10,
    "ipi_number": 292898239823,
    "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/publishers/1",
    "tracks_url": "https://app.spondulix.ai/api/v1/libraries/2/publishers/1/tracks"
}

HTTP Response Codes

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

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

Update a publisher. 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 publisher	Yes

Request Body

{
    "publisher": {
        "name": "Updated Publisher Name",
        "pro_id": 20,
        "ipi_number": 123456789
    }
}

Response

Returns the updated publisher.

HTTP Response Codes

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

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

Delete a publisher.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes
id	integer	External ID of the publisher	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 publisher ID

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

Retrieve the tracks the publisher 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 publisher	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 publisher ID