1. Overview

The Bookshare API v2 for Collection Management provides clients endpoints for Collection Assistant users to manage the set of titles which are part of their Site. The same conventions and general rules for API use apply here as they do to the public API for Bookshare users.

Collection Assistants are typically allowed to update properties of titles, both for titles that are visible to members and titles that have either been withdrawn, or are still being prepared for use. They can also see additional properties of titles, and have access to event history to see what processing has been done to a title. As part of their work to help bring titles into the collection, they will also have access to different stages in the processing pipeline as they work with publishers and other title providers to bring new content to the collection.

2. Resources

2.1. Collection Assistant - Titles

Administrative users have resources available that will let them manage the collection, either by adding or removing titles, or by manipulating their metadata. This could include withdrawing live titles, publishing pending titles, or reviewing proofread scans. Collection Assistants can perform these functions, only restricted to the titles that are associated with their site.

2.1.1. Submit metadata for new title

POST /v2/titles
Description

Submit metadata for a new title to the collection.

Parameters
Type Name Description Schema

FormData

title
required

Main title of the book or reading material.

string

FormData

subtitle
optional

Subtitle of the book or reading material.

string

FormData

isbn13
required

ISBN of the book or reading material. This can be either ISBN-10 or ISBN-13, but it will be converted to ISBN-13. Required if synopsis is not provided.

string

FormData

authors
required

Author names for the title. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

abridgers
optional

People named as 'abridged by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

adapters
optional

People named as 'adapted by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

arrangers
optional

People named as 'arranged by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

composers
optional

People named as 'composer' of a musical score. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

coWriters
optional

People named as 'written with'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

editors
optional

People named as 'editor' or 'edited by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

epilogueBys
optional

People named as 'epilogue by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

forewardBys
optional

People named as 'foreward by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

introductionBys
optional

People named as 'introduction by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

lyricists
optional

People named as 'lyricist' of a musical score. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

transcribers
optional

People named as 'transcriber' of a Braille title. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

translators
optional

People named as 'translated by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

synopsis
required

Descriptive summary of the title. Required if ISBN is not provided.

string

FormData

seriesTitle
optional

Title of the series to which the book belongs, if applicable.

string

FormData

seriesSubtitle
optional

Subtitle of the series to which the book belongs, if applicable.

string

FormData

seriesNumber
optional

Number of the book within the series to which it belongs.

string

FormData

copyrightHolder
optional

The copyright owner of the book or reading material. Required if usageRestriction is 'copyright'

string

FormData

copyrightDate
optional

The copyright year of the book or reading material. Required if usageRestriction is 'copyright'

integer

FormData

edition
optional

The edition name, if any, of the title.

string

FormData

readingAgeMinimum
optional

The minimum reading age for which the content is recommended.

integer

FormData

readingAgeMaximum
optional

The maximum reading age for which the content is recommended.

integer

FormData

adultContent
optional

True if the title contains adult content.

boolean

FormData

allowRecommend
optional

True if the title should be a candidate for the recommendation engine.

boolean

FormData

numPages
optional

Number of pages in this title.

integer

FormData

publisher
optional

The publisher of the book or reading material.

string

FormData

categories
required

Bookshare categories to which the title belongs. For choices, see the category listing endpoint. Enter each category as a separate instance of this parameter.

< string > array(multi)

FormData

countries
required

Countries to which this title is restricted for distribution. The values should be a two-character ISO 3166 alpha-2 country code. Enter each country as a separate instance of this parameter.

< string > array(multi)

FormData

languages
required

Languages of the title. The value will be a three-character ISO 639-2 alpha-3 language code. Enter each language as a separate instance of this parameter.

< string > array(multi)

FormData

grades
optional

Code value of the grades for which the content is appropriate. Values are from ONIX codelist 77 for US grades, BIC for UK grades. Enter each grade as a separate instance of this parameter.

< string > array(multi)

FormData

contentWarnings
optional

Content warnings attached to the title. Enter each content warning as a separate instance of this parameter.

< enum (contentWarning, sex, violence, drugs, language, intolerance, adult, unrated) > array(multi)

FormData

relatedIsbns
optional

ISBNs of other formats or renderings of the title. Enter each ISBN as a separate instance of this parameter.

< string > array(multi)

FormData

usageRestriction
required

Usage restriction on the title, in terms of licensing.

enum (copyright, publicDomain, creativeCommons)

FormData

externalCategoryCode
optional

