Skip to content

Download API v2

The Download API v2 is a legacy API that's no longer receiving updates or improvements.

Most API implementations now use the downloadRedirect endpoint of the Checkouts API instead of the Download API. Visit the Checkouts API to learn more about the downloadRedirect endpoint.

If your implementation has been granted access to the Download API for direct fulfillment, you can use this documentation.

The legacy Download API allows you to GET a contentLink, which requests a title from our (or our outside provider's) fulfillment servers. Each format, like magazine-overdrive or ebook-adobe, has a contentLink that works a little differently.

Note: The examples below show our production API URL. If you're using our integration environment, use https://integration-patron.api.overdrive.com.

If you're using the Download API v1 in your product, you can find the original documentation here. We'll continue to support the prior query parameters, but we recommend that you switch to v2 as soon as possible.

Using the Download API

Make a GET request to the downloadLink endpoint with the title's reserve ID. You can find the downloadLink template in the Checkouts API response (in the linkTemplates section).

Resource URL

https://patron.api.overdrive.com/v2/patrons/me/checkouts/{reserve ID}/formats/{format}/downloadlink?errorurl={errorurl}

Tip: On OverDrive websites, we automatically filter out formats that aren't compatible with the device that's being used to access the site (based on user agent). This way, users only see formats they can get with the device they're using. If you'd like a similar feature, it's something you'll have to develop independently in your app or website.

The {errorurl} parameter requires you to supply a base error page URL. In our example GET below, we replaced the {errorurl} value with https://www.yourwebpage.com/errorpage.htm. If there is a fulfillment error when processing your GET request, the error code will be returned and appended to your supplied error page URL using the following query string parameters:

ParameterDescription
ErrorCodeAn OverDrive-specific error code
ErrorDescriptionA basic description of the error
ErrorDetailsA more detailed description of the error. You may want to consider logging this information rather than displaying it to end users.
reserveIdOverDrive streaming titles will return this to identify which title encountered the error.
read_errorAn error specific to OverDrive Read and OverDrive Listen (see "OverDrive Read and Listen errors" below)

Note: All query string parameters must be URL encoded.

To GET a contentLink, the format you're requesting must be locked in (unless it's a format that's always available, like ebook-overdrive or audiobook-overdrive).

Example request

GET https://patron.api.overdrive.com/v2/patrons/me/checkouts/864604e2-0146-46ef-a96d-d9977dc15263/formats/ebook-overdrive/downloadlink?errorurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com
Connection: Keep-Alive

Example response

200 OK
Date: Thu, 29 Aug 2024 20:56:03 GMT
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Length: 599
Content-Type: application/json; charset=utf-8
         
{
    "reserveId": "864604e2-0146-46ef-a96d-d9977dc15263",
    "crossRefId": 686192,
    "formatType": "ebook-overdrive",
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v2/patrons/me/checkouts/864604e2-0146-46ef-a96d-d9977dc15263/formats/ebook-overdrive/downloadlink?errorUrl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm",
            "type": "application/vnd.overdrive.circulation.api+json"
        },
        "contentlink": {
            "href": "https://fulfill.contentreserve.com/GoneGirl_9780307588388_686192.epub-sample.overdrive.com?RetailerID={id}&Expires=1724968563&Token=cdc322dd-e949-4f26-85c6-b1db011711f5&Signature=ibQNWRczs8RlYtoIYTT%2fsUr3t9I%3d",
            "type": "text/html"
        }
    }
}

You can then use the contentLink to download the title.

  • For Adobe EPUBs: the contentLink delivers an ACSM file that opens in Adobe Digital Editions.
  • For OverDrive Read, OverDrive Listen, MediaDo Reader, and magazines: the contentLink opens the title in its in-browser reader or player.

Note: contentLinks are one time use and are only valid for 60 seconds. If fulfillment is not completed within that timeframe, you’ll need to request a new contentLink.

OverDrive Read and Listen errors

There are a series of error codes associated specifically with OverDrive Read and OverDrive Listen fulfillment. Possible errors:

  • D001: missing
    No message was supplied in the request.
  • D002: stale
    The contentLink used was more than 60 seconds old when Read or Listen tried to open it.
  • D003: expired
    The lending period has expired for the requested ebook or audiobook.
  • D004: message reused
    The contentLink was already used to access the ebook or audiobook.
  • D101: message signature mismatch
    The "signature" doesn't match the message. This can indicate a failed attempt to forge the message.
  • D102: message unreadable
    The attempt to load the object via JSON and base64 failed, or required properties were missing.
  • D103: theme unavailable
    The message specifies a theme, but the theme is not in the connector's list of available themes.
  • D104: book not found
    No ebook or audiobook was found that matches the reserveId in the given domain name.
  • D105: book not in your catalogs
    An ebook or audiobook matching the reserveId was found, but not in any of the catalogs the connector has access to.
  • D106: book not compatible with outlet
    The ebook or audiobook was found, but the wrong outlet (player or reader) tried to open the file (e.g., an ebook tried to open in OverDrive Listen).