External clients

What is a Cytomine external client ?

As Cytomine is a Restful application, the data stored and managed by Cytomine can be obtained via specific URLs to get only the relevant information (without the visual interface).

These access points allow users and external softwares to interact with Cytomine for various purposes : datamining, scripting, create a new visual interface for particular usages, etc. However, it is not convenient to set an HTTP request, its authentication, call it, then analyse and parse the response. To ease the interaction of Cytomine with System Administrators, external softwares and so on, we developed multiple clients that encapsulate the HTTP operations to allow developers to focus on their tasks.

Note that a client will have the same permission than a human user. So a client will not be able to :
- See an annotation of another contributor of a Read-only project that he doesn't manage;
- Add or remove contributors of a project he doesn't manage;
- Fetch data without authentication;
- etc.

How to use a Cytomine external client

We have currently clients in Java, Javascript and Python, you can freely choose to program in one of these 3 language.
The Cytomine clients are used as library into some scripts or programming projects. Look at their dedicated pages to know how to install them.


The first step with the use of a Cytomine client is to authenticate you to the Cytomine instance that you want to interact with.
This authentication is made with 3 arguments :
- The URL of the Cytomine instance;
- The public key of a user;
- The private key of a user.

These keys can be found in your https://doc.cytomine.org/Get Started V2?structure=UsersV2" class="wiki wikinew text-danger tips">account settings.

In the Python client, it's done with the with statement:

with Cytomine(host=params.host, public_key=params.public_key, private_key=params.private_key) as cytomine:

In the Java client, it's done with connection static method of the Cytomine class:

Cytomine.connection(cytomineCoreUrl, publickey, privatekey);

In the Javascript client, however, we connect through the username and password:

new Cytomine(CYTOMINE_CORE_URL);
await Cytomine.instance.login(username, password, rememberMe);
await Cytomine.instance.loginWithToken(username, token);


As Cytomine is a project following the Object Oriented Paradigm, it is built on basic element called objects, domains or models. In Cytomine, users, projects, annotations or images are objects.
In our external clients, these objects are called models and each object in Cytomine have its model representation (a class) in the external clients. Each object (an instance of model):

  • has a set of attributes corresponding to resource attributes
  • is managed itself through fetch(), save(), update() and delete() methods that communicate with the Cytomine-core server
  • has some utilities to be serialized to JSON

Technically, all models inherits from a parent class Model that encapsulate functions as save(), update(), delete(), get_url(), etc.

//in Java
//creation of a project
Long ontID = 0L;
Ontology ontology = new Ontology().fetch(ontID);
String name = "test";

Project p = new Project(name,ontology).save();

//fetch a project
Long projectID = 0L;
Project p = new Project().fetch(projectID);

//update a project
p.set("name", name+"bis");

//delete a project

Supplementary actions

In some cases, the server provides supplementary actions for some resources. These actions are encapsulated in additional methods for the model (downloading an ImageInstance, uploading an attached file, ...).


A Collection is a representation of a collection of models.
This class contains methods that allow you to fetch multiples models with filters and/or pagination (with max and offset parameters).
You can use the Collection class directly with a Model:

Collection c = new Collection<>(ImageInstance.class); 
c.addFilter("project", project.getId().toString());
c.fetch(); // will return all the image instance into the projectCollection 
c = new Collection<>(ImageInstance.class, 0,2);
c.addFilter("project", project.getId().toString());
c.fetch(); // will return the two first image instances into the project

However, there is specific class in some case:

ImageInstanceCollection.fetchByProject(project); // will return all the image instance into the project
ImageInstanceCollection.fetchByProject(project,0,2); // will return the two first image instances into the project

Usually, a specific class is created for :
- specific methods related to these models collection;
- syntaxic sugar;