A code that maps to a category scheme in an external system. This can be used to track categories that Bookshare does not recognize.

string

FormData

musicScoreType
optional

If the content is a music score, the type of score it represents.

enum (fullScore, openScore, singleLine)

FormData

hasChordSymbols
optional

If the content is a music score, true if the content includes musical chord symbols.

boolean

FormData

instruments
optional

If the content is a music score, the names of any musical instruments that it covers.

string

FormData

key
optional

If the content is a music score, the musical key in which the score is written.

string

FormData

movementNumber
optional

If the content is a music score, the descriptive number of the musical movement.

string

FormData

movementTitle
optional

If the content is a music score, the descriptive title of the movement.

string

FormData

opus
optional

If the content is a music score, the descriptive number of the opus.

string

FormData

vocalParts
optional

If the content is a vocal score, the letters representing the vocal parts it covers. This can be some combination of the letters S, A, T and B.

string

FormData

notes
optional

Text to place in the metadata record of the title, describing particular features of the title for other Collection Assistants to see.

string

FormData

marrakeshEligible
optional

True if the title would be eligible to be shared with qualifying Marrakesh Treaty countries when the title’s country of origin has implemented the Marrakesh Treaty.

boolean

FormData

marrakeshPODException
optional

True if the title has a Marrakesh Proof of Disability exception.

boolean

FormData

userAvailabilities
optional

Defines a restriction of a title to a set of users or groups of users to whom it should be available.

< enum (AVAILABLE_TO_DEMO, NIMAC) > array(multi)

FormData

availableToDemo
optional

True if the title is available to download by special user accounts set up for demonstration purposes.

boolean

FormData

availableWorldwide
optional

True if the title is available to users in any country.

boolean

FormData

states
optional

States to which this title is restricted for distribution. The value should be either a two-character postal abbreviation or an ISO 3166-2 subdivision code for the country. This field is only relevant for subdivisions of the US and Canada. Enter each state as a separate instance of this parameter.

< string > array(multi)

FormData

contentType
required

General type of content found in this title.

enum (text, musicScore)

FormData

comments
optional

Text to place in the history of updates to the title, describing how or why the current changes are being made.

string

FormData

hasEmbeddedImageDescriptions
optional

True if the title has the image description in the text content, rather than in standard XML or HTML markup.

boolean

FormData

quality
optional

Rating of how well the title reflects the content and structure of the original material.

enum (publisher, excellent, good, fair)

FormData

originCountry
optional

The origin country of the title. The value should be a two-character ISO 3166 alpha-2 country code.

string

FormData

productIdentifier
optional

Unique identifier of the title within the collection. This could be a standard identifier, such as ISBN, or a custom identifier, so long as it is unique.

string

FormData

seriesId
optional

Unique identifier of the series.

string

FormData

externalFormat
required

Format in which the title is available, but which is not deliverable by the API. Use of these formats must be negotiated with the site responsible for the title.

enum (MUSIC_BRAILLE, HARDCOPY_BRAILLE, PRINT_BRAILLE, FEELIX_KIT)

FormData

lexileCode
optional

The two-letter Lexile code of the title describing the type of book and age appropriateness.

string

FormData

lexileNumber
optional

The Lexile measure representing the title’s readability.

string
Responses
HTTP Code Description Schema

202

Request has been received, and will be processed.

status_model

default

Unexpected error

error_model
Consumes

  • application/x-www-form-urlencoded

2.1.2. Update title metadata

PUT /v2/titles/{bookshareId}
Description

Update a title’s metadata. This includes title, author, ISBN and other properties. This submits a request that will be processed at some point in the future. The title history event list will include an entry reflecting this request and showing when it was applied.

Parameters
Type Name Description Schema

Path

bookshareId
required

Unique identifier of a title.

string

FormData

title
optional

Main title of the book or reading material.

string

FormData

subtitle
optional

Subtitle of the book or reading material.

string

FormData

isbn13
optional

ISBN of the book or reading material. This can be either ISBN-10 or ISBN-13, but it will be converted to ISBN-13.

string

FormData

authors
optional

Author names for the title. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

abridgers
optional

People named as 'abridged by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

adapters
optional

People named as 'adapted by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

arrangers
optional

People named as 'arranged by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

composers
optional

People named as 'composer' of a musical score. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

coWriters
optional

People named as 'written with'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

editors
optional

People named as 'editor' or 'edited by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

epilogueBys
optional

