back to index

The Notes API allows any EPUB, anywhere, to carry shared public annotations with it, and allows anyone with a compatible EPUB reading system to post new notes and view public notes posted from other reading systems. Each EPUB file out there has a unique primary ID which the Notes API uses along with hash identifiers (#fragment) for arbitrary elements and pseudo hash identifiers (#!0p:0) for paragraph identification. The notes themselves are transported with the widely-used Atom format, available as either XML or JSON.

API Details

Endpoints
GET note/list


Parameters

• epub_id (REQUIRED): The Primary ID of the EPUB for which you want to retrieve notes. Note: this is the single identifier designated as the "unique-identifier" in the EPUB file.
• href (OPTIONAL): The target, usually a path/file#fragment combination, identifying a document and optionally a location within a document. Only the notes attached to this location will be returned, if it is specified. The BookGlutton system uses pseudo-hash IDs (PHIs) to indicate HTML elements in document order. For example, #!2p:0 would point to the third paragraph element in the document, character 0. Right now, only PHIs for paragraph elements are supported. Other identification schemes such as XPath could also be used. We leave it up to other developers to help decide which schemes are best.
• note_id (OPTIONAL): This retrieves a single note, by its internal system id.
• fmt (OPTIONAL): Specifying 'json' here will return JSON results, 'atom' will return Atom formatted results. Defaults to 'atom.'
• limit (OPTIONAL): Limit to this number of results per page.
• page (OPTIONAL): Which page number of results beyond the limit to retrieve.
• q (OPTIONAL): Query string filter to limit results by keyword or phrase.
• by (OPTIONAL): Can be set to 'group' to return group results (requires authentication).
• group_id (OPTIONAL): If by is set to 'group', this is the internal system id for the group.

POST note/add
Authentication
A BookGlutton session id is required to post notes to the system. The user's profile information and any associated book group information are taken from this session and used as the context for the note. In the future, we'll support oAuth, Google, Facebook and Twitter, but for now, a valid BookGlutton user session is required. For details on how to authenticate a user with BookGlutton through your own application, contact Aaron Miller (aaron[...]bookglutton.com).

Parameters

• apikey (REQUIRED): Your developer API key. For a limited time, this should be set to 'testing' so that anyone may try it right away. In the near future, you will need to request an official key from our CTO, Aaron Miller.
• epub_id (REQUIRED): The Primary ID of the EPUB to which this note should be attached.
• href (OPTIONAL): The document or document location to which this note should be attached.
• title (REQUIRED): The title of the note.
• body (OPTIONAL): The body of the note (up to 900 characters).
• isprivate (OPTIONAL): If the user is authenticated, this will set the note to private under the user's account.

Response Formats and Codes
This API will respond to requests with appropriate HTTP status codes. In the list action, the response body will contain either XML or JSON formatted data, with pagination cues and links to responses. In the add action, the response body will contain a JSON-formatted object with a single property, either 'OK' or 'ERROR' depending on success or failure.


Disclaimer
This API is provided as a free service, with no guarantees or liability.