Slide Score API allows programmatically creating studies, uploading slides and downloading results. It can only be enabled by administrators. See an example client in C# for details of usage.
A next version of API based on GraphQL with more control for all important entities is on the roadmap.
Note that this documentation is a work in progress.
- Get Images
- Get Results
- Setting up study config files
- (Re-)Importing a study
- Uploading Results
- ASAP interoperability
Before you can invoke any API method you need to obtain an API token.
Login as Administrator and go to the Create Token page. Fill in the name, expiration, limitations and capabilities this token will have and press Create.
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 Api/Scores?studyId= with a study ID returns tab separated file with all the scores from the study. The format is the same as when downloading results manually.
If you are periodically checking for new results, you can use
GET Api/GetStudiesUpdated?since= with ISO 8601 formatted date and time string (including the time zone) to request IDs of studies that had results submitted since given date. The result is a JSON object with an array of integer IDs in
GET Api/Images?studyId= with a study ID returns a JSON array of images with their
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:
tmaColfor row and column (0-based) respectively
tmaSamplesearches for TMA core with this Sample ID. If it is unique it selects and zooms in otherwise it shows up in the "Search" panel
tmaIdinternal TMA core ID
Uploading a file has 3 steps:
- POST RequestUpload - Specify which folder on the server to upload to and under what filename, you will receive an
uploadtoken. You can only upload to the root folder or one folder below - you can't create a folder inside a folder.
- Upload using Tus.io - Add
uploadtokenand API token (as
apitoken) as metadata, you will receive
- POST FinishUpload - When Tus is done uploading you have to commit the upload using the
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 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 (
canedit) separated by comma if you want to change that.
firstname.lastname@example.org email@example.com;viewonly firstname.lastname@example.org;canscore,canedit,cangetresults
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.
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:
tmascomma-separated list of slides that this map applies to
controlscomma-separated list of TMA core IDs in the map that should be considered controls and not scored
ignorecomma-separated list of TMA core IDs in the map that should be ignored - they will show up as empty space
rotatespecifies the clockwise rotation that should be applied to all slides listed in
tmasin multiples of 90. Note that you can't change the rotation for a slide individually you need to create a new map for each rotation
origmappath to the original TMA map - usually an Excel file - that users can download from the slide viewer for cross-checking
forceif you set this to true everytime this study is reimported all scores and positions belonging to cores from this map will be deleted. If you don't set it to true the map is used only on the first import and you can't change anything afterwards. Use carefully!
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
Study settings are configured in the
It contains properties of the study, in the format
property name: value (or value1,value2)
artid allowchangingscores allowsharingslidesanonymously cbioportalid disease emailimageadded emailnew emailquestionadded folder friendlyname instance organ showduplicates showlabels showotherpeoplesscores showslidenames showtmasampleids showthumbnails stainings
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 (
Checkbox, ...), followed by another semicolon and optionally other configuration for the question (options for a DropDown for example).
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.
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.
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.
First you need to setup the questions so that they correspond to the results.
Then you can use
POST Api/UploadResults with
results as POST parameters. The results should have the same format as when you download them from Slide Score -
ImageID(tab)Name(tab)By(tab)(optionally: TMA Row(tab)TMA Col(tab)TMA Sample(tab))Question(tab)Answer
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.
You can export Slide Score annotations in ASAP format using
GET Api/ExportASAPAnnotationsemail@example.com&question=Mitosis. This will return a single XML file containing annotations for image 1 created by user "firstname.lastname@example.org" for the question (it has to be of type
AnnoPoints) that can be loaded straight to ASAP
Importing ASAP annotations to Slide Score is possible using
Slide Score expects these parameters
asapAnnotation - contents of the ASAP XML file containing annotations.
You can specify two optional parameters:
annotationName - (optional) how this import should be labelled in the database,
questionsMap - (optional) defines mapping between colors used in the annotation file and questions defined in the study in Slide Score. 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 this parameter is not supplied Slide Score generates new question for each color in the annotation file.