Getting started with GC-API

Install gcapi¶

First, lets install the newest version of gcapi with pip.

$ pip install gcapi

Your personal API token¶

In order to start using gcapi you need to get a personal API token. An API token is a unique identifier that is used to authenticate you on the API.
You can generate the token yourself by logging in on Grand Challenge. Once logged in, navigate to Your Profile --> Manage API Tokens and click on Create a Token . Once you click Save, the token will be generated for you and displayed in a blue ribbon at the top of the page. You will only be able to see this token once, so store it safely in a password manager for later use. Please treat your API Token like a password and remove the key if necessary.

Slugs¶

You will also need to find the slug of the object you want to download from or upload to. It is typically the name of your archive, algorithm, or reader study on Grand Challenge and can be found in the URL of the respective page. For instance, if you would like to upload to the algorithm at https://grand-challenge.org/algorithms/corads-ai/, the slug of the algorithm would be corads-ai. Note that the slug is case-sensitive.

Access rights¶

To interact with an algorithm, reader study, or archive on Grand Challenge, you must have the proper access rights. Unless you are the editor of the object, you will first need to request access to the desired algorithm/reader study/archive. This can be done by navigating to the respective algorithm/reader study/archive page on Grand Challenge and pressing the "Request access" button. It might take a couple of hours before the owner of an algorithm/reader study/archive approves your request, please be patient.

Retries¶

GC-API Requests that fail with a server-side error (i.e. 5XX) are retried with an exponential-backoff strategy. To customize the retry strategy provide a callable when initializing the client as follows:

import gcapi
import httpx

class NoRetries(gcapi.retries.BaseRetryStrategy):
   def get_delay(self, latest_response: httpx.Response):  # Return optional delay in seconds
      return None

token = 'my-personal-api-token'
client = gcapi.Client(token=token, retry_strategy=NoRetries)