People named as 'epilogue by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

forewardBys
optional

People named as 'foreward by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

introductionBys
optional

People named as 'introduction by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

lyricists
optional

People named as 'lyricist' of a musical score. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

transcribers
optional

People named as 'transcriber' of a Braille title. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

translators
optional

People named as 'translated by'. Enter each person or entity as a separate instance of this parameter.

< string > array(multi)

FormData

synopsis
optional

Descriptive summary of the title.

string

FormData

seriesTitle
optional

Title of the series to which the book belongs, if applicable.

string

FormData

seriesSubtitle
optional

Subtitle of the series to which the book belongs, if applicable.

string

FormData

seriesNumber
optional

Number of the book within the series to which it belongs.

string

FormData

copyrightHolder
optional

The copyright owner of the book or reading material.

string

FormData

copyrightDate
optional

The copyright year of the book or reading material.

integer

FormData

edition
optional

The edition name, if any, of the title.

string

FormData

readingAgeMinimum
optional

The minimum reading age for which the content is recommended.

integer

FormData

readingAgeMaximum
optional

The maximum reading age for which the content is recommended.

integer

FormData

adultContent
optional

True if the title contains adult content.

boolean

FormData

allowRecommend
optional

True if the title should be a candidate for the recommendation engine.

boolean

FormData

numPages
optional

Number of pages in this title.

integer

FormData

publisher
optional

The publisher of the book or reading material.

string

FormData

categories
optional

Bookshare categories to which the title belongs. For choices, see the category listing endpoint.

< string > array(multi)

FormData

bisacCategories
optional

BISAC categories to which the title belongs. For choices, see the list of BISAC codes.

< string > array(multi)

FormData

countries
optional

Countries to which this title is restricted for distribution. The values should be a two-character ISO 3166 alpha-2 country code.

< string > array(multi)

FormData

languages
optional

Languages of the title. The value will be a three-character ISO 639-2 alpha-3 language code.

< string > array(multi)

FormData

grades
optional

Code value of the grades for which the content is appropriate. Values are from ONIX codelist 77 for US grades, BIC for UK grades.

< string > array(multi)

FormData

contentWarnings
optional

Content warnings attached to the title.

< enum (contentWarning, sex, violence, drugs, language, intolerance, adult, unrated) > array(multi)

FormData

relatedIsbns
optional

ISBNs of other formats or renderings of the title.

< string > array(multi)

FormData

usageRestriction
optional

Usage restriction on the title, in terms of licensing.

enum (copyright, publicDomain, creativeCommons)

FormData

externalCategoryCode
optional

A code that maps to a category scheme in an external system. This can be used to track categories that Bookshare does not recognize.

string

FormData

musicScoreType
optional

If the content is a music score, the type of score it represents.

enum (fullScore, openScore, singleLine)

FormData

hasChordSymbols
optional

If the content is a music score, true if the content includes musical chord symbols.

boolean

FormData

instruments
optional

If the content is a music score, the names of any musical instruments that it covers.

string

FormData

key
optional

If the content is a music score, the musical key in which the score is written.

string

FormData

movementNumber
optional

If the content is a music score, the descriptive number of the musical movement.

string

FormData

movementTitle
optional

If the content is a music score, the descriptive title of the movement.

string

FormData

opus
optional

If the content is a music score, the descriptive number of the opus.

string

FormData

vocalParts
optional

If the content is a vocal score, the letters representing the vocal parts it covers. This can be some combination of the letters S, A, T and B.

string

FormData

notes
optional

Text to place in the metadata record of the title, describing particular features of the title for other Collection Assistants to see.

string

FormData

marrakeshEligible
optional

True if the title would be eligible to be shared with qualifying Marrakesh Treaty countries when the title’s country of origin has implemented the Marrakesh Treaty.

boolean

FormData

marrakeshPODException
optional

True if the title has a Marrakesh Proof of Disability exception.

boolean

FormData

availableToDemo
optional

True if the title is available to download by special user accounts set up for demonstration purposes.

boolean

FormData

availableWorldwide
optional

True if the title is available to users in any country.

boolean

FormData

states
optional

States to which this title is restricted for distribution. The value should be either a two-character postal abbreviation or an ISO 3166-2 subdivision code for the country. This field is only relevant for subdivisions of the US and Canada. Enter each state as a separate instance of this parameter.

< string > array(multi)

FormData

comments
optional

