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, goodreads_ratings]
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/actors

Query Parameters:

include_enrolled (bool) – [true, false]
include_suggested (bool) – [true, false]

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