GET v4/assets/:vbid/ancillaries

Ancillaries are files that "travel" with a DRMed book within Bookshelf, but are not, themselves, under DRM. It's a way for a publisher to deliver additional materials with a given book. For example, a book about learning HTML might come with some JPGs and sample HTML files in a ZIP file. Or a book might come with videos.

Ancillary files are stored in a GCP bucket. A list of ancillaries for a given asset can be seen in VitalSource Manage.

Use this API to list all ancillaries attached to an asset (VBID) stored within VitalSource Manage.

Verb/URI
Data Definitions
Request Headers
- Request Header - get all example
- Request Header - get one ancillary example
Response
Error Codes

Verb/URI

GET https://api.vitalsource.com/v4/assets/:vbid/ancillaries

Data Definitions

Name	Usage	Description	Data Type	Example	Required
asset_isbn	URL Path Response	ISBN of the asset to which the ancillary is associated, expressed as a VBID.	String	L-999-70031	Yes
ancillaries	Response	A list of all the ancillaries for an asset	Array	[ { "isbn": "<asset-isbn>", "id": 12, "type": "URL", "active": true "title": nil, "URL": "www.example.com", "file_size": nil, "file_name": nil, "platform": nil, "display_order": 2, "created_at": "2020-11-20 19:14:30", "updated_at": "2020-11-20 20:14:30" } ]	No
ancillary_id	URL Path Response	The ID of the ancillary	Integer	55	Yes
isbn	Response	ISBN within VitalSource	String	L-999-70032	No
id	Response	ID of the ancillary	Integer	55	No
url	Response	Ancillary URL (CompanionUrl)	String:1024	https://downloadfile.here	No
display_order	Response	The order that the ancillary is displayed to the user (CompanionUrl \| DownloadableFile)	Integer	1	No
title	Response	Title of the file (DownloadableFile)	String:255	Myfile	No
platform	Response	What platform this file works on (DownloadableFile)	String:255	mac/windows \|\| mac \|\| windows	No
callback_url	Response	Url that should be called once the processing of the file is complete (success or failure). If this is not provided, then the callback URL of the parent asset will be used. Note that the callback URL is not persisted and will only override the parent asset callback URL for this request. This field is only available on the PUT request as that is where the file is actually uploaded.	String	https://callback.url	No
active	Response	If the ancillary is active	Boolean	True	No
file_size	Response	The size of the file	Integer	123	No
created_at	Response	The date the ancillary was created	Date	2014-11-20 19:14:30	No
updated_at	Response	The date the ancillary was last updated	Date	2014-11-20 19:14:30	No

Request Headers

X-VitalSource-API-Key: ABCDEFGHIJKLMNOP
Content-Type: application/json

Request Header - get all example

This request would return all ancillaries associated with an asset

GET https://api.vitalsource.com/v4/assets/:vbid/ancillaries

Request Header - get one ancillary example

This request would return one ancillary

GET https://api.vitalsource.com/v4/assets/:vbid/ancillaries/:ancillary_id

Response

Response Body - get all example

{
"ancillaries": [
    {
        "isbn": "VBID_HERE",
        "id": NUMBERS,
        "type": "DownloadableFile",
        "active": true,
        "title": "Test File 01",
        "url": "https://storage.googleapis.com/vst-manage-ancillaries-prod/VBID_HERE/Test File 01?GoogleAccesID=LOTSMORESTUFFHERE",
        "file_size": NUMBERS,
        "file_name": "something_01.pptx",
        "platform": "mac/windows",
        "display_order": 1,
        "callback_url": null,
        "created_at": "2020-01-01T00:00:00Z",
        "updated_at": "2020-07-01T00:00:00Z"
     },
     {
        "isbn": "VBID_HERE",
        "id": NUMBERS,
        "type": "DownloadableFile",
        "active": true,
        "title": "Test File 02",
        "url": "https://storage.googleapis.com/vst-manage-ancillaries-prod/VBID_HERE/Test File 02",
        "file_size": NUMBERS,
        "file_name": "something-02.pptx",
        "platform": "mac/windows",
        "display_order": 2,
        "callback_url": null,
        "created_at": "2020-01-01T00:00:00Z",
        "updated_at": "2020-07-01T00:00:00Z"
     },
  ],
"total_items": 2
}

Response Body - get one example

{
   "isbn": "VBID_HERE",
   "id": NUMBERS,
   "type": "DownloadableFile",
   "active": true,
   "title": "Test File 01",
   "url": "https://storage.googleapis.com/vst-manage-ancillaries-prod/VBID_HERE/Test File 01?GoogleAccesID=LOTSMORESTUFFHERE",
   "file_size": NUMBERS,
   "file_name": "something_01.pptx",
   "platform": "mac/windows",
   "display_order": 1,
   "callback_url": null,
   "created_at": "2020-01-01T00:00:00Z",
   "updated_at": "2020-07-01T00:00:00Z"
 }

Response descriptions

Name	Description
isbn	The VBID to the associated asset
id	The ID of the ancillary. This will be returned in the payload of the POST
type	File = DownloadableFile, URL = CompanionURL
active	True/False.
title	Title of the file (DownloadableFile)
url	Ancillary URL (CompanionUrl)
file_size	The size of the file
file_name	Name of the file
platform	What platform this file works on (DownloadableFile)
display_order	The order that the ancillary is displayed to the user (CompanionUrl \| DownloadableFile)
callback_url	Url that should be called once the processing of the file is complete (success or failure). If this is not provided, then the callback URL of the parent asset will be used. Note that the callback URL is not persisted and will only override the parent asset callback URL for this request. This field is only available on the PUT request as that is where the file is actually uploaded.
created_at	The date the ancillary was created
updated_at	The date the ancillary was last updated

Error Codes

HTTP & Error messages	Message	Notes
200	Ok
403	Forbidden	Possible distribution error. Verify you have rights to this VBID by doing v4/products/:vbid
404	Not found	Verify POST create/update and VBID
422	Unprocessable Entity	Re-verify your request
500	Server Error