Record¶
A record holds the FLAC master audio file associated with a track (creator), together with the technical metadata derived from it (bit depth, file size, codec details, MD5). Create as many records as there are tracks in the product. Provide the audio either as base64 bytes (new-file) or as a source URL (original-url).
Lists Records¶
GET https://domain.com/api/v1/records
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Response — 200 OK
{
"data": [
{
"type": "records",
"id": "<ID>",
"attributes": {
"md5": "9e8b67a6c8329fc4d905b5cc7821ec05",
"original-url": null,
"precision": 24,
"master-type": "cd",
"profile": null,
"file-size": 7022334,
"filename": "track_flac_24_48000_2.flac",
"file": {
"codec": "flac",
"channels": 2,
"duration": "1.660229",
"codec_type": "audio",
"mime_type": "audio/flac",
"bitrate": "18345",
"lossless": true,
"compression_ratio": "0.62",
"bitrate_mode": "vbr",
"duration_ts": 79691,
"sample_rate": "48000",
"channel_layout": "stereo",
"bits_per_raw_sample": "24"
},
"createdAt": "2023-08-11T20:45:23.000000Z",
"updatedAt": "2023-08-11T20:45:23.000000Z"
},
"relationships": {
"creator": {
"links": {
"related": "https://domain.com/api/v1/records/<ID>/creator",
"self": "https://domain.com/api/v1/records/<ID>/relationships/creator"
}
}
},
"links": {
"self": "https://domain.com/api/v1/records/<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/records?page[number]=1&page[size]=20",
"last": "https://domain.com/api/v1/records?page[number]=1&page[size]=20"
}
}
Filters¶
| Filter | Example |
|---|---|
| ID | /records?filter[id]=1 |
| Track ID | /records?filter[track-id]=42 |
Get Record¶
GET https://domain.com/api/v1/records/:id
Path Parameters¶
| Name | Type | Description |
|---|---|---|
| id* | Number | Record ID |
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Response — 200 OK
{
"data": {
"type": "records",
"id": "<ID>",
"attributes": {
"md5": "9e8b67a6c8329fc4d905b5cc5521ec05",
"original-url": null,
"precision": 24,
"master-type": "cd",
"profile": null,
"file-size": 342345,
"filename": "track_flac_24_48000_2.flac",
"file": {
"codec": "flac",
"channels": 2,
"duration": "1.660229",
"codec_type": "audio",
"mime_type": "audio/flac",
"bitrate": "18345",
"lossless": true,
"compression_ratio": "0.62",
"bitrate_mode": "vbr",
"duration_ts": 79691,
"sample_rate": "48000",
"channel_layout": "stereo",
"bits_per_raw_sample": "24"
},
"createdAt": "2023-08-11T20:45:23.000000Z",
"updatedAt": "2023-08-11T20:45:23.000000Z"
},
"relationships": {
"creator": {
"links": {
"related": "https://domain.com/api/v1/records/<ID>/creator",
"self": "https://domain.com/api/v1/records/<ID>/relationships/creator"
}
}
},
"links": {
"self": "https://domain.com/api/v1/records/<ID>"
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://domain.com/api/v1/records/<ID>"
}
}
Create Record¶
POST https://domain.com/api/v1/records
Provide the audio with either new-file (base64 bytes) or original-url (source URL) — use one or the other, not both. The audio must be FLAC, with a sample rate of at least 44000 Hz and a bit depth of 16 or 24. md5, precision, file-size, filename and file are computed server-side.
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Request Body¶
| Name | Type | Description |
|---|---|---|
| creator* | Object | Track resource (relationship) |
| new-file | String | Base64-encoded audio bytes, e.g. ZkxhQwAAA.... Use this or original-url, not both |
| original-url | String | URL of the source file. Use this or new-file, not both |
Response — 201 Created
{
"data": {
"type": "records",
"id": "<ID>",
"attributes": {
"md5": "9e8b67a6c8329fc4d905b5cc5521ec05",
"original-url": null,
"precision": 24,
"master-type": "cd",
"profile": null,
"file-size": 342345,
"filename": "track_flac_24_48000_2.flac",
"file": {
"codec": "flac",
"channels": 2,
"duration": "1.660229",
"codec_type": "audio",
"mime_type": "audio/flac",
"bitrate": "18345",
"lossless": true,
"compression_ratio": "0.62",
"bitrate_mode": "vbr",
"duration_ts": 79691,
"sample_rate": "48000",
"channel_layout": "stereo",
"bits_per_raw_sample": "24"
},
"createdAt": "2023-08-11T20:45:23.000000Z",
"updatedAt": "2023-08-11T20:45:23.000000Z"
},
"relationships": {
"creator": {
"links": {
"related": "https://domain.com/api/v1/records/<ID>/creator",
"self": "https://domain.com/api/v1/records/<ID>/relationships/creator"
}
}
},
"links": {
"self": "https://domain.com/api/v1/records/<ID>"
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://domain.com/api/v1/records/<ID>"
}
}
Response — 422 Unprocessable Entity
{
"jsonapi": {
"version": "1.0"
},
"errors": [
{
"detail": "The creator field is required.",
"source": {
"pointer": "/data/relationships/creator"
},
"status": "422",
"title": "Unprocessable Entity"
}
]
}
Update Record¶
PATCH https://domain.com/api/v1/records/:id
Path Parameters¶
| Name | Type | Description |
|---|---|---|
| id* | Number | Record ID |
Headers¶
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer \ |
| Content-Type* | String | application/vnd.api+json |
Request Body¶
| Name | Type | Description |
|---|---|---|
| new-file | String | Base64-encoded audio bytes. Use this or original-url, not both |
| original-url | String | URL of the source file. Use this or new-file, not both |
| creator | Object | Track resource (relationship) |
Response — 200 OK
{
"data": {
"type": "records",
"id": "<ID>",
"attributes": {
"md5": "9e8b67a6c8329fc4d905b5cc5521ec05",
"original-url": null,
"precision": 24,
"master-type": "cd",
"profile": null,
"file-size": 342345,
"filename": "track_flac_24_48000_2.flac",
"file": {
"codec": "flac",
"channels": 2,
"duration": "1.660229",
"codec_type": "audio",
"mime_type": "audio/flac",
"bitrate": "18345",
"lossless": true,
"compression_ratio": "0.62",
"bitrate_mode": "vbr",
"duration_ts": 79691,
"sample_rate": "48000",
"channel_layout": "stereo",
"bits_per_raw_sample": "24"
},
"createdAt": "2023-08-11T20:45:23.000000Z",
"updatedAt": "2023-08-11T20:45:23.000000Z"
},
"relationships": {
"creator": {
"links": {
"related": "https://domain.com/api/v1/records/<ID>/creator",
"self": "https://domain.com/api/v1/records/<ID>/relationships/creator"
}
}
},
"links": {
"self": "https://domain.com/api/v1/records/<ID>"
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://domain.com/api/v1/records/<ID>"
}
}
Delete Record¶
DELETE https://domain.com/api/v1/records/:id
Path Parameters¶
| Name | Type | Description |
|---|---|---|
| id* | Number | Record 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