Introduction

Radiopaedia.org provides a REST API to integrate case uploads into your institution or application.

This API reference provides information on available endpoints and how to interact with it.

Access

To access the API, you need to obtain an access token. Please follow the steps below:

1. Visit New Application to register your integration.
2. Fill out the form and click submit when finished.
3. You will then see your application page. This page contains your APPLICATION_ID, CLIENT_SECRET, and one or more permitted REDIRECT_URLs.
4. You can later find this page later via https://radiopaedia.org/oauth/applications
5. To authorize your application, click on the Authorize button.
6. Click to confirm the authorization and save the Authorization code which will allow you to retrieve your ACCESS_TOKEN.
7. In order to retrieve an ACCESS_TOKEN you will need to perform a HTTP request.

For example, using curl:

curl \
  --data 'grant_type=authorization_code' \
  --data 'client_id=<APPLICATION_ID>' \
  --data 'client_secret=<CLIENT_SECRET>' \
  --data 'code=<AUTHORIZATION_CODE>' \
  --data 'redirect_uri=<REDIRECT_URL>' \
  https://radiopaedia.org/oauth/token

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "<REFRESH_TOKEN>",
  "created_at": 1706498077
}

Authenticate requests using an access token by setting the HTTP header Authorization: Bearer <ACCESS_TOKEN>

Both access_token and refresh_token should be stored.

Token expiration

Access tokens expire after 24 hours.

You may get a new one as follows, using the refresh token from the previous request. For example:

curl \
  --data 'grant_type=refresh_token' \
  --data 'client_id=<APPLICATION_ID>' \
  --data 'client_secret=<CLIENT_SECRET>' \
  --data 'refresh_token=<REFRESH_TOKEN>' \
  https://radiopaedia.org/oauth/token

The response follows the same format with an updated access_token and refresh_token, both of which should be stored (the previous values are no longer usable).

Authentication

OAuth 2.0

To authorize, use this code:

curl -H "Authorization: Bearer $TOKEN" -D - https://radiopaedia.org/api/<endpoint>

Make sure to replace $TOKEN with the access_token received from /oauth/token.

OAuth2 requests must be authenticated with a valid access token passed as bearer token. To use the bearer token, construct a normal HTTPS request and include an Authorization header with the value of Bearer.

Radiopaedia expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer $TOKEN

Check user quota

Radiopaedia limits how many draft/unlisted cases a user may create.
To avoid quota errors when uploading cases, you may first check that the user is not over their quota.
Users may increase their quota at https://radiopaedia.org/supporters
The /v1/users/current endpoint returns details of the authenticated user, including their username and account quotas.

curl -H "Authorization: Bearer $TOKEN" -D - https://radiopaedia.org/api/v1/users/current

Example Response

{
  "login": "johndoe82",
  "quotas": {
    "allowed_draft_cases": 10,
    "allowed_unlisted_cases": null,
    "allowed_unlisted_playlists": 10,
    "draft_case_count": 3,
    "unlisted_case_count": 2,
    "unlisted_playlist_count": 1
  }
}

The values allowed_draft_cases and allowed_unlisted_cases are the users quota of cases with that status.
A value of null for one of these properties indicates that the user has an unlimited quota of that resource.
The values draft_case_count and unlisted_case_count are the number of cases that the user currently has.
If the count value is equal to or greater than the allowed value, attempts to create additional cases will be rejected with an over quota error.

Create a blank case

Before uploading any images, you must first create a blank case & add a study to the case.

curl -H "Authorization: Bearer $TOKEN" -D - https://radiopaedia.org/api/v1/cases \
  --request POST \
  --header 'Content-Type: application/json' \
  --data "$(cat <<-JSON
{
  "title": "Case title",
  "system_id": 1,
  "diagnostic_certainty_id": 1,
  "suitable_for_quiz": true,
  "presentation": "Mild symptoms",
  "age": "34 years",
  "gender": "Male",
  "body": "<p>Discussion</p>"
}
JSON
  )"

Example Response

{
  "id": 8731,
  "title": "Title of the case",
  "author_id": 1,
  "created_at": "2024-01-29T11:20:19+11:00",
  "updated_at": "2024-01-29T11:20:19+11:00"
}

This will create a blank draft case record, to which you can add studies and free text components.
Draft cases are not available to view; their status may be updated via a subsequent PUT request.

Request Parameters

Add a study to a case

curl -H "Authorization: Bearer $TOKEN" -D - https://radiopaedia.org/api/v1/cases/:id/studies \
  --request POST \
  --header 'Content-Type: application/json' \
  --data "$(cat <<-JSON
{
  "modality": "CT",
  "findings": "This particular case was interesting ...",
  "position": 3,
  "caption": "Your caption for the study."
}
JSON
  )"

Example Response

{
  "case_id": 1,
  "created_at": "2024-01-29T11:20:19+11:00",
  "caption": "Your caption for the study.",
  "modality": "CT",
  "findings": "<p>This particular case was interesting ...</p>",
  "id": 34152,
  "updated_at": "2024-01-29T11:20:19+11:00"
}

