Using the API
This guide is for account holders who want to automate downloading release files.
Contents
Introduction
The API provides 2 endpoints (URLs you can send requests to). These let you:
- list available releases for an item
- download a release file using a link provided by the list endpoint
These endpoints are available to all account holders for items they are subscribed to.
API key
Each account has a unique API key, derived from the account's email address and password. If either of these changes, a new key is generated and the old one is disabled.
The API key for an account is shown on the Your account page.
Keep your API key private. If someone else gets it, they can use the API as if they were you.
Release list endpoint
Request
Make an HTTP GET request to a URL like this:
Replace deadc0de with the API key, and 123 with the item number.
Item numbers can be found in the URLs of releases pages. For example, the URL for the NHS National Interim Clinical Imaging Procedures releases page is:
In this example the item number is 14.
To request only the latest release, add ?latest to the URL, like this:
Successful response
A JSON object that includes all the information shown on the releases page, plus extra details such as digital signatures.
The releases appear in the same order as on the releases page, from new to old.
Here's an example response from the API:
{
"apiVersion" : "1",
"releases" : [ {
"id" : "nhs_odsweekly_5.2.0_20250508000001.zip",
"name" : "Release 5.2.0",
"releaseDate" : "2025-05-08",
"archiveFileUrl" : "https://isd.digital.nhs.uk/download/api/v1/keys/deadc0de/content/items/58/nhs_odsweekly_5.2.0_20250508000001.zip",
"archiveFileName" : "nhs_odsweekly_5.2.0_20250508000001.zip",
"archiveFileSizeBytes" : 12728891,
"archiveFileSha256" : "285354105EA8ED362CDD5E517DC687266DB6188B1B80133D2C55AE730A508159",
"archiveFileLastModifiedTimestamp" : "2025-05-07T08:51:21.000Z",
"checksumFileUrl" : "https://isd.digital.nhs.uk/download/api/v1/keys/deadc0de/content/items/58/trud_nhs_odsweekly_5.2.0_20250508000001.xml",
"checksumFileName" : "trud_nhs_odsweekly_5.2.0_20250508000001.xml",
"checksumFileSizeBytes" : 187,
"checksumFileLastModifiedTimestamp" : "2025-05-07T10:34:28.000Z",
"signatureFileUrl" : "https://isd.digital.nhs.uk/download/api/v1/keys/deadc0de/content/items/58/trud_nhs_odsweekly_5.2.0_20250508000001.xml.asc",
"signatureFileName" : "trud_nhs_odsweekly_5.2.0_20250508000001.sig",
"signatureFileSizeBytes" : 488,
"signatureFileLastModifiedTimestamp" : "2025-05-07T10:34:28.000Z",
"publicKeyFileUrl" : "https://isd.digital.nhs.uk/download/api/v1/keys/deadc0de/content/public-keys/trud-public-key-2013-04-01.pgp",
"publicKeyFileName" : "trud-public-key-2013-04-01.pgp",
"publicKeyFileSizeBytes" : 1736,
"publicKeyId" : 6
} ],
"httpStatus" : 200,
"message" : "OK"
}
Error responses
If the API key is invalid:
{
"apiVersion" : "1",
"httpStatus" : 400,
"message" : "BAD REQUEST"
}
If the item number is invalid:
{
"apiVersion" : "1",
"releases" : [ ],
"httpStatus" : 404,
"message" : "NOT FOUND: No releases found for API key deadc0de, item 9999."
}
If the requesting account is not subscribed to the requested item:
{
"apiVersion" : "1",
"releases" : [ ],
"httpStatus" : 404,
"message" : "NOT FOUND: No releases found for API key deadc0de, item 123."
}
Release download endpoint
Request
Make an HTTP GET request to a URL from a previous release list response, like this:
Successful response
Downloads the requested release file.
Error responses
All error conditions result in an HTTP 404 error response.
Automating downloads
Run automation scripts on weekdays between 8am and 6pm, or midnight and 6am (UK time) to avoid planned maintenance.
The following sample scripts use the API to automate downloads. They assume a valid API key is set in the TRUD_API_KEY environment variable.
Bash
trud-api-download-release.bash