Text to place in the history of updates to the title, describing how or why the current changes are being made.

string

FormData

hasEmbeddedImageDescriptions
optional

True if the title has the image description in the text content, rather than in standard XML or HTML markup.

boolean

FormData

quality
optional

Rating of how well the title reflects the content and structure of the original material.

enum (publisher, excellent, good, fair)

FormData

originCountry
optional

The origin country of the title. The value should be a two-character ISO 3166 alpha-2 country code.

string

FormData

productIdentifier
optional

Unique identifier of the title within the collection. This could be a standard identifier, such as ISBN, or a custom identifier, so long as it is unique.

string

FormData

lexileCode
optional

The two-letter Lexile code of the title describing the type of book and age appropriateness.

string

FormData

lexileNumber
optional

The Lexile measure representing the title’s readability.

string

FormData

nimacRestricted
optional

True if the title is NIMAC restricted.

boolean
Responses
HTTP Code Description Schema

202

Request has been received, and will be processed.

status_model

default

Unexpected error

error_model
Consumes

  • application/x-www-form-urlencoded

2.1.3. Get a list of title history events

GET /v2/titles/{bookshareId}/history
Description

Get a list of events that mark transitions or updates to the given title and its artifacts. For example, these events might tell when a particular metadata value changed, or when an audio artifact was created.

Parameters
Type Name Description Schema

Path

bookshareId
required

Unique identifier of a title

string
Responses
HTTP Code Description Schema

200

Title history event collection response

title_history_event_resource_list

default

Unexpected error

error_model

2.1.4. Search for titles across the catalog

GET /v2/catalog
Description

For allowed roles, you can ask for titles that might not be visible to regular users, such as those that were once in the collection, but have since been removed. This allows adminstrators to manage the wider collection of titles.

Like with the general title search, the result will be a collection of title metadata resources, with a paging token if the results are more than the paging limit.

Parameters
Type Name Description Schema Default

Query

country
optional

Limit results to those available in the given country. The value should be a two-character ISO 3166 alpha-2 country code.

string

Query

isbn
optional

Search string to use to search for matching ISBNs. Spaces and dashes will be stripped. Invalid ISBNs will return an error from the search.

string

Query

titleStatus
optional

Limit results to those with the given status.

enum (available, withdrawn)

Query

startUpdatedDate
optional

Start date for a filtered range of results. Uses the date-time notation as described in the dates section.

string (date-time)

Query

endUpdatedDate
optional

End date for a filtered range of results. Uses the date-time notation as described in the dates section.

string (date-time)

Query

start
optional

If null or empty, it means to start at the beginning of the result set. Otherwise, it should be the value of "next" that was returned from the previous request.

string

Query

limit
optional

Maximum number of results to include. The maximum allowed is 100.

integer

10

Query

sortOrder
optional

Primary sorting field.

enum (relevance, title, author, updatedDate, copyrightDate)

"[title]"

Query

direction
optional

Direction for sorting.

enum (asc, desc)

"[asc]"
Responses
HTTP Code Description Schema

200

Title metadata collection response

title_metadata_complete_list

default

Unexpected error

error_model

2.2. Collection Assistant - Periodicals

Administrative users have resources available that will let them manage periodical series and editions. These are similar in function to the title resources, but with differences related to the series nature of periodicals.

2.2.1. Update periodical series metadata

PUT /v2/periodicals/{seriesId}
Description

Update the series metadata for an existing periodical.

Parameters
Type Name Description Schema

Path

seriesId
required

ID of the Periodical series

string

FormData

title
optional

Title of the periodical series

string

FormData

issn
optional

ISSN of the periodical series

string

FormData

description
optional

Description of the periodical series

string

FormData

publisher
optional

Publisher name for the periodical series

string

FormData

externalCategoryCode
optional

External category code

string

FormData

categories
optional

Bookshare categories, each sent as an individual parameter.

< string > array(multi)

FormData

languages
optional

Languages, each sent as an individual parameter.

< string > array(multi)

FormData

seriesType
optional

Type of periodical

enum (newspaper, magazine, journal)

FormData

countries
optional

Countries to which this series is restricted for distribution. The values should be a two-character ISO 3166 alpha-2 country code.

< string > array(multi)
Responses
HTTP Code Description Schema

200

Periodical series metadata detail response

periodical_series_metadata_summary

default

Unexpected error

error_model

2.2.2. Update periodical edition metadata

PUT /v2/periodicals/{seriesId}/editions/{editionId}
Description

