Product¶
A product is the central release entity (album, single, EP, etc.). It carries the release metadata, cover art and contributor credits, and is linked to a label, language and product type.
Lists Products¶
GET https://domain.com/api/v1/products
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Response — 200 OK
{
"data": [
{
"type": "products",
"id": "<ID>",
"attributes": {
"name": "product name",
"is-compilation": false,
"upc-code": "8445281840433",
"copyright-line": "Records Music",
"production-line": "2023 Records Music",
"production-year": 2023,
"status": "active",
"cover-url": "https://domain.com/storage/covers/0adc8b96-be2d-4b9c-a35b-5d27230736e7.jpg",
"release-date": "2023-10-01T00:00:00.000000Z",
"original-release-date": null,
"mastered-by": null,
"label-internal-reference": null,
"subtitle": null,
"front-cover-md5": "b6d038d3da8a454b30b17c007aa001e8",
"artist": ["artist"],
"composer": null,
"producer": null,
"featuring": null,
"remixer": null,
"author": null,
"lyricist": null,
"performer": null,
"arranger": null,
"orchestra": null,
"director": null,
"custom-data": null,
"createdAt": "2023-08-11T20:45:10.000000Z",
"updatedAt": "2023-08-11T20:46:58.000000Z"
},
"relationships": {
"company": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/company",
"self": "https://domain.com/api/v1/products/<ID>/relationships/company"
}
},
"label": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/label",
"self": "https://domain.com/api/v1/products/<ID>/relationships/label"
}
},
"product-type": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/product-type",
"self": "https://domain.com/api/v1/products/<ID>/relationships/product-type"
}
},
"language": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/language",
"self": "https://domain.com/api/v1/products/<ID>/relationships/language"
}
},
"offers": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/offers",
"self": "https://domain.com/api/v1/products/<ID>/relationships/offers"
}
},
"tracks": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/tracks",
"self": "https://domain.com/api/v1/products/<ID>/relationships/tracks"
}
},
"rights": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/rights",
"self": "https://domain.com/api/v1/products/<ID>/relationships/rights"
}
}
},
"links": {
"self": "https://domain.com/api/v1/products/<ID>"
}
}
],
"meta": {
"page": {
"currentPage": 1,
"from": 1,
"lastPage": 1,
"perPage": 20,
"to": 1,
"total": 1
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"first": "https://domain.com/api/v1/products?page[number]=1&page[size]=20",
"last": "https://domain.com/api/v1/products?page[number]=1&page[size]=20"
}
}
Filters¶
| Filter | Example |
|---|---|
| Name | /products?filter[name]=Product title |
| Status | /products?filter[status]=draft |
| ID | /products?filter[id]=1 |
| Label ID | /products?filter[label-id]=5 |
| UPC code | /products?filter[upc-code]=8088111222333 |
| Created after | /products?filter[created-at-gte]=2024-01-01 |
| Created before | /products?filter[created-at-lte]=2024-12-31 |
| Has send tasks | /products?filter[has-send-tasks]=true |
Get Product¶
GET https://domain.com/api/v1/products/:id
Path Parameters¶
| Name | Type | Description |
|---|---|---|
| id* | Number | Product ID |
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Response — 200 OK
{
"data": {
"type": "products",
"id": "<ID>",
"attributes": {
"name": "Product title",
"is-compilation": false,
"upc-code": "8088111222333",
"copyright-line": "Records Music",
"production-line": "2023 Records Music",
"production-year": 2023,
"status": "draft",
"cover-url": null,
"release-date": null,
"original-release-date": null,
"mastered-by": null,
"label-internal-reference": null,
"subtitle": null,
"front-cover-md5": null,
"artist": ["Artist name"],
"composer": null,
"producer": null,
"featuring": null,
"remixer": null,
"author": null,
"lyricist": null,
"performer": null,
"arranger": null,
"orchestra": null,
"director": null,
"custom-data": null,
"createdAt": "2023-08-12T16:06:21.000000Z",
"updatedAt": "2023-08-12T16:06:21.000000Z"
},
"relationships": {
"company": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/company",
"self": "https://domain.com/api/v1/products/<ID>/relationships/company"
}
},
"label": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/label",
"self": "https://domain.com/api/v1/products/<ID>/relationships/label"
}
},
"product-type": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/product-type",
"self": "https://domain.com/api/v1/products/<ID>/relationships/product-type"
}
},
"language": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/language",
"self": "https://domain.com/api/v1/products/<ID>/relationships/language"
}
},
"offers": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/offers",
"self": "https://domain.com/api/v1/products/<ID>/relationships/offers"
}
},
"tracks": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/tracks",
"self": "https://domain.com/api/v1/products/<ID>/relationships/tracks"
}
},
"rights": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/rights",
"self": "https://domain.com/api/v1/products/<ID>/relationships/rights"
}
}
},
"links": {
"self": "https://domain.com/api/v1/products/<ID>"
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://domain.com/api/v1/products/<ID>"
}
}
Create Product¶
POST https://domain.com/api/v1/products
A product must be associated with a label, and declares its language (and optionally its product type). On creation the status must be draft.
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Request Body¶
| Name | Type | Required | Description |
|---|---|---|---|
| name | String | Yes | Product title |
| upc-code | String | Yes | UPC code |
| copyright-line | String | Yes | e.g. © 2023 Records Music |
| production-line | String | Yes | e.g. ℗ 2023 Records Music |
| production-year | Number | Yes | e.g. 2023 |
| status | String | Yes | Must be draft on create |
| artist | Array | Yes | e.g. ["Artist name"] |
| label | Object | Yes | Label resource (relationship) |
| language | Object | Yes | Language resource (relationship) |
| is-compilation | Boolean | No | Whether the product is a compilation |
| front-cover | String | No | Base64-encoded cover image, e.g. data:image/jpeg;base64,/9j/... (the resulting URL is returned as cover-url) |
| release-date | String | No | e.g. 2023-10-01 |
| original-release-date | String | No | e.g. 2023-10-01 |
| subtitle | String | No | Product subtitle / version |
| mastered-by | String | No | Mastering engineer |
| label-internal-reference | String | No | Internal reference used by the label |
| composer | Array | No | e.g. ["Composer name"] |
| producer | Array | No | e.g. ["Producer name"] |
| featuring | Array | No | e.g. ["Featured name"] |
| remixer | Array | No | e.g. ["Remixer name"] |
| author | Array | No | e.g. ["Author name"] |
| lyricist | Array | No | e.g. ["Lyricist name"] |
| performer | Array | No | e.g. ["Performer name"] |
| arranger | Array | No | e.g. ["Arranger name"] |
| orchestra | Array | No | e.g. ["Orchestra name"] |
| director | Array | No | e.g. ["Director name"] |
| custom-data | Array | No | Custom metadata |
| product-type | Object | No | Product-type resource (relationship) |
Response — 201 Created
{
"data": {
"type": "products",
"id": "<ID>",
"attributes": {
"name": "Product title",
"is-compilation": false,
"upc-code": "8088111222333",
"copyright-line": "Records Music",
"production-line": "2023 Records Music",
"production-year": 2023,
"status": "draft",
"cover-url": null,
"release-date": null,
"original-release-date": null,
"mastered-by": null,
"label-internal-reference": null,
"subtitle": null,
"front-cover-md5": null,
"artist": ["Artist name"],
"composer": null,
"producer": null,
"featuring": null,
"remixer": null,
"author": null,
"lyricist": null,
"performer": null,
"arranger": null,
"orchestra": null,
"director": null,
"custom-data": null,
"createdAt": "2023-08-12T16:06:21.000000Z",
"updatedAt": "2023-08-12T16:06:21.000000Z"
},
"relationships": {
"company": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/company",
"self": "https://domain.com/api/v1/products/<ID>/relationships/company"
}
},
"label": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/label",
"self": "https://domain.com/api/v1/products/<ID>/relationships/label"
}
},
"product-type": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/product-type",
"self": "https://domain.com/api/v1/products/<ID>/relationships/product-type"
}
},
"language": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/language",
"self": "https://domain.com/api/v1/products/<ID>/relationships/language"
}
}
},
"links": {
"self": "https://domain.com/api/v1/products/<ID>"
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://domain.com/api/v1/products/<ID>"
}
}
Response — 422 Unprocessable Entity
{
"jsonapi": {
"version": "1.0"
},
"errors": [
{
"detail": "The name field is required.",
"source": {
"pointer": "/data/attributes/name"
},
"status": "422",
"title": "Unprocessable Entity"
},
{
"detail": "The upc-code field is required.",
"source": {
"pointer": "/data/attributes/upc-code"
},
"status": "422",
"title": "Unprocessable Entity"
}
]
}
Update Product¶
PATCH https://domain.com/api/v1/products/:id
Accepts the same writable attributes as Create (all optional on update). On update, status may be draft, active or archived.
Path Parameters¶
| Name | Type | Description |
|---|---|---|
| id* | Number | Product ID |
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Request Body¶
| Name | Type | Required | Description |
|---|---|---|---|
| name | String | No | Product title |
| status | String | No | draft / active / archived |
| release-date | String | No | e.g. 2023-10-01 |
| front-cover | String | No | Base64-encoded cover image |
Response — 200 OK
{
"data": {
"type": "products",
"id": "<ID>",
"attributes": {
"name": "Product title",
"is-compilation": false,
"upc-code": "8088111222333",
"copyright-line": "Records Music",
"production-line": "2023 Records Music",
"production-year": 2023,
"status": "active",
"cover-url": "https://domain.com/storage/covers/7eaeb210-cb4d-453a-a646-7a60787fdb25.jpg",
"release-date": "2023-10-01T00:00:00.000000Z",
"original-release-date": null,
"mastered-by": null,
"label-internal-reference": null,
"subtitle": null,
"front-cover-md5": null,
"artist": ["Artist name"],
"composer": null,
"producer": null,
"featuring": null,
"remixer": null,
"author": null,
"lyricist": null,
"performer": null,
"arranger": null,
"orchestra": null,
"director": null,
"custom-data": null,
"createdAt": "2023-08-12T16:06:21.000000Z",
"updatedAt": "2023-08-12T16:10:00.000000Z"
},
"relationships": {
"company": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/company",
"self": "https://domain.com/api/v1/products/<ID>/relationships/company"
}
},
"label": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/label",
"self": "https://domain.com/api/v1/products/<ID>/relationships/label"
}
},
"product-type": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/product-type",
"self": "https://domain.com/api/v1/products/<ID>/relationships/product-type"
}
},
"language": {
"links": {
"related": "https://domain.com/api/v1/products/<ID>/language",
"self": "https://domain.com/api/v1/products/<ID>/relationships/language"
}
}
},
"links": {
"self": "https://domain.com/api/v1/products/<ID>"
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://domain.com/api/v1/products/<ID>"
}
}
Delete Product¶
DELETE https://domain.com/api/v1/products/:id
A product with status = active cannot be deleted.
Path Parameters¶
| Name | Type | Description |
|---|---|---|
| id* | Number | Product ID |
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Response — 204 No Content (delete OK, empty body)
Response — 404 Not Found