PUT 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

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

Data Definitions

Name
Usage
Description
Data Type
Example
Required

vbid

(asset_isbn)

:check_mark: URL Path

:check_mark: Param

:check_mark: Response

ISBN (VBID) of the asset that the ancillary is going to be uploaded against

String

L-999-70031

Yes

type

:check_mark: Param

:check_mark: 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

:check_mark: Param

:check_mark: Response

Ancillary URL (CompanionUrl)

String:1024

https://download_file.here

Yes, if CompanionURL

platform

:check_mark: Param

:check_mark: Response

What platform this file works on (downloadable_file)

String:255

mac/windows || mac || windows

Yes, if downloadable

isbn

:cross_mark: Param

:check_mark: Response

Isbn of the asset that the ancillary belongs to

String

1231523134

No

id

:cross_mark: Param

:check_mark: Response

ID of the ancillary

Integer

55

No

display_order

:check_mark: Param

:check_mark: Response

The order that the ancillary is displayed to the user (CompanionUrl | downloadable_file)

Integer

1

No

title

:check_mark: Param

:check_mark: Response

Title of the file (downloadable_file)

String:255

My_file

No

callback_url

:check_mark: Param

:check_mark: 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

:cross_mark: Param

:check_mark: Response

If the ancillary is active

Boolean

True

No

file_size

:cross_mark: Param

:check_mark: Response

The size of the file

Integer

123

No

created_at

:cross_mark: Param

:check_mark: Response

The date the ancillary was created

Date

2014-11-20 19:14:30

No

updated_at

:cross_mark: Param

:check_mark: 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

 
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.