Update the metadata of an existing periodical edition.

Parameters
Type Name Description Schema

Path

seriesId
required

The unique identifier of a periodical series

string

Path

editionId
required

The unique identifier of a periodical edition

string

FormData

editionName
optional

The name of the periodical edition

string

FormData

publicationDate
optional

The publication date of the periodical edition

date

FormData

expirationDate
optional

The expiration date (if any) of the periodical edition

date
Responses
HTTP Code Description Schema

200

Periodical edition metadata response

periodical_edition

default

Unexpected error

error_model
Consumes

  • application/x-www-form-urlencoded

2.2.3. Withdraw a periodical edition

DELETE /v2/periodicals/{seriesId}/editions/{editionId}
Description

Withdraw a periodical edition.

Parameters
Type Name Description Schema

Path

seriesId
required

The unique identifier of a periodical series.

string

Path

editionId
required

The unique identifier of a periodical edition

string
Responses
HTTP Code Description Schema

202

Request has been received, and will be processed.

status_model

default

Unexpected error

error_model

3. Definitions

3.1. accessibility_certification

Name Description Schema

certifiedBy
optional

Identifies a party responsible for the testing and certification of the accessibility of this artifact

string

certifierCredential
optional

Identifies a credential or badge that establishes the authority of the party identified in the associated certifiedBy property to certify content accessible

string

certifierReport
optional

Provides a link to an accessibility report created by the party identified

string

3.2. accessibility_feature

Name Description Schema

accessibilityFeature
optional

Identifies the type of accessibility feature with values coming from ONIX codelist 196 and W3C Discoverability Vocab

string

description
optional

Additional information about the feature

string

3.3. accessibility_metadata

Name Description Schema

accessModes
optional

The ways in which information is encoded in this artifact with values from W3C Discoverability Vocab

< string > array

accessModesSufficient
optional

A list of single or combined accessModes that are sufficient to understand all the intellectual content of this artifact with values from W3C Discoverability Vocab

< string > array

accessibilityCertifications
optional

The person or organization that certified the accessibility of this artifact

< accessibility_certification > array

accessibilityConformances
optional

Set of specifications this artifact conforms to (EPUB specification levels, WCAG versions, and WCAG levels). For more information see the W3C EPUB Accessibility and ONIX Codelist 196

< string > array

accessibilityFeatures
optional

The accessibility features that apply to this artifact

< accessibility_feature > array

accessibilityHazards
optional

Set of accessibility hazards that apply to this artifact with values coming from W3C Discoverability Vocab

< string > array

accessibilitySummary
optional

A human readable field summarizing the accessibility metadata

string

3.4. artifact_metadata

Name Description Schema

accessibilityMetadata
optional

Accessibility metadata related to this artifact

accessibility_metadata

brailleCode
optional

Braille code, such as UEB or EBAE

string

brailleGrade
optional

Braille grade, contracted or uncontracted

enum (contracted, uncontracted)

brailleMusicScoreLayout
optional

Braille music score layout, barOverBar or barByBar

enum (barOverBar, barByBar)

brailleType
optional

Braille type, automated or transcribed

enum (automated, transcribed)

dateAdded
optional

Date that the artifact was originally added to the collection

string (date-time)

duration
optional

The length of the audio artifact, in ISO 8601 duration format (PTnHnMnS)

string

externalIdentifierCode
optional

The external identifier for this artifact, assigned by the site responsible for this artifact

string

format
optional

The format identifier of the artifact this information relates to

string

fundingSource
optional

The person or organization who funded the production of this artifact

string

globalBookServiceId
optional

An identifier from a global book service such as ABC

string

narrator
optional

narrator

numberOfVolumes
optional

The number of Braille volumes contained in this artifact

integer

producer
optional

The person or organization that produced this particular artifact

string

supplier
optional

The person or organization who provided this artifact to be included in the collection

string

transcriber
optional

The name of the person who transcribed this artifact

name

3.5. category

Name Description Schema

categoryType
optional

Category type, Bookshare or BISAC

enum (Bookshare, BISAC)

code
optional

Code that represents the category, may be null.

string

description
optional

Descriptive name of the subject category, localized when possible to the user’s locale.

string

links
optional

< link > array

name
optional

Identifier of the subject category

string

3.6. content_warning_values

Type : enum (contentWarning, sex, violence, drugs, language, intolerance, adult, unrated)

3.7. contributor

