API Reference

Authentication

login(locale)

Generate a login URL for the Audible PKCE OAuth flow.

const { loginUrl, session, cookies } = await login('fr')

Parameters:

Name	Type	Description
locale	AudibleLocale	The Audible marketplace to authenticate against

Returns: Promise<{ loginUrl: string, session: AuthSession, cookies: AudibleCookie[] }>

---

register(authorizationCode, session)

Complete device registration using the authorization code from the OAuth callback.

const credentials = await register(code, session)
console.log(`Authenticated! Expires: ${credentials.expiresAt}`)

Parameters:

Name	Type	Description
authorizationCode	string	The code from the OAuth callback URL
session	AuthSession	The session returned by login()

Returns: Promise<AudibleCredentials>

Throws: Error if registration fails (invalid code, expired session, etc.)

---

refresh(credentials)

Manually refresh an access token. Usually not needed — all API functions auto-refresh credentials before each call.

const updated = await refresh(credentials)
console.log(`New expiration: ${updated.expiresAt}`)

Parameters:

Name	Type	Description
credentials	AudibleCredentials	Current credentials with a valid refreshToken

Returns: Promise<AudibleCredentials> — New credentials with updated accessToken and expiresAt

Throws: Error if the refresh token is invalid

---

Data Fetching

library(credentials)

Fetch the user’s entire Audible library with automatic pagination. Credentials are auto-refreshed before the call.

const { items } = await library(credentials)

// Each item has full details: rating, categories, listening progress, etc.
items.map((book) => {
  const rating = book.rating?.overallDistribution
  console.log(`${book.title} — ${rating?.averageRating?.toFixed(1)}/5`)
  if (book.listeningStatus?.finishedAt) {
    console.log(`  Finished on ${book.listeningStatus.finishedAt.toLocaleDateString()}`)
  }
})

Parameters:

Name	Type	Description
credentials	AudibleCredentials	Valid credentials

Returns: Promise<{ items: AudibleItem[], credentials: AudibleCredentials }>

Pagination is automatic — all items are fetched (50 per page).

---

wishlist(credentials)

Fetch the user’s entire Audible wishlist with automatic pagination. Credentials are auto-refreshed before the call.

const { items } = await wishlist(credentials)

items.map((book) =>
  console.log(`${book.title} — ${book.durationMinutes} min — ${book.publisher}`)
)

Parameters:

Name	Type	Description
credentials	AudibleCredentials	Valid credentials

Returns: Promise<{ items: AudibleItem[], credentials: AudibleCredentials }>

---

lastPositions(credentials, asins)

Fetch where the reader last stopped in each of the given titles. Asked in batches of 25, the most Audible accepts per call; a title the reader never opened is left out of the answer. Credentials are auto-refreshed before the call.

This is the reliable progress signal: listeningStatus.percentComplete on a library item is often stale — 0 on a title two hours in — while the position is what the player itself saves.

const { items } = await library(credentials)
const { positions } = await lastPositions(credentials, items.map(({ asin }) => asin))

positions.map(({ asin, positionMs, lastUpdatedAt }) =>
  console.log(`${asin} — ${Math.floor(positionMs / 60000)} min in, last heard ${lastUpdatedAt.toDateString()}`)
)

Parameters:

Name	Type	Description
credentials	AudibleCredentials	Valid credentials
asins	readonly string[]	The titles to ask about, any number

Returns: Promise<{ positions: LastPosition[], credentials: AudibleCredentials }>

---

catalog(credentials, options)

Search the Audible catalog by category with optional filters. Credentials are auto-refreshed before the call.

// Science Fiction sorted by relevance (default sort)
const { items } = await catalog(credentials, {
  category: 'science-fiction',
  limit: 20,
})

// Or using raw category ID
const { items: items2 } = await catalog(credentials, {
  categoryId: '21229020031',
  limit: 20,
})

items.map((book, i) => {
  const r = book.rating?.overallDistribution
  console.log(
    `${i + 1}. ${book.title} — ${r?.averageRating?.toFixed(1)}/5 (${r?.numRatings} votes)`
  )
})

Parameters:

Name	Type	Default	Description
credentials	AudibleCredentials	—	Valid credentials
options.category	AudibleGenre	—	Genre name, resolved per locale
options.categoryId	string	—	Raw category ID (alternative to category)
options.sortBy	string	'Relevance'	Sort order (see below)
options.limit	number | 'all'	50	Max results to return. Use 'all' to fetch everything
options.keywords	string	—	Search term filter
options.author	string	—	Filter by author name
options.narrator	string	—	Filter by narrator name

API sorts (fast) — single request, returns limit items: 'Relevance' (default), 'BestSellers', 'AvgRating', 'ReleaseDate', '-ReleaseDate', 'Title'

Client sort (slow): 'MostVoted' — fetches ALL pages (up to 1000 items), sorts by votes desc then rating desc, returns limit items. Can take 10-60 seconds on large categories.

Returns: Promise<{ items: AudibleItem[], credentials: AudibleCredentials }>

---

search(credentials, options)

Search the whole catalog of the account’s marketplace, without a category, most relevant first. Credentials are auto-refreshed before the call.

const { items } = await search(credentials, {
  title: 'Dungeon Crawler Carl',
  author: 'Matt Dinniman',
  limit: 20,
})

A marketplace also sells editions in other languages: filter on item.language when it matters.

Parameters:

Name	Type	Default	Description
credentials	AudibleCredentials	—	Valid credentials
options.keywords	string	—	Free search term
options.title	string	—	Title filter (a series name matches its volumes)
options.author	string	—	Author filter
options.narrator	string	—	Narrator filter
options.limit	number	10	Max results, at most 50

At least one of keywords, title, author or narrator is required; the call throws otherwise.

Returns: Promise<{ items: AudibleItem[], credentials: AudibleCredentials }>

---

product(credentials, asin)

Look one audiobook up by its ASIN in the account’s marketplace, whether or not the account owns it. Credentials are auto-refreshed before the call.

const { item } = await product(credentials, 'B0934Y4DMW')
if (item) console.log(item.title, item.series?.position)

Returns: Promise<{ item: AudibleItem | undefined, credentials: AudibleCredentials }> — item is undefined when the marketplace does not sell that ASIN.

---

verify(credentials)

Verify that credentials are valid by making a minimal API call. Credentials are auto-refreshed before the call.

try {
  await verify(credentials)
  console.log('Connected')
} catch {
  console.log('Credentials invalid')
}

Parameters:

Name	Type	Description
credentials	AudibleCredentials	Credentials to verify

Returns: Promise<void>

Throws: Error if credentials are invalid or expired

---

Configuration

AUDIBLE_LOCALES

A record mapping each AudibleLocale to its marketplace configuration.

import { AUDIBLE_LOCALES } from 'audible-api-ts'

AUDIBLE_LOCALES['fr']
// { domain: 'fr', marketplaceId: 'A2728XDNODOQ8T', countryCode: 'fr' }

AUDIBLE_LOCALES['com']
// { domain: 'com', marketplaceId: 'AF2M0KC94RCEA', countryCode: 'us' }

Type: Record<AudibleLocale, LocaleConfig>