Studies are required to be attached to a case. You will need to ensure that you have first created a case and retrieved a case_id so that you can use it when creating a study.

Barium
CT
DSA (angiography)
Fluoroscopy
MRI
Mammography
Nuclear medicine
Ultrasound
X-ray
Annotated image
Diagram
Pathology
Photo

Upload an image or stack (deprecated method)

curl -H "Authorization: Bearer $TOKEN" -D - https://radiopaedia.org/api/v1/cases/:id/studies/:study_id/images \
    --header 'Content-Type: image/png' \
    --request POST \
    --data-binary @image.png

{
    "id": 8731,
    "filename": "d125fdeb0ce8b603e753df69cbbbd4.png",
    "contributor_id": 1,
    "created_at": "2024-01-29T11:20:19+11:00",
    "updated_at": "2024-01-29T11:20:19+11:00"
  }

Upload an image or stack (current method)

Uploading an image requires three requests.
The first, to obtain one or more pre-signed URLs. These URLs allow you to upload the image data directly to our AWS S3 account, and are only valid for 15 minutes.
Then a second request, to upload the image data.
Finally, a third request, to attach the uploaded image data to the study.

To ensure upload integrity, we check that the SHA-256 of the uploaded file matches one you calculate before upload.
For each file you intend to upload, first calculate the SHA-256 hash. Then, request presigned URLs for each of those hashes:

curl -H "Authorization: Bearer $TOKEN" -D - https://radiopaedia.org/direct_s3_uploads \
  --request POST \
  --header 'Content-Type: application/json' \
  --data "$(cat <<-JSON
{
  "sha256": [
    "5279e636d769aeb7bf08cccda61c34b931987b2c6bba3e1fdf3bae7812751af0",
    "5279e636d769aeb7bf08cccda61c34b931987b2c6bba3e1fdf3bae7812751af1"
  ]
}
JSON
  )"

Example Response

{
  "uploads": [
    {
      "id": 1234,
      "url": "https://bucket.s3.amazonaws.com/by_sha256/5279e636d?X-Amz-Signature=4441596e"
    },
    {
      "id": 1235,
      "url": "https://bucket.s3.amazonaws.com/by_sha256/fdf3bae78?X-Amz-Signature=fas42w"
    },
    {
      "id": 1236,
      "status": "already_uploaded"
    }
  ]
}

You can now upload the files directly to s3. Any files which have have a status of "already_uploaded" do not need to be sent; the ID can still be used as normal.

Any DICOM files uploaded must first be anonymized.
Radiopaedia will check this via https://github.com/radiopaedia/dicom-anonymiser .
To protect patients, API clients found to have uploaded patient data will be suspended until the issue can be resolved.
If you use our anonymiser implementation to check your files before upload, we do not anticipate this happening.
Contact [email protected] if you run into issues.

curl -X PUT --data-binary @000000001.dcm 'https://bucket.s3.amazonaws.com/by_sha256/5279e636d?X-Amz-Signature=fas42w'
curl -X PUT --data-binary @000000002.dcm 'https://bucket.s3.amazonaws.com/by_sha256/fdf3bae78?X-Amz-Signature=fas42w'

Once the file upload completes, you can add the image(s) you have uploaded to a study.
Do not attempt to add files which have not finished uploading.
To reference an uploaded image, use the ID value that matches its SHA-256.

A request that specifies multiple upload IDs will create a single stack, with the order of slices of the stack matching the order you supply them.
Specify the index of the "primary" image of the stack in the root_idx parameter. For example:

curl -H "Authorization: Bearer $TOKEN" -D - https://radiopaedia.org/image_preparation/:case_id/studies/:study_id/series \
  --header 'Content-Type: application/json' \
  --request POST \
  --data "$(cat <<-JSON
{
  "image_format": "application/dicom",
  "series": {
    "root_index": 1
  },
  "stack_upload": {
    "uploaded_data": {
      "0": 1234,
      "1": 1235,
      "2": 1236
    }
  }
}
JSON
  )"

Example Response

{
  "id": 8731,
  "filename": "d125fdeb0ce8b603e753df69cbbbd4.png",
  "contributor_id": 1,
  "created_at": "2024-01-29T11:20:19+11:00",
  "updated_at": "2024-01-29T11:20:19+11:00"
}

Mark Upload Finished

To prevent conflicts between edits via API and via the main site, cases cannot be edited on the site until they are marked "upload finished".

curl -H "Authorization: Bearer $TOKEN" -D - https://radiopaedia.org/api/v1/cases/:id/mark_upload_finished \
      --request PUT \
      --header 'Content-Type: application/json'

Example Response

{
  "id": 8731,
  "title": "Title of the case",
  "author_id": 1,
  "created_at": "2024-01-29T11:20:19+11:00",
  "updated_at": "2024-01-29T11:20:19+11:00"
}

Diagnostic Certainty

The Radiopaedia diagnostic certainties are as below:

Errors

The Radiopaedia API uses the following error codes:

Systems

The Radiopaedia systems are as below: