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://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://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://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

Cases

Create a case

 curl https://radiopaedia.org/api/v1/cases --request POST --data '{"title":"Case title","system_id":1,"diagnostic_certainty_id":1,"suitable_for_quiz":true,"presentation":"Mild symptoms","age":"34 years","gender":"Male","body":"\u003cp\u003eDiscussion\u003c/p\u003e"}' --header 'Content-Type: application/json' --header 'Authorization: Bearer <YOUR_TOKEN>' --verbose

Example Response

{
  "id": 8731,
  "title": "Title of the case",
  "author_id": 1,
  "created_at": "2017-12-11T11:53:55+11:00",
  "updated_at": "2017-12-11T11:53:55+11:00"
}

This will give you a blank case record so that you are able to add studies and free text components. All cases that are initially created, will not be available to view until the case visibility or status have been updated in a PUT request to the resource.

HTTP Request

POST https://radiopaedia.org/api/v1/cases

Request Parameters

Parameter Type Required / Values Description
title String true Title of the case
system_id Integer true The id of the System that is to be associated with the case. A list of available ids can be found here
diagnostic_certainty_id Integer false The id of the Diagnostic Certainty that is to be associated with the case.A list of available ids can be found here
suitable_for_quiz Virtus::attribute::boolean false Whether or not this case will be made available in quiz mode.
presentation String false Presentation information of patient’s symptoms, history, etc.
age String false The age of the patient in the case. Do not provide specifics.
gender String false The gender of the patient in the case. \

Should be either Male or Female body | String | false | More information and details about a case. HTML tags should be used.

Mark Upload Finished

Make case editable on Radiopaedia.org

 curl https://radiopaedia.org/api/v1/cases/:id/mark_upload_finished --request PUT --header 'Content-Type: application/json' --header 'Authorization: Bearer <YOUR_TOKEN>' --verbose

Example Response

{
  "id": 8731,
  "title": "Title of the case",
  "author_id": 1,
  "created_at": "2017-12-11T11:53:55+11:00",
  "updated_at": "2017-12-11T11:53:55+11:00"
}

This will make the case available to be updated on Radiopaedia.org. This is done to avoid conflicts from changes made by users whilst it is being uploaded by the API.

HTTP Request

PUT https://radiopaedia.org/api/v1/cases/:id/mark_upload_finished

Free Texts

Create a free text entry

 curl https://radiopaedia.org/api/v1/cases/:id/free_texts --request POST --data '{"description":"\u003cp\u003eYour description here\u003c/p\u003e","position":2}' --header 'Content-Type: application/json' --header 'Authorization: Bearer <YOUR_TOKEN>' --verbose

Example Response

{
  "case_id": 8731,
  "created_at": "2017-12-11T11:53:55+11:00",
  "description": "Your description here",
  "id": 37821,
  "updated_at": "2017-12-11T11:53:55+11:00"
}

Free text entries can be attached to a case to provide additional information that is not specific to a study.

HTTP Request

POST https://radiopaedia.org/api/v1/cases/:id/free_texts

Request Parameters

Parameter Type Required / Values Description
description String true The content for the free text entry. HTML tags should be used.
position Integer false The position in the case where you would like the free text \

component to be inserted.

Studies

Create a study

 curl https://radiopaedia.org/api/v1/cases/:id/studies --request POST --data '{"modality":"CT","findings":"This particular case was interesting ...","position":3,"caption":"Your caption for the study."}' --header 'Content-Type: application/json' --header 'Authorization: Bearer <YOUR_TOKEN>' --verbose

Example Response

{
  "case_id": 1,
  "created_at": "2017-12-11T11:53:55+11:00",
  "caption": "Your caption for the study.",
  "modality": "CT",
  "findings": "This particular case was interesting ...",
  "id": 34152,
  "updated_at": "2017-12-11T11:53:55+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.

HTTP Request

POST https://radiopaedia.org/api/v1/cases/:id/studies

Request Parameters

Parameter Type Required / Values Description
modality String false [“Barium”, “CT”, “DSA (angiography)”, “Fluoroscopy”, “MRI”, “Mammography”, “Nuclear medicine”, “Ultrasound”, “X-ray”, “Annotated image”, “Diagram”, “Pathology”, “Photo”] The chosen modality for your study.
findings String false The findings of your study.
position Integer false The position in the case where you would like the free text \

component to be inserted. caption | String | false | Caption

Images

Upload an image or stack

 curl https://radiopaedia.org/api/v1/cases/:id/studies/:study_id/images --request POST --data-binary @image.png --header 'Content-Type: image/png' --header 'Authorization: Bearer <YOUR_TOKEN>' --verbose

Example Response

{
  "id": 8731,
  "filename": "d125fdeb0ce8b603e753df69cbbbd4.png",
  "contributor_id": 1,
  "created_at": "2017-12-11T11:53:55+11:00",
  "updated_at": "2017-12-11T11:53:55+11:00"
}

Images or stacks of images can be attached to studies. You will need to ensure that you have first created a study and retrieved a study_id so that you can use it when uploading an image or stack. The image or stack data should be sent as the body of the request.

HTTP Request

POST https://radiopaedia.org/api/v1/cases/:id/studies/:study_id/images

Request Headers

Header Required Values Description
Content-Type true ["application/zip", "image/jpeg", "image/bmp", "image/png", "image/gif", "video/mp4"] Defines content media type

Institutions

Returns a list of institutions matching the search query

 curl https://radiopaedia.org/api/v1/institutions/search --request GET --header 'Content-Type: application/json' --header 'Authorization: Bearer <YOUR_TOKEN>' --verbose

HTTP Request

GET https://radiopaedia.org/api/v1/institutions/search

Query Parameters

Parameter Type Required / Values Description
query String true
verified Virtus::attribute::boolean false

Users

Get current user

 curl https://radiopaedia.org/api/v1/users/current --request GET --header 'Content-Type: application/json' --header 'Authorization: Bearer <YOUR_TOKEN>' --verbose

Example Response

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

Returns details of the authenticated user including username and account quotas. Note that the scope users must be enabled for the application to fetch this resource.

The values for allowed_draft_cases, allowed_unlisted_cases, allowed_unlisted_playlists are the number of those resources that this user may create. A value of null for one of these properties indicates that the user has an unlimited quota of that resource.

draft_case_count, unlisted_case_count, and unlisted_playlist_count are the count of these resources that the user currently has. If the “count” value is equal to or greater than the “allowed” value then attempts to create additional resources of that kind will be rejected with an over quota error.

HTTP Request

GET https://radiopaedia.org/api/v1/users/current

Countries

Returns your country based on request IP

 curl https://radiopaedia.org/api/v1/countries/current --request GET --header 'Content-Type: application/json' --header 'Authorization: Bearer <YOUR_TOKEN>' --verbose

HTTP Request

GET https://radiopaedia.org/api/v1/countries/current

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