Name Description Schema

links
optional

< link > array

name
optional

The contributor’s name.

contributor_name

type
optional

Type of contributor to a title or artifact.

enum (author, coWriter, epilogueBy, forwardBy, introductionBy, editor, composer, arranger, lyricist, translator, transcriber, abridger, adapter)

3.8. contributor_name

Name Description Schema

displayName
optional

Name as a full combination of all parts, first name before last name.

string

indexName
optional

Name as it would be indexed for sorting.

string

links
optional

< link > array

3.9. error_model

Name Schema

key
required

string

messages
required

< string > array

3.10. format

Name Description Schema

formatId
optional

Unique identifier of the format.

string

name
optional

Descriptive name of the format, suitable for display.

string

3.11. grade

Name Description Schema

gradeCode
optional

Code value of the grade. Values are from ONIX codelist 77 for US grades, BIC for UK grades

string

gradeId
optional

Deprecated - Unique identifier

string

links
optional

< link > array

name
optional

Descriptive name of the grade category

string

3.12. link

Name Description Schema

href
optional

An absolute or relative URI for a resource request

string

rel
optional

A relationship name

string

3.13. name

Name Description Schema

firstName
optional

First name of the individual or entity

string

lastName
optional

Last name of the individual or entity

string

links
optional

< link > array

middle
optional

Middle name, or initial, if any

string

prefix
optional

Prefix, if any, such as Mr., Mrs., Dr.

string

suffix
optional

Suffix, if any, such as Jr., Sr., III

string

3.14. narrator

Name Description Schema

gender
optional

The narrator’s gender

enum (male, female, otherNonBinary)

name
optional

The narrator’s name

string

type
optional

The source of speech

enum (tts, human)

3.15. periodical_edition

Name Description Schema

editionId
optional

Unique identifier of a periodical edition

string

editionName
optional

Name of the edition

string

expirationDate
optional

Expiration date of the edition

string (date-time)

formats
optional

Available formats

< format > array

links
optional

< link > array

publicationDate
optional

Publication date of the edition

string (date-time)

3.16. periodical_edition_summary

Name Description Schema

editionId
optional

Unique identifier of the periodical edition

string

editionName
optional

Name of the edition

string

3.17. periodical_series_metadata_summary

Name Description Schema

categories
optional

Categories of the periodical

< category > array

countries
optional

Countries to which this periodical is restricted for distribution. The values should be a two-character ISO 3166 alpha-2 country code.

< string > array

description
optional

Description of the periodical

string

editionCount
optional

The number of editions available for this periodical

integer

externalCategoryCode
optional

External Category Code

string

issn
optional

ISSN of the periodical

string

languages
optional

Languages of the periodical. The value will be a three-character ISO 639-2 alpha-3 language code

< string > array

latestEdition
optional

periodical_edition_summary

links
optional

< link > array

publisher
optional

Publisher of the periodical

string

seriesId
optional

Unique identifier of the periodical series

string

seriesType
optional

Type of periodical

enum (newspaper, magazine, journal)

title
optional

Title of the periodical

string

3.18. status_model

Name Schema

key
required

string

messages
required

< string > array

3.19. title_history_event

Name Description Schema

action
optional

Action that was performed

string

comment
optional

Comments about the action performed

string

date
optional

Date the action was performed

string (date-time)

format
optional

The format identifier of the artifact for which the event occurred

string

personName
optional

Person who performed the action

string

3.20. title_history_event_resource_list

Name Schema

events
optional

< title_history_event > array

3.21. title_link

Name Description Schema

href
optional

An absolute or relative URI for a resource request.

string

rel
optional

A relationship name.

enum (self, coverimage, thumbnail, download, history, titleSource, replacement, submitter)

title
optional

Descriptive text that could be used as link text.

string

type
optional

Media type that this link is expected to return.

string

3.22. title_metadata_complete

Name Description Schema

adultContent
optional

True if the title contains adult content

boolean

allowRecommend
optional

True if this title can be part of a recommendation set

boolean

allows
optional

Operations allowed: PUT, for Collection Assistants

< enum (PUT) > array

arrangers
optional

Deprecated - Arrangers of the sheet music

< name > array

artifacts
optional

Additional information, if any, about the artifacts available for this title

< artifact_metadata > array

authors
optional

Deprecated - Author names of the title

< name > array

available
optional

True if the title is potentially available to users. See 'formats' for the ways the current user is allowed to request the title

