NAV
shell

Introduction

Radiopaedia.org provides a simple and powerful 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 the developer page.
  2. Click on the Manage your applications button to access your API applications.
  3. Click on the New Application button to create a new application.
  4. Fill out the form and click submit when finished. Note: scopes field should contain cases.
  5. You will then see your application page. This page contains your application id, secret, scopes and redirect urls.
  6. To authorize your application, click on the Authorize button. You will be prompted to confirm the authorization. Click Authorize to do so.
  7. You will then be presented with your Authorization code. Make sure you save it, as it will be required to retrieve your access token.
  8. In order to retrieve an access token you will need to perform a HTTP request. For example, using curl:
  9. Please make sure that you store both ‘access token’ and 'refresh token’, that are returned in a response body.
curl --data 'client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&code=<AUTHORIZATION_CODE>&grant_type=authorization_code&redirect_uri=<CALLBACK_URL>' https://production.radiopaedia.org/oauth/token

Token expiration

Access token’s expiration time is 24 hours.

In order to obtain a new access token, you will need to make a request to https://production.radiopaedia.org/oauth/token and include your previously saved refresh token. Example curl:

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

Authentication

OAuth 2.0

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Bearer your_token"

Make sure to replace your_token with your API key.

OAuth2 is recommended when you’re creating an application for others on top of Radiopaedia platform. This authentication provides a secure and easy to use authentication flow for users.

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 your_token

Diagnostic Certainty

The Radiopaedia diagnostic certainties are as below:

ID Name Description
1 Possible The diagnosis is possible but has not been established for certain. There are other differential diagnostic possibilities.
2 Probable The diagnosis is considered by far the most likely but has not been established for certain. Other unlikely differential diagnostic possibilities exist.
3 Confirmed unsubstantiated The diagnosis is considered to be almost certain based on the highly characteristic imaging appearance or based on clinical, surgical or pathological knowledge obtained by the uploader from a secondary source rather than a primary source. A statement regarding this secondary source of proof should be included with the case.
4 Confirmed substantiated The diagnosis is 100% certain based on the unequivocal or pathognomonic imaging appearance, or based on clinical, surgical or pathological proof directly obtained from a primary source by the uploader. A statement regarding this primary source of proof, along with appropriate substantiating evidence (e.g. histology report/slides, diagnostic laboratory test/values), should be included with the case.
5 Not applicable The images are not of a patient with a particular diagnosis. For example, they may be a normal scan for teaching purposes, or alternatively a diagram or flow chart.

Errors

The Radiopaedia API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request was malformed
401 Unauthorized – Your Authentication token is not valid
403 Forbidden – The resource requested is hidden for administrators only
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The resource requested has been removed from our servers
429 Too Many Requests – You’re requesting too many resources! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Systems

The Radiopaedia systems are as below:

ID Name
1 Breast
2 Vascular
3 Central Nervous System
4 Chest
6 Gastrointestinal
7 Head & Neck
8 Hepatobiliary
9 Musculoskeletal
11 Urogenital
12 Paediatrics
15 Spine
16 Cardiac
17 Interventional
18 Obstetrics
19 Gynaecology
20 Haematology
shell