• Home
  • Contact us
  • Create an account
  • Sign in
NHS TRUD
Search help

Using the API

This guide is for account holders who want to automate downloading release files.

Contents

  • Introduction
  • API key
  • Release list endpoint
  • Release download endpoint
  • Automating downloads

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 account management page.

Do not share account API keys.

Release list endpoint

Request

Make an HTTP GET request to a URL like this:

https://isd.digital.nhs.uk/trud/api/v1/keys/deadc0de/items/123/releases

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:

https://isd.digital.nhs.uk/trud/users/guest/filters/101/categories/2/items/14/releases

In this example the item number is 14.

To request only the latest release, add ?latest to the URL, like this:

https://isd.digital.nhs.uk/trud/api/v1/keys/deadc0de/items/123/releases?latest

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:

https://isd.digital.nhs.uk/download/api/v1/keys/deadc0de/content/items/58/nhs_odsweekly_5.2.0_20250508000001.zip

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 9am 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

PowerShell

Get-TrudRelease.ps1

Category filters

  • All categories
  • Classification products
  • NHS Data Model and Dictionary
  • Terminology products

Categories

  • All items
  • NHS Data Model and Dictionary XML Schemas
NHS Technology Reference Update Distribution (TRUD)
  • API
  • Cookies
  • Licences
  • Privacy policy
  • Terms and conditions