boolean

bookshareId
optional

Unique identifier of the title

string

categories
optional

Categories of the title

< category > array

composers
optional

Deprecated - Composer names of the sheet music

< name > array

contentWarnings
optional

List of content warnings for the title

< content_warning_values > array

contributors
optional

Contributors to the title

< contributor > array

copyright
optional

Deprecated - The copyright owner of the book or reading material

string

copyrightDate
optional

The copyright year of this title

string (year)

copyrightHolder
optional

The copyright owner of the book or reading material

string

countries
optional

Countries to which this title is restricted for distribution. The values should be a two-character ISO 3166 alpha-2 country code.

< string > array

dtbookSize
optional

Number of bytes in the DTBook content file of the DAISY artifact

integer (int64)

edition
optional

Edition of the book or reading material

string

externalCategoryCode
optional

A proprietary category designation

string

externalFormats
optional

Formats in which the title is available, but which are not deliverable by the API. Access to these formats must be negotiated with the site responsible for the title.

< format > array

formats
optional

Formats in which the title is available

< format > array

grades
optional

Grades for which the title is appropriate

< grade > array

hasChordSymbols
optional

Chord symbols of the sheet music

string

instruments
optional

Instruments of the sheet music

string

isbn13
optional

ISBN of the book or reading material

string

key
optional

Key of the sheet music

string

languages
optional

Languages of the title. The value will be a three-character ISO 639-2 alpha-3 language code

< string > array

lastUpdated
optional

The date this title was most recently updated, either with changed metadata, a new artifact, or a changed status

string (date-time)

lexileCode
optional

The 2-letter Lexile code describing additional information about the readability of the book.

string

lexileNumber
optional

The numeric Lexile measure describing the readability of the book, followed by an 'L'.

string

links
optional

< title_link > array

lyricists
optional

Deprecated - Lyricists of the sheet music

< name > array

marrakeshAvailable
optional

True if this title is available under the Marrakesh Treaty

boolean

marrakeshPODException
optional

True if this title is available under the Marrakesh Proof of Disability exception

boolean

movementNumber
optional

Movement number of the sheet music

string

movementTitle
optional

Movement title of the sheet music

string

musicLayout
optional

Music layout of the sheet music

string

musicScoreType
optional

Score type of the sheet music

string

notes
optional

Any general notes for the title

string

numImages
optional

Number of images in this title

integer

numPages
optional

Number of pages in this title

integer

opus
optional

Opus of the sheet music

string

proofreader
optional

An identifier of the person who proofread the original scanned title

string

publishDate
optional

The date this title was added to the collection

string (date-time)

publisher
optional

The publisher of the book or reading material

string

readingAgeMaximum
optional

The maximum reading age for which the book is recommended

integer

readingAgeMinimum
optional

The minimum reading age for which the book is recommended

integer

relatedIsbns
optional

ISBNs of books related to the title

< string > array

replacementId
optional

Identifier of the title that replaced this one, if any

string

seriesNumber
optional

Number of the book within the series to which it belongs

string

seriesSubtitle
optional

Subtitle of the series to which the book belongs

string

seriesTitle
optional

Title of the series to which the book belongs, if applicable

string

site
optional

The site with which the title is associated

string

submitter
optional

An identifier of the person who submitted the original scanned title

string

subtitle
optional

Subtitle of the book or reading material

string

synopsis
optional

Synopsis of the title

string

title
optional

Title of the book or reading material

string

titleContentType
optional

General type of content found in this title. Most titles will be text, but specialized titles could be primarily content like music scores or graphic images.

string

titleSource
optional

The publisher or distributor who submitted the original title artifact

string

translators
optional

Deprecated - Translators of the sheet music

< name > array

usageRestriction
optional

Usage restriction on the title

usage_restriction

vocalParts
optional

Vocal parts of the sheet music

string

withdrawalDate
optional

The date this title was removed from the collection

string (date-time)

3.23. title_metadata_complete_list

Name Description Schema

allows
optional

Operations allowed: None

< string > array

limit
optional

Maximum number of results included in this set

integer

links
optional

< link > array

next
optional

Token that can be used as the "start" value to retrieve another group of results

string

titles
optional

< title_metadata_complete > array

totalResults
optional

The number of results found that match the search criteria

integer

3.24. usage_restriction

Name Description Schema

name
optional

Descriptive name of the usage restriction

string

usageRestrictionId
optional

Unique identifier

string