External Audible API

Documentation

There is currently no publicly available documentation about the Audible API.

There is a node client audible-api that has some endpoints documented, but does not provide information on authentication.

Luckily the Audible API is partially self-documenting, however the parameter names need to be known. Error responses will look like:

{
  "message": "1 validation error detected: Value 'some_random_string123' at 'numResults' failed to satisfy constraint: Member must satisfy regular expression pattern: ^\\d+$"
}

Few endpoints have been fully documented, as a large amount of functionality is not testable from the app or functionality is unknown. Most calls need to be authenticated.

For %s substitutions the value is unknown or can be inferred from the endpoint. /1.0/catalog/products/%s for example requires an asin, as in /1.0/catalog/products/B002V02KPU.

Each bullet below refers to a parameter for the request with the specified method and URL.

Responses will often provide very little info without response_groups specified. Multiple response groups can be specified, for example: /1.0/catalog/products/B002V02KPU?response_groups=product_plan_details,media,review_attrs. When providing an invalid response group, the server will return an error response but will not provide information on available response groups.

API Endpoints

GET /0.0/library/books

This API endpoint is deprecated. Please use GET /1.0/library instead.

Query Parameters:

• purchaseAfterDate (string) – mm/dd/yyyy

• sortByColumn (string) – [SHORT_TITLE, strTitle, DOWNLOAD_STATUS, RUNNING_TIME, sortPublishDate, SHORT_AUTHOR, sortPurchDate, DATE_AVAILABLE]

• sortInAscendingOrder (bool) – [true, false]

Library

GET /1.0/library

The audible library of current user

Query Parameters:

• num_results (integer) – (max: 1000)

• page (integer) – page

• purchased_after (string) – [RFC3339](https://tools.ietf.org/html/rfc3339) (e.g. 2000-01-01T00:00:00Z)

• title (string) – a title

• author (string) – a author

• response_groups (string) – [contributors, customer_rights, media, price, product_attrs, product_desc, product_details, product_extended_attrs, product_plan_details, product_plans, rating, sample, sku, series, reviews, ws4v, origin, relationships, review_attrs, categories, badge_types, category_ladders, claim_code_url, in_wishlist, is_archived, is_downloaded, is_finished, is_playable, is_removable, is_returnable, is_visible, listening_status, order_details, origin_asin, pdf_url, percent_complete, periodicals, provided_review]

• image_sizes (string) – [1215,408,360,882,315,570,252,558,900,500]

• sort_by (string) – [-Author, -Length, -Narrator, -PurchaseDate, -Title, Author, Length, Narrator, PurchaseDate, Title]

• status (string) – [Active, Revoked] (‘Active’ is the default, ‘Revoked’ returns audiobooks the user has returned for a refund.)

• parent_asin (string) – asin

• include_pending (string) – [true, false]

• marketplace (string) – [e.g. AN7V1F1VY261K]

• state_token (string)

GET /1.0/library/(string: asin)

Parameters:

• asin (string) – The asin of the book

Query Parameters:

• response_groups (string) – [contributors, media, price, product_attrs, product_desc, product_details, product_extended_attrs, product_plan_details, product_plans, rating, sample, sku, series, reviews, ws4v, origin, relationships, review_attrs, categories, badge_types, category_ladders, claim_code_url, is_downloaded, is_finished, is_returnable, origin_asin, pdf_url, percent_complete, periodicals, provided_review]

POST /1.0/library/item

Request JSON Object:

• asin (string) – The asin of the book

POST /1.0/library/item

Request JSON Object:

• asin

PUT /1.0/library/item

Add an (AYCL) item to the library

Request JSON Object:

• asin

POST /1.0/library/item/(param1)/(param2)

Parameters:

• param1

• param2

Request JSON Object:

• unknown

POST /1.0/library/collections/(param1)/channels/(param2)

Parameters:

• param1

• param2

Request JSON Object:

• customer_id

• marketplace

POST /1.0/library/collections/(param1)/products/(param2)

Parameters:

• param1

• param2

Request JSON Object:

• channel_id

GET /1.0/library/collections

Query Parameters:

• customer_id

• marketplace

POST /1.0/library/collections

Request JSON Object:

• collection_type

GET /1.0/library/collections/(param1)

Parameters:

• param1

Query Parameters:

• customer_id

• marketplace

• page_size

• continuation_token

GET /1.0/library/collections/(param1)/products

Parameters:

• param1

Query Parameters:

• customer_id

• marketplace

• page_size

• continuation_token

• image_sizes

Catalog

Categories

GET /1.0/catalog/categories

Query Parameters:

• response_groups – [category_metadata, products]

• products_plan – [Enterprise, RodizioFreeBasic, AyceRomance, AllYouCanEat, US Minerva, Universal, AmazonEnglish, ComplimentaryOriginalMemberBenefit, Radio, SpecialBenefit, Rodizio]

• products_in_plan_timestamp

• products_num_results

• runtime_length_min

• content_level

• content_type

• categories_num_levels (int) – (greater than or equal to 1)

• ids – \d+(,\d+)*

• root – [InstitutionsHpMarketing, ChannelsConfigurator, AEReadster, ShortsPrime, ExploreBy, RodizioBuckets, EditorsPicks, ClientContent, RodizioGenres, AmazonEnglishProducts, ShortsSandbox, Genres, Curated, ShortsIntroOutroRemoval, Shorts, RodizioEpisodesAndSeries, ShortsCurated]

GET /1.0/catalog/categories/(category_id)

Parameters:

• category_id

Query Parameters:

• image_dpi (int)

• image_sizes

• image_variants

• products_in_plan_timestamp

• products_num_results (int)

• products_plan – [Enterprise, RodizioFreeBasic, AyceRomance, AllYouCanEat, AmazonEnglish, ComplimentaryOriginalMemberBenefit, Radio, SpecialBenefit, Rodizio]

• products_sort_by – [-ReleaseDate, ContentLevel, -Title, AmazonEnglish, AvgRating, BestSellers, -RuntimeLength, ReleaseDate, ProductSiteLaunchDate, -ContentLevel, Title, Relevance, RuntimeLength]

• reviews_num_results (int)

• reviews_sort_by – [MostHelpful, MostRecent]

Quers products_not_in_plan_timestamp:

Products

GET /1.0/catalog/products/(string: asin)

Parameters:

• asin (string) – The asin of the book

Query Parameters:

• image_dpi

• image_sizes

• response_groups – [contributors, media, price, product_attrs, product_desc, product_details, product_extended_attrs, product_plan_details, product_plans, rating, sample, sku, series, reviews, relationships, review_attrs, category_ladders, claim_code_url, provided_review, rights, customer_rights]

• reviews_num_results – \d+ (max: 10)

• reviews_sort_by – [MostHelpful, MostRecent]

• asins

GET /1.0/catalog/products

Query Parameters:

• asins

• image_sizes – [1215,408,360,882,315,570,252,558,900]

• response_groups – [sku,product_attrs,rating,product_extended_attrs,media,sample,product_plans,product_plan_details,badges,relationships,customer_rights,product_desc,contributors]

GET /1.0/catalog/products/(string: asin)/reviews

Parameters:

• asin (string) – The asin of the book

Query Parameters:

• sort_by – [MostHelpful, MostRecent]

• num_results (int) – (max: 50)

• page (int)

GET /1.0/catalog/products

Query Parameters:

• author

• browse_type

• category_id (int) – \d+(,\d+)*

• disjunctive_category_ids

• image_dpi (int)

• image_sizes

• in_plan_timestamp

• keywords

• narrator

• not_in_plan_timestamp

• num_most_recent

• num_results (int) – (max: 50)

• page (int)

• plan – [Enterprise, RodizioFreeBasic, AyceRomance, AllYouCanEat, AmazonEnglish, ComplimentaryOriginalMemberBenefit, Radio, SpecialBenefit, Rodizio]

• products_since_timestamp

• products_sort_by – [-ReleaseDate, ContentLevel, -Title, AmazonEnglish, AvgRating, BestSellers, -RuntimeLength, ReleaseDate, ProductSiteLaunchDate, -ContentLevel, Title, Relevance, RuntimeLength]

• publisher

• response_groups – [contributors, media, price, product_attrs, product_desc, product_extended_attrs, product_plan_details, product_plans, rating, review_attrs, reviews, sample, series, sku]

• reviews_num_results (int) – (max: 10)

• reviews_sort_by – [MostHelpful, MostRecent]

• title

GET /1.0/catalog/products/(string: asin)/sims

Parameters:

• asin (string) – The asin of the book

Query Parameters:

• category_image_variants

• image_dpi

• image_sizes

• in_plan_timestamp

• language

• not_in_plan_timestamp

• num_results (int) – (max: 50)

• plan – [Enterprise, RodizioFreeBasic, AyceRomance, AllYouCanEat, AmazonEnglish, ComplimentaryOriginalMemberBenefit, Radio, SpecialBenefit, Rodizio]

• response_groups – [contributors, media, price, product_attrs, product_desc, product_extended_attrs, product_plans, rating, review_attrs, reviews, sample, sku]

• reviews_num_results (int) – (max: 10)

• reviews_sort_by – [MostHelpful, MostRecent]

• similarity_type – [InTheSameSeries, ByTheSameNarrator, RawSimilarities, ByTheSameAuthor, NextInSameSeries]

Collections

GET /1.0/collections

Query Parameters:

• state_token – [ey…]

• visibility_types – [Private, Discoverable]

POST /1.0/collections

Create a new collection

Request JSON Object:

• name

• asins – []

• description

Response JSON Object:

• collection_id

• creation_date

• customer_id

• marketplace

GET /1.0/collections/(collection_id)

Parameters:

• collection_id

PUT /1.0/collections/(collection_id)

Modify a collection

Parameters:

• collection_id

Request JSON Object:

• state_token

• collection_id

• name

• description

Response JSON Object:

• state_token

• collection_id

• name

• description

GET /1.0/collections/(collection_id)/items

Parameters:

• collection_id – e.g __FAVORITES

Query Parameters:

• response_groups – [always-returned]

POST /1.0/collections/(collection_id)/items

Add item(s) to a collection

Parameters:

• collection_id

Request JSON Object:

• collection_id

• asins – []

Response JSON Object:

• description

• name

• num_items_added (int)

• state_token

Orders

GET /1.0/orders

Returns order history from at least the past 6 months. Supports pagination.

Query Parameters:

• unknown

POST /1.0/orders

Request JSON Object:

• asin (string)

• audiblecreditapplied (boolean) – will specify whether to use available credits or default payment method.

Example request body

{
  "asin": "B002V1CB2Q",
  "audiblecreditapplied": "false"
}

Wishlist

GET /1.0/wishlist

Query Parameters:

• num_results (int) – (max: 50)

• page (int) – (wishlist start at page 0)

• locale (string) – e.g. de-DE

• response_groups – [contributors, media, price, product_attrs, product_desc, product_extended_attrs, product_plan_details, product_plans, rating, sample, sku, customer_rights, relationships]

• sort_by – [-Author, -DateAdded, -Price, -Rating, -Title, Author, DateAdded, Price, Rating, Title]

POST /1.0/wishlist

Request JSON Object:

• asin (string) – The asin of the book to add

Status Codes:

• 201 Created – Returns the Location to the resource.

Example request body

{
  "asin": "B002V02KPU"
}

DELETE /1.0/wishlist/(string: asin)

Parameters:

• asin (string) – The asin of the book

Status Codes:

• 204 No Content – Removes the item from the wishlist using the given asin.

GET /1.0/badges/progress

Query Parameters:

• locale – en_US

• response_groups – brag_message

• store – [AudibleForInstitutions, Audible, AmazonEnglish, Rodizio]

Badges

GET /1.0/badges/metadata

Query Parameters:

• locale – en_US

• response_groups – all_levels_metadata

Content

POST /1.0/content/(string: asin)/licenserequest

Parameters:

• asin (string) – The asin of the book

Request JSON Object:

• use_adaptive_bit_rate (boolean) – [true, false]

• quality (string) – [High, Normal]

• chapter_titles_type (string) – [Tree, Flat]

• response_groups (string) – [chapter_info, content_reference, last_position_heard, pdf_url, ad_insertion, certificate]

• consumption_type (string) – [Streaming, Offline, Download]

• spatial (boolean) – [true, false]

• supported_media_features (dict) – [codecs, drm_types]

• codecs (list) – [mp4a.40.2, mp4a.40.42, ec+3, ac-4]

• drm_types (list) – [Mpeg, PlayReady, Hls, Dash, Adrm, FairPlay, Widevine, HlsCmaf]

• num_active_offline_licenses (integer) – (max: 10)

Example request body

{
    "quality": "High",
    "response_groups": "chapter_info,content_reference,last_position_heard,pdf_url, ad_insertion, certificate",
    "consumption_type": "Download",
    "supported_media_features":
        {
            "codecs": [
                "mp4a.40.2",
                "mp4a.40.42",
                "ec+3",
                "ac-4"
            ],
            "drm_types": [
                "Mpeg",
                "PlayReady",
                "Hls",
                "Dash",
                "Adrm",
                "FairPlay",
                "Widevine",
                "HlsCmaf",
            ]
        },
    "spatial": false
}

For a succesful request, returns JSON body with content_url.

GET /1.0/content/(string: asin)/metadata

Parameters:

• asin (string) – the asin of the book

Query Parameters:

• response_groups – [chapter_info, always-returned, content_reference, content_url]

• acr

• quality – [High, Normal]

• chapter_titles_type – [Tree, Flat]

• drm_type – [Mpeg, PlayReady, Hls, Dash, FairPlay, Widevine, HlsCmaf, Adrm]

POST /1.0/content/(string: asin)/drmlicense

Parameters:

• asin (string) – The asin of the book

Request JSON Object:

• licenseChallenge (string) – The license challenge

• asin (string) – The asin of the book

• consumption_type (string) – “Download”

• drm_type (string) – “FairPlay”

Response JSON Object:

• license (string) – The encrypted license

GET 1.0/content/FairPlay/certificate

Response JSON Object:

• certificate (string) – The base64 encoded FairPlay certificate

Account

GET /1.0/account/information

Query Parameters:

• response_groups – [delinquency_status, customer_benefits, customer_segments, subscription_details_payment_instrument, plan_summary, subscription_details, directed_ids]

• source – [Credit, Enterprise, RodizioFreeBasic, AyceRomance, AllYouCanEat, AmazonEnglish, ComplimentaryOriginalMemberBenefit, Radio, SpecialBenefit, Rodizio]

Customer

GET /1.0/customer/information

Query Parameters:

• response_groups – [migration_details, subscription_details_rodizio, subscription_details_premium, customer_segment, subscription_details_channels]

GET /1.0/customer/status

Query Parameters:

• response_groups – [benefits_status, member_giving_status, prime_benefits_status, prospect_benefits_status]

GET /1.0/customer/freetrial/eligibility

Stats

GET /1.0/stats/aggregates

Query Parameters:

• daily_listening_interval_duration – ([012]?[0-9])|(30) (0 to 30, inclusive)

• daily_listening_interval_start_date – YYYY-MM-DD (e.g. 2019-06-16)

• locale – en_US

• monthly_listening_interval_duration – 0?[0-9]|1[012] (0 to 12, inclusive)

• monthly_listening_interval_start_date – YYYY-MM (e.g. 2019-02)

• response_groups – [total_listening_stats]

• store – [AudibleForInstitutions, Audible, AmazonEnglish, Rodizio]

GET /1.0/stats/status/finished

Query Parameters:

• asin – asin

• start_date – [RFC3339](https://tools.ietf.org/html/rfc3339) (e.g. 2000-01-01T00:00:00Z)

POST /1.0/stats/status/finished

Request JSON Object:

• start_date

• status

• continuation_token

PUT /1.0/stats/events

Request JSON Object:

• stats

Example request body

{
    "stats" : [
        {
            "download_start" : {
                "country_code" : "de",
                "download_host" : "xxxxx.cloudfront.net",
                "user_agent" : "Audible, iPhone, 3.35.1 (644), iPhone XS (iPhone11,2), 238 GB, iOS, 14.1, Wifi",
                "request_id" : "xxxxxxxxxxxx",
                "codec" : "AAX_44_128",
                "source" : "audible_iPhone"
            },
            "social_network_site" : "Unknown",
            "event_type" : "DownloadStart",
            "listening_mode" : "Offline",
            "local_timezone" : "Europe\/Berlin",
            "asin_owned" : false,
            "playing_immersion_reading" : false,
            "audio_type" : "FullTitle",
            "event_timestamp" : "2020-10-23T21:29:06.985Z",
            "asin" : "xxxxxxx",
            "store" : "Audible",
            "delivery_type" : "Download"
        }
    ]
}

Misc

GET /1.0/annotations/lastpositions

Query Parameters:

• asins – asin (comma-separated), e.g. ?asins=B01LWUJKQ7,B01LWUJKQ7,B01LWUJKQ7

PUT /1.0/lastpositions/(string: asin)

Parameters:

• asin (string) – the asin of the book

Request JSON Object:

• acr – obtained by POST /1.0/content/(string:asin)/licenserequest

• asin

• position_ms

GET /1.0/pages/(string: param1)

Parameters:

• param1 (string) – [ios-app-home]

Query Parameters:

• image_dpi (int) – [489]

• local_time – [2022-01-01T12:00:00+01:00]

• locale – en-US

• os – [15.2]

• reviews_num_results

• reviews_sort_by

• response_groups – [media, product_plans, view, product_attrs, contributors, product_desc, sample]

• session_id – [123-1234567-1234567]

• surface – [iOS]

GET /1.0/recommendations

Query Parameters:

• category_image_variants

• category_image_variants

• image_dpi

• image_sizes

• in_plan_timestamp

• language

• not_in_plan_timestamp

• num_results (int) – (max: 50)

• plan – [Enterprise, RodizioFreeBasic, AyceRomance, AllYouCanEat, AmazonEnglish, ComplimentaryOriginalMemberBenefit, Radio, SpecialBenefit, Rodizio]

• response_groups – [contributors, media, price, product_attrs, product_desc, product_extended_attrs, product_plan_details, product_plans, rating, sample, sku]

• reviews_num_results (int) – (max: 10)

• reviews_sort_by – [MostHelpful, MostRecent]

GET /1.0/user/settings

Query Parameters:

• setting_name (string) – [captionsEnabled]

GET /1.0/app/upgradestatus

Query Parameters:

• version – [3.68]

• app_id – [A2CZJZGLK2JJVM]

• operating_system – [iOS15.4]

GET https://cde-ta-g7g.amazon.com/FionaCDEServiceEngine/sidecar

Returns the clips, notes and bookmarks of a book

Query Parameters:

• type (string) – [“AUDI”]

• key (string) – asin of the book