POST v4/assets/:vbid/ancillaries

Ancillaries are files that "travel" with a DRMed book in 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.

Verb/URI
Data Definitions
Request Headers
Response
- Response body - default example
- Response descriptions
Error Codes

Verb/URI

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

Data Definitions

Name	Usage	Description	Data Type	Example	Required
vbid (asset_isbn)	URL Path Param Response	ISBN (VBID) of the asset that the ancillary is going to be uploaded against	String	L-999-70031	Yes
type	Param Response	Type of ancillary; URL or file. For a CompanionUrl only "URL" is acceptable here. For a downloadable_file only "file" is acceptable here	String	file, URL	Yes
url	Param Response	Ancillary URL (CompanionUrl)	String:1024	https://download_file.here	Yes, if CompanionURL
platform	Param Response	What platform this file works on (downloadable_file)	String:255	mac/windows \|\| mac \|\| windows	Yes, if downloadable
vbid	Param Response	Isbn of the asset that the ancillary belongs to	String	1231523134	No
id	Param Response	ID of the ancillary	Integer	55	No
display_order	Param Response	The order that the ancillary is displayed to the user (CompanionUrl \| downloadable_file)	Integer	1	No
title	Param Response	Title of the file (downloadable_file)	String:255	My_file	No
callback_url	Param 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	Param Response	If the ancillary is active	Boolean	True	No
file_size	Param Response	The size of the file	Integer	123	No
created_at	Param Response	The date the ancillary was created	Date	2014-11-20 19:14:30	No
updated_at	Param Response	The date the ancillary was last updated	Date	2014-11-20 19:14:30	No

Request Headers

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

Default example

Request body - CompanionURL

{
   "type": "url",
   "url": "www.example.com",
   "display_order": 1
}

Request body - Downloadable_fIle

{
  "type": "file",
  "title": "Title of file",
  "display_order": 2,
  "platform": "mac/windows"
}

Request body - upload_file

{
  "upload_file": @/path/to/file
}

Response

Response body - default example

{
  "isbn": "L-999-70031",
  "id": 12,
  "type": "CompanionUrl",
  "active": true,
  "title": "Title of file",
  "url": "www.example.com",
  "file_size": nil,
  "file_name": nil,
  "platform": mac/windows,
  "display_order": 2,
  "created_at": "2020-12-31 23:59:59",
  "updated_at": "2020-12-31 23:59:59"
}

Response descriptions

Name	Description
isbn	The VBID of the associated asset
id	ID of the ancillary. This will be returned in payload of 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	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
404	Not found	Verify POST create/update and VBID
422	Unprocessable Entity	Re-verify your request
500	Server Error