Overview

Slide Score API allows programmatically uploading slides, creating studies and downloading results.

You can for example:

It can only be enabled by site administrators.

This API is based on common tasks that need to be done. A next version of API based on GraphQL with more control for all important entities is on the roadmap.

Note that this documentation assumes some programming knowledge and is a work in progress.

Examples

You can either write a script that sends the HTTP requests directly or make use of C# or Python SDKs. If you use C# have a look at an example client in C# that includes SlideScoreClient.cs class that will help you make the API calls.

For Python install the SDK module with pip install slidescore-sdk, initiate the client class:

from slidescore import *
client = APIClient(url, apitoken)

The client object has methods that directly correspond to the API calls.

Creating Token

Before you can access the API you need an access token.

Login as Site Administrator and go to the Create Token page.

Fill in the name and expiration date of the token. Check below what methods you need to call and give the token only the rights that are needed only for the necessary studies.

Can upload

API token can upload slides and configuration files

Can create upload folders

API token can create folders on the server to create new studies

Can upload scores

API token can upload results and annotations to studies. This is useful for image analysis workflows - models can push their results to Slide Score.

Can download configuration files for studies

API token can request the current configuration of studies in the form of configuration files. This is useful if you want to synchronize external database with Slide Score configuration.

Can read raw tiles from slides and their metadata

API token can read image tiles. The API has 3 ways to access the pixels GetScreenshot (the most high level call - request a region and level of detail), GetTile (DeepZoom-like request), GetRawTile (request that's forwarded to the slide libraries - OpenSlide and others. You need to check the image metadata first - levels in the slide and so on).

With this right image analysis algorithm can request (and cache) the pixels of slides.

Can upload only in folders

This is a restriction.

Semicolon-separated list of folders on the server to which the token can upload. If you leave it empty API token can upload slides in any folder. If you set it API token won't be allowed to upload to any other folders.

Can read (get scores, images) only these studies

This is a restriction.

Semicolon-separated list of studies which the token can read - download scores (with Can get scores of any study), images, ... If you leave it empty API token can read any study. If you set it API token won't be allowed to read any other studies.

Can modify (upload images, delete, reimport) only these studies

This is a restriction.

Semicolon-separated list of studies which the token can modify - add slides, reimport, ... If you leave it empty API token can modify any study. If you set it API token won't be allowed to modify any other studies.

Can create studies

Unused at the moment

Can reimport studies

API token can (after uploading configuration files and slides) re-import a study.

This will read configuration files and apply changes to the study. Note that it can overwrite changes made manually in the administration interface - you can use GetConfigFiles to create up-to-date config files and change only those.

You always need to run reimport after you upload the slide(s) using the API otherwise they won't show up.

Can delete owned studies

Unused at the moment

Can get scores of owned studies

API token can retrieve (unless Can read blocks it) scores of studies that the token has created.

Can get scores of any study

API token can retrieve (unless Can read blocks it) scores of any study.

Can get study configuration

API token can retrieve (unless Can read blocks it) configuration files of any study and can send emails on behalf of the Slide Score server.

Authentication

This API token needs to be supplied for all API calls in the Authorization HTTP Header like this:

Authorization: Bearer hblJlYWRPbmx5U....3R1ZGllcyI6IiIsIkNhbk1

When you no longer need it you can give it up by calling POST /Admin/GiveupToken with the token as POST parameter.

Get results

GET Api/Scores

Required rights: Can read the study, Can get scores of owned studies or at least Can get scores of any study if it was created by the API token

Parameters:

Name Type Required Explanation
studyId int yes Study which you want to download scores from

Returns tab separated file with all the scores from the study. The format is the same as when downloading results manually.

GET Api/GetStudiesUpdated

Required rights: Can read, Can get scores of owned studies or at least Can get scores of any study if it was created by the API token

Parameters:

Name Type Required Explanation
since string yes ISO 8601 date and time string with timezone

Returns JSON object with an array of integer IDs in StudyIDs - IDs of studies that had results submitted since the given date You can use this method if you are periodically checking for new results.

Get images

GET Api/Images

Required rights: Can read

Parameters:

Name Type Required Explanation
studyId int yes Study which you want to list images from

Returns

JSON array of images with their ID and Name. Useful for creating reports with links to view the slide. You can construct an URL like https://server/Image/Details?imageId=1&studyId=2 that will open image with ID=1 in study with ID=2. For TMAs you can use additional GET parameters to select single or few cores:

Upload

Uploading a file has 3 steps:

  1. POST RequestUpload
  2. Upload using Tus.io
  3. POST FinishUpload

POST RequestUpload

Required rights: Can upload

Parameters:

Name Type Required Explanation
filename string yes Filename (without path) to use for the file on the server - this can be used to rename slides
folder string no Folder on the server (under the images root) to which the file should be uploaded. Note that you can only upload to the root folder, it subfolders and their subfolders, if empty studyId has to be set and it will determine the folder
studyId int no if folder is not set it will be set to name of this study

Returns

JSON object with token attribute. This is the upload token you will need for uploading.

Upload using Tus.io

You can use any of Tus.io's clients to perform the upload. Add uploadtoken that you've received from previous step and API token (as apitoken) as metadata. You will receive fileid that you will need in the next step

POST FinishUpload

Required rights: Can upload

Parameters:

Name Type Required Explanation
token string yes upload token from RequestUpload
id string yes fileid from Tus.io

Returns

JSON string containing "OK"

When Tus is done uploading you have to commit the upload using this method.

Uploading Results

It's possible to upload scoring results to Slide Score - this is useful if you have some legacy slides that you want to review or you are moving all the data to a single repository - Slide Score. This is also very useful for Active learning - training image analysis models with manual corrections with quick turn-around.

POST Api/UploadResults

Required rights: Upload scores

Parameters:

Name Type Required Explanation
studyId int yes Study where results should be imported
results string yes The results should have the same format as when you download them from Slide Score

This is the format of results expected:

ImageID(tab)Name(tab)By(tab)(optionally: TMA Row(tab)TMA Col(tab)TMA Sample(tab))Question(tab)Answer

ASAP interoperability

Slide Score supports exchanging annotations with ASAP. Since both programs use slightly different way to organize the annotations you might want to specify how to map colors in ASAP to questions in Slide Score.

GET Api/ExportASAPAnnotations

Required rights: Can get scores

Parameters:

Name Type Required Explanation
imageId int yes Image for which annotations should be exported
user string yes User whose annotations/answers should be exported
question string no Which question to export if there are multiple annotation-type questions. Can be empty to export all

Returns

Single XML file containing annotations for image imageId created by user user for the question (it has to be of type AnnoShapes or AnnoPoints). This XML file can be loaded straight to ASAP.

POST Api/UploadASAPAnnotations

Required rights: Upload scores

Parameters:

Name Type Required Explanation
imageid int yes Image for which annotations should be imported
user string yes User under whose account these annotations/answers should be imported
asapAnnotation string yes Contents of the ASAP XML file
questionsMap string no Defines mapping between colors used in the annotation file and questions defined in the study in Slide Score, see below

questionsMap: Each mapping is on a new line and consists of color hex code, semicolon (;) and the name of the question. Example mapping file:

#f0f0f0;Lymphocytes
#ff0000;Tumor area

If you don't specify questionsMap each new color of annotations will be imported into a new question called "Imported annotation #".

Returns

JSON object with attribute Success (true for successful import) and Log containing log of the the import detailing generated questions and more.

Screenshots

GET Api/GetScreenshot

Required rights: Can get scores, Can get pixels

Parameters:

string withAnnotationForUser, int x, int y, int width, int height, int level, string scoreIDs

Name Type Required Explanation
imageID int yes Image to screenshot
x int no screenshot top-left corner coordinate in pixels, if x, y, width and height are 0 the whole image is imaged
y int no screenshot top-left corner coordinate in pixels, if x, y, width and height are 0 the whole image is imaged
width int no screenshot width in pixels, if x, y, width and height are 0 the whole image is imaged
height int no screenshot height in pixels, if x, y, width and height are 0 the whole image is imaged
withAnnotationForUser string no If the study has annotation-type questions you can include particular user's answers-annotations in the screenshot
scoreIDs string no If the study has annotation-type questions you can include only particular questions to only select some annotations to include. If you leave it empty all annotations by withAnnotationForUser will be added
level int yes DeepZoom level - binary exponent of the larger dimension of the resulting image - 11 for an image with larger dimensions between 1024 and 2048 pixels, 12 for 2048 - 4096 and so on

Returns

JPEG file with the screenshot. Note that this method can be slow and won't work for more than ~50 megapixel images. Please, request smaller ones and stitch them together.

Sending emails

POST Api/SendEmail

Required rights: Can get configuration files

Parameters:

Name Type Required Explanation
studyId int yes Study that email is related to
to string yes Semicolon (;) separated list of email addresses to send it to, they have to be configured as users of the study
subject string yes Email Subject line
body string yes Text of the email to send. In plain text. It can contain token <LINK:Start Scoring> which will be replaced with a link to start scoring the study

It will send an email to all addresses listed in to. The From address will be info@slidescore.com.

Returns

Empty JSON object if successful.

Study configuration

Studies are set up by uploading configuration files to the root folder and image files into a subfolder. If the subfolder has the same name as the study all image files there are automatically uploaded. Otherwise you need to reference them with an study.<studyname>.images file (see Slides for more).

Users

Users are configured in a file study.<studyname>.emails. This file contains one user of the study per line.

By default they get only CanScore right. You can specify viewonly or additional rights (cangetresults, canscore, canedit) separated by comma if you want to change that. Note that you can't remove rights from a user this way, they are only added. To remove user's rights, use the administration interface.

For example:

email@example.com
email2@example.com;viewonly
email3@example.com;canscore,canedit,cangetresults

Slides

By default all slides in a folder that has the same name as the study are imported. Additionally, this folder can contain *.images file that references images, one image per line. You can also specify TMA map, rotation to use with the image and potential new name, like this:

../otherfolder/1.svs
../otherfolder/2.svs;study.example.map;90
../otherfolder/011938r082.tif;;Nice Image

Note that TMA map, rotation or new name can be left out or empty and they will be ignored.

TMA Maps

You can import a TMA Map in two ways - either reference it in an .images file in study's folder or create a map file with the name study.<studyname>.map<additional identifier> in the root folder. The map file can be divided into a header and the actual map.

Header contains properties and their values separated by a colon (:). Header properties can be:

The header is terminated by an empty line. The map starts under it. Each line in a map is a row of TMA core IDs, columns are separated by TAB character. If a line doesn't have the same number of columns as the longest row it will be padded by empty cores.

Here is an example of a simple map:

tmas: 1.svs
controls: ctrl
ignore: 0, empty
force: true

1   1   1   ctrl    ctrl    ctrl
2   2   2   3   3   3
0   0   0   4   4   4
5   5   5   empty   empty   empty

The imported map applies to 1.svs and looks like this

Example TMA map

Study Settings

Study settings are configured in the study.<studyname>.config file.

It contains properties of the study, in the format property name: value (or value1,value2)

Recognized properties:

allowchangingscores
allowresultscomparisonforeveryone
allowsharingslidesanonymously
artid
disallownavigation
disallowrewritingscores
disease
folder
friendlyname
hideslidenames
organ
scoretmacoresatonce
showduplicates
showlabels
showotherpeoplesscores
showslidenames
showthumbnails
showtmasampleids
stainings

Questions

The questions that form study's scoring sheet are listed in study.<studyname>.scores. The format is a bit complicated, it's best to create the scoring sheet in the Question editor, click the Share button and copy the value of the f URL parameter to the questions file. In principle it has one line per question - name of the question followed by a semicolon (;), question type (FreeText, DropDown, Percentage, Checkbox, ...), followed by another semicolon and optionally other configuration for the question (options for a DropDown for example).

Importing

After uploading all important files call the POST Api/Reimport method with studyName as POST parameter which will create the study based on the config files and return a log of how did it go. If you need to change an existing study you can upload modified config files and run Reimport again. Note that nothing gets removed, only added. Furthermore, if you've removed an image or users using the administration interface it will be added again if it is in the config files. You can add ignoreImageErrors=true parameter to treat unrecognized or inaccessible images as warnings and proceed with import.

Note that you can't delete files on the server only overwrite them.

Synchronizing

All users with CanEdit right can enter the administration interface and make changes to the study. Often it's needed to rotate some images, adjust a TMA map or reorder questions. However, when you call Reimport next time these changes can be overwritten. To prevent this from happening use GET Api/GetConfig method with study ID as a parameter. It will return the complete configuration of a study as an object graph (for details see the API client).

Clone a study

You can easily clone a study as it is by requesting the configuration files of an existing study using Get Api/GetConfigFiles method with study ID as a parameter. This will return JSON object with content of all the configuration files. Note that they are dynamically generated from the database - these are not necessarily the same files that were used to create the study.