Kili Docs

Kili Docs

›Python - GraphQL API

Introduction to Kili Technology

  • Introduction to Kili Technology
  • Kili Technology allows
  • Compatible browser

Getting Started

  • Getting started with Kili - Classification

Hosting

  • SaaS
  • On-Premise Data
  • On-Premise Entreprise

Concepts

  • Definitions
  • Status Lifecycle
  • Architecture

Users and roles

  • Roles by project
  • Users
  • Users and roles management

Projects

  • Audit labelers
  • Customize interface
  • Dataset
  • New project
  • Project overview
  • Projects
  • Projects list
  • Settings
  • Shortcuts

Image interfaces

  • Bounding Box
  • Classification
  • Point
  • Polygon
  • Polyline
  • Segmentation
  • Simple and intuitive interfaces

Text & PDF interfaces

  • Classification
  • Image transcription / OCR
  • Named entities recognition
  • Relations extraction

Video interfaces

  • Classification
  • Multi-frames classification
  • Multi-frames object detection
  • Transcription

Audio interfaces

  • Voice transcription / Speech to text

Data ingestion

  • Data ingestion made easy
  • Load data from a workstation
  • Load data from a public cloud
  • Data on premise or on private cloud
  • How to generate non-expiring signed URLs on AWS

Quality management

  • Consensus
  • Honeypot or Gold Standard
  • Instructions
  • Quality KPIs
  • Quality management
  • Questions and Issues
  • Review Process
  • Workload distribution

Automation

  • Human in the loop
  • Model based preannotation
  • Online learning
  • Queue prioritisation

Data export

  • Data export
  • Data format
  • Example

Python - GraphQL API

  • GraphQL API
  • Python API

Code snippets

  • Authentication
  • Create a Honeypot
  • Create a user
  • Creating Consensus
  • Delete the data
  • Export data
  • Export labels
  • Import data
  • Import labels
  • Prioritize assets
  • See the Consensus of an annotation
  • See the Honeypot of an annotation
  • Throttling

Recipes

  • AutoML for faster labeling with Kili Technology
  • Create a project
  • Exporting a training set
  • Importing medical data into a frame project
  • Importing assets
  • Import rich-text assets
  • Importing predictions
  • Reading and uploading dicom image data
  • How to query using the API
  • Labelled Image Data & Transfer Learning
  • Webhooks

Change log

  • Change log

Python API


Table of contents

  • append_many_to_dataset
  • append_to_labels
  • append_to_roles
  • assets
  • count_assets
  • count_labels
  • count_locks
  • count_notifications
  • count_organizations
  • count_project_users
  • count_projects
  • count_users
  • create_empty_project
  • create_honeypot
  • create_notification
  • create_organization
  • create_predictions
  • create_project
  • create_user
  • delete_from_roles
  • delete_many_from_dataset
  • delete_project
  • export_labels_as_df
  • force_project_kpis
  • label_created_or_updated
  • labels
  • locks
  • make_project_public
  • notifications
  • organizations
  • parse_json_response_for_multi_classification
  • parse_json_response_for_single_classification
  • project_users
  • projects
  • reset_password
  • update_api_key
  • update_password
  • update_properties_in_asset
  • update_properties_in_assets
  • update_properties_in_label
  • update_properties_in_notification
  • update_properties_in_organization
  • update_properties_in_project
  • update_properties_in_project_user
  • update_properties_in_role
  • update_properties_in_user
  • users

append_many_to_dataset

Append assets to a project

For more detailed examples on how to import assets, see the recipe. For more detailed examples on how to import specifically text assets, see the recipe.

Parameters :

  • project_id : str
    Identifier of the project
  • content_array : List[str], optional (default = None)
    List of elements added to the assets of the project
    • For a Text project, the content can be either raw text, or URLs to TEXT assets.
    • For an Image / PDF project, the content can be either URLs or paths to existing images/pdf on your computer.
    • For a Video project, the content must be hosted on a web server,
      and you point Kili to your data by giving the URLs.
      Must not be None except if you provide json_content_array.
  • external_id_array : List[str], optional (default = None)
    List of external ids given to identify the assets. If None, random identifiers are created.
  • is_honeypot_array : List[bool], optional (default = None)
  • status_array : List[str], optional (default = None)
    By default, all imported assets are set to 'TODO'. It can also be set to
    'ONGOING', 'LABELED', 'REVIEWED'
  • json_content_array : List[List[str]], optional (default = None)
    Useful for 'FRAME' or 'TEXT' projects only.
    For FRAME projects, each element is a sequence of frames, i.e. a list of URLs to images or a list of paths to images
    For TEXT projects, each element is a json_content dict, formatted according to documentation on how to import rich-text assets: https://github.com/kili-technology/kili-playground/blob/master/recipes/import_text_assets.ipynb
  • json_metadata_array : List[Dict] , optional (default = None)
    The metadata given to each asset should be stored in a json like dict with keys
    "imageUrl", "text", "url".
    json_metadata_array = [{'imageUrl': '','text': '','url': ''}] to upload one asset.

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

Examples :

>>> playground.append_many_to_dataset(project_id=project_id, content_array=['https://upload.wikimedia.org/wikipedia/en/7/7d/Lenna_%28test_image%29.png'])

append_to_labels

Append a label to an asset

Parameters :

  • json_response : dict
    Label is given here
  • author_id : str, optional (default = auth.user_id)
    ID of the author of the label
  • label_asset_external_id : str, optional (default = None)
    External identifier of the asset
    Either provide label_asset_id or label_asset_external_id and project_id
  • label_asset_id : str, optional (default = None)
    Identifier of the asset
    Either provide label_asset_id or label_asset_external_id and project_id
  • project_id : str, optional (default = None)
    Project ID of the asset
    Either provide label_asset_id or label_asset_external_id and project_id
  • label_type : str, optional (default = 'DEFAULT')
    Can be one of {'AUTOSAVE', 'DEFAULT', 'PREDICTION', 'REVIEW'}
  • seconds_to_label : int, optional (default = 0)
  • skipped : bool, optional (default = False)

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

Examples :

>>> playground.append_to_labels(label_asset_id=asset_id, json_response={...})

append_to_roles

Add a user to a project

If the user does not exist in your organization, he is invited and added both to your organization and project. This function can also be used to change the role of the user in the project.

Parameters :

  • project_id : str
    Id of the project.
  • user_email : str
    The email of the user. This email is used as the unique identifier of the user.
  • role : str, optional (default = 'LABELER')
    One of {"ADMIN", "REVIEWER", "LABELER", "READER"}.

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

Examples :

>>> playground.append_to_roles(project_id=project_id, user_email='john@doe.com')

assets

Get an array of assets respecting a set of constraints

Parameters :

  • project_id : str
    Identifier of the project.
  • skip : int, optional (default = None)
    Number of assets to skip (they are ordered by their date of creation, first to last).
  • fields : list of string, optional (default = ['id', 'content', 'externalId', 'isHoneypot', 'isUsedForConsensus', 'jsonMetadata', 'labels.author.id', 'labels.author.email','labels.jsonResponse', 'labels.skipped', 'priority', 'projects.id', 'projects.title', 'project.jsonInterface'])
    All the fields to request among the possible fields for the assets.
    See the documentation for all possible fields.
  • first : int, optional (default = None)
    Maximum number of assets to return. Can only be between 0 and 100.
  • consensus_mark_gt : float, optional (default = None)
    Minimum amout of consensus for the asset.
  • consensus_mark_lt : float, optional (default = None)
    Maximum amout of consensus for the asset.
  • external_id_contains : list of str, optional (default = None)
    Returned assets should have an external id that belongs to that list, if given.
  • honeypot_mark_gt : float, optional (default = None)
    Minimum amout of honeypot for the asset.
  • honeypot_mark_lt : float, optional (default = None)
    Maximum amout of honeypot for the asset.
  • status_in : list of str, optional (default = None)
    Returned assets should have a status that belongs to that list, if given.
    Possible choices : {'TODO', 'ONGOING', 'LABELED', 'REVIEWED'}
  • label_type_in : list of str, optional (default = None)
    Returned assets should have a label whose type belongs to that list, if given.
  • label_author_in : list of str, optional (default = None)
    Returned assets should have a label whose status belongs to that list, if given.
  • label_consensus_mark_gt, optional (default = None)
    Returned assets should have a label whose consensus is greater than this number.
  • label_consensus_mark_lt : float, optional (default = None)
    Returned assets should have a label whose consensus is lower than this number.
  • label_created_at : string, optional (default = None)
    Returned assets should have a label whose creation date is equal to this date.
    Formatted string should have format : "YYYY-MM-DD"
  • label_created_at_gt : string, optional (default = None)
    Returned assets should have a label whose creation date is greater than this date.
    Formatted string should have format : "YYYY-MM-DD"
  • label_created_at_lt : string, optional (default = None)
    Returned assets should have a label whose creation date is lower than this date.
    Formatted string should have format : "YYYY-MM-DD"
  • label_json_response_contains : list of str, optional (default = None)
    Returned assets should have a substring of the label's jsonResponse that belongs to that list, if given.
  • label_honeypot_mark_gt : float, optional (default = None)
    Returned assets should have a label whose honeypot is greater than this number.
  • label_honeypot_mark_lt : float, optional (default = None)
    Returned assets should have a label whose honeypot is lower than this number.
  • label_skipped : bool, optional (default = None)
    Returned assets should have a label which is skipped
  • updated_at_gte : string, optional (default = None)
    Returned assets should have a label whose update date is greated or equal to this date.
    Formatted string should have format : "YYYY-MM-DD"
  • updated_at_lte : string, optional (default = None)
    Returned assets should have a label whose update date is lower or equal to this date.
    Formatted string should have format : "YYYY-MM-DD"
  • format : str, optional (default = None)
    If equal to 'pandas', returns a pandas DataFrame
  • disable_tqdm : bool, optional (default = False)

Returns :

  • a result object which contains the query if it was successful, or an error message else.

Examples :

>>> playground.assets(project_id=project_id)
>>> playground.assets(asset_id=asset_id)

count_assets

Count and return the number of assets with the given constraints

Parameters beginning with 'label_' apply to labels, others apply to assets.

Parameters :

  • asset_id : str
    Identifier of the asset
  • project_id : str, optional (default = None)
    Identifier of the project
  • external_id_contains : list of str, optional (default = None)
    Returned assets should have an external id that belongs to that list, if given.
  • status_in : list of str, optional (default = None)
    Returned assets should have a status that belongs to that list, if given.
    Possible choices : {'TODO', 'ONGOING', 'LABELED', 'REVIEWED'}
  • consensus_mark_gt : float, optional (default = None)
    Minimum amout of consensus for the asset.
  • consensus_mark_lt : float, optional (default = None)
    Maximum amout of consensus for the asset.
  • honeypot_mark_gt : float, optional (default = None)
    Minimum amout of honeypot for the asset.
  • honeypot_mark_lt : float, optional (default = None)
    Maximum amout of consensus for the asset.
  • label_type_in : list of str, optional (default = None)
    Returned assets should have a label whose type belongs to that list, if given.
  • label_author_in : list of str, optional (default = None)
    Returned assets should have a label whose status belongs to that list, if given.
  • label_consensus_mark_gt : float, optional (default = None)
    Returned assets should have a label whose consensus is greater than this number.
  • label_consensus_mark_lt : float, optional (default = None)
    Returned assets should have a label whose consensus is lower than this number.
  • label_created_at : string, optional (default = None)
    Returned assets should have a label whose creation date is equal to this date.
    Formatted string should have format : "YYYY-MM-DD"
  • label_created_at_gt : string, optional (default = None)
    Returned assets should have a label whose creation date is greater than this date.
    Formatted string should have format : "YYYY-MM-DD"
  • label_created_at_lt : string, optional (default = None)
    Returned assets should have a label whose creation date is lower than this date.
    Formatted string should have format : "YYYY-MM-DD"
  • label_honeypot_mark_gt : float, optional (default = None)
    Returned assets should have a label whose honeypot is greater than this number.
  • label_honeypot_mark_lt : float, optional (default = None)
    Returned assets should have a label whose honeypot is lower than this number.
  • label_json_response_contains : list of str, optional (default = None)
    Returned assets should have a substring of the label's jsonResponse that belongs to that list, if given.
  • label_skipped : bool, optional (default = None)
    Returned assets should have a label which is skipped
  • updated_at_gte : string, optional (default = None)
    Returned assets should have a label whose update date is greated or equal to this date.
    Formatted string should have format : "YYYY-MM-DD"
  • updated_at_lte : string, optional (default = None)
    Returned assets should have a label whose update date is lower or equal to this date.
    Formatted string should have format : "YYYY-MM-DD"

Returns :

  • a result object which contains the query if it was successful, or an error message else.

Examples :

>>> playground.count_assets(project_id=project_id)
250
>>> playground.count_assets(asset_id=asset_id)
1

count_labels

Get the number of labels for the given parameters

Parameters :

  • asset_id : str
    Identifier of the asset.
  • asset_status_in : list of str, optional (default = None)
    Returned labels should have a status that belongs to that list, if given.
    Possible choices : {'TODO', 'ONGOING', 'LABELED', 'REVIEWED'}
  • asset_external_id_in : list of str, optional (default = None)
    Returned labels should have an external id that belongs to that list, if given.
  • author_in : list of str, optional (default = None)
    Returned labels should have a label whose status belongs to that list, if given.
  • created_at : string, optional (default = None)
    Returned labels should have a label whose creation date is equal to this date.
    Formatted string should have format : "YYYY-MM-DD"
  • created_at_gt : string, optional (default = None)
    Returned labels should have a label whose creation date is greater than this date.
    Formatted string should have format : "YYYY-MM-DD"
  • created_at_lt : string, optional (default = None)
    Returned labels should have a label whose creation date is lower than this date.
    Formatted string should have format : "YYYY-MM-DD"
  • fields : list of string, optional (default = ['author.email', 'author.id','author.name', 'id', 'jsonResponse', 'labelType', 'secondsToLabel', 'skipped'])
    All the fields to request among the possible fields for the labels.
    See the documentation for all possible fields.
  • honeypot_mark_gt : float, optional (default = None)
    Returned labels should have a label whose honeypot is greater than this number.
  • honeypot_mark_lt : float, optional (default = None)
    Returned labels should have a label whose honeypot is lower than this number.
  • json_response_contains : list of str, optional (default = None)
    Returned labels should have a substring of the jsonResponse that belongs to that list, if given.
  • label_id : str
    Identifier of the label.
  • project_id : str
    Identifier of the project.
  • skipped : bool, optional (default = None)
    Returned labels should have a label which is skipped
  • type_in : list of str, optional (default = None)
    Returned labels should have a label whose type belongs to that list, if given.
  • user_id : str
    Identifier of the user.

Returns :

  • the number of labels with the parameters provided

count_locks

Get the number of locks

Parameters :

Returns :

  • the number of locks

count_notifications

Count the number of notifications

Parameters :

  • has_been_seen : bool, optional (default = None)
    Filter on notifications that have been seen.
  • user_id : string, optional (default = None)
    Filter on the notifications of a specific user

Returns :

  • the number of notifications with the parameters provided

count_organizations

Count organizations respecting a set of criteria

Parameters :

  • email : str, optional (default = None)
  • organization_id : str, optional (default = None)

Returns :

  • a result object which contains the query if it was successful, or an error message else.

count_project_users

Counts the number of projects and their users respecting a set of criteria

Parameters :

  • email : str, optional (default = None)
  • organization_id : str, optional (default = None)
  • project_id : str, optional (default = None)

Returns :

  • a positive integer corresponding to the number of results of the query if it was successful, or an error message else.

count_projects

Counts the number of projects with a search_query

Parameters :

  • project_id : str, optional (default = None)
    Select a specific project through its project_id
  • search_query : str, optional (default = None)
    Returned projects have a title or a description that matches this string.
  • should_relaunch_kpi_computation : bool, optional (default = None)
    Technical field, added to indicate changes in honeypot or consensus settings
  • updated_at_gte : string, optional (default = None)
    Returned projects should have a label whose update date is greated or equal to this date.
    Formatted string should have format : "YYYY-MM-DD"
  • updated_at_lte : string, optional (default = None)
    Returned projects should have a label whose update date is lower or equal to this date.
    Formatted string should have format : "YYYY-MM-DD"

Returns :

  • a positive integer corresponding to the number of results of the query if it was successful, or an error message else.

count_users

Get users count given a set of constraints

Parameters :

  • organization_id : str, optional (default = None)

Returns :

  • the count of users whose organization id correspond to the given one

create_empty_project

Create an empty project

For more detailed examples on how to create projects, see the recipe.

Parameters :

  • user_id : str, optional (default = auth.user_id)

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

Examples :

>>> project = playground.create_empty_project()
>>> project_id = project['id']

create_honeypot

Create honeypot for an asset.

Uses the json_response given to create a "REVIEW" label. This allows to compute a honeypotMark, which measures how similar are other labels compared to this one.

Parameters :

  • json_response : dict
    The JSON response of the honeypot label of the asset
  • asset_id : str, optional (default = None)
    Identifier of the asset
    Either provide asset_id or asset_external_id and project_id
  • asset_external_id : str, optional (default = None)
    External identifier of the asset
    Either provide asset_id or asset_external_id and project_id
  • project_id : str, optional (default = None)
    External identifier of the asset
    Either provide asset_id or asset_external_id and project_id

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

create_notification

Create a notification

This method is currently only active for Kili administrators.

Parameters :

  • message : str
  • status : str
  • url : str
  • user_id : str

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

create_organization

Create an organization

Each user must be linked to an organization

Parameters :

  • name : str
  • address : str
  • zip_code : str
  • city : str
  • country : str

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

create_predictions

Create predictions for some assets

For more detailed examples on how to create predictions, see the recipe.

Parameters :

  • project_id : str
  • external_id_array : list of str
    The external identifiers of the assets for which we want to add predictions
  • model_name_array : list of str
    In case you want to precise from which model the label originated
  • json_response_array : list of dict
    The predictions are given here. An example can be found here, for a polygon.
    For other examples, see the recipe.
{    
    "JOB_0": {    
        "annotations": [    
            {    
                "categories": [{ "name": "OBJECT_B", "confidence": 100 }],    
                "boundingPoly": [    
                    {    
                        "normalizedVertices": [    
                            { "x": 0.07, "y": 0.88 },    
                            { "x": 0.07, "y": 0.32 },    
                            { "x": 0.94, "y": 0.32 },    
                            { "x": 0.94, "y": 0.88 }    
                        ]    
                    }    
                ]    
            }    
        ]    
    }    
}    

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

create_project

Create a project

For more detailed examples on how to create projects, see the recipe.

Parameters :

  • input_type : str
    Currently, one of {AUDIO, IMAGE, PDF, TEXT, URL, VIDEO, NA}
  • json_interface: dict
    The json parameters of the project, see Edit your interface.
  • title : str
  • description : str, optional (default = '')
  • project_type: str, optional (default = None)
    Currently, one of {IMAGE_CLASSIFICATION_SINGLE, IMAGE_CLASSIFICATION_MULTI, IMAGE_OBJECT_DETECTION_RECTANGLE, IMAGE_OBJECT_DETECTION_POLYGON, IMAGE_OBJECT_DETECTION_SEMANTIC, OCR, PDF_CLASSIFICATION_SINGLE, PDF_CLASSIFICATION_MULTI, TEXT_CLASSIFICATION_SINGLE, TEXT_CLASSIFICATION_MULTI, TEXT_TRANSCRIPTION, TEXT_NER, VIDEO_CLASSIFICATION_SINGLE, VIDEO_FRAME_CLASSIFICATION, VIDEO_FRAME_OBJECT_TRACKING, SPEECH_TO_TEXT}
  • user_id : str, optional (default = None)

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

Examples :

>>> playground.create_project(input_type='IMAGE', json_interface=json_interface, title='Example')

create_user

Add a user to your organization.

Parameters :

  • name : str
    Name of the new user.
  • email : str
    Email of the new user, used as his unique identifier.
  • password : str
    On the first sign in, he will use this password and be able to change it.
  • organization_role : str
    One of "ADMIN", "USER".

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

delete_from_roles

Delete users by their role_id

Parameters :

  • role_id : str

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

delete_many_from_dataset

Delete assets from a project

Parameters :

  • asset_ids : list of str
    The list of identifiers of the assets to delete.

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

delete_project

Delete project permanently

Parameters :

  • project_id : str

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

export_labels_as_df

Get the labels of a project as a pandas DataFrame

Parameters :

  • project_id : str
  • fields : list of string, optional (default = [ 'author.email', 'author.id','author.name', 'id', 'jsonResponse', 'labelType', 'secondsToLabel', 'skipped'])
    All the fields to request among the possible fields for the labels.
    See the documentation for all possible fields.

Returns :

  • labels_df : pandas DataFrame containing the labels.

force_project_kpis

Compute KPIs for a project

Parameters :

  • project_id : str

Returns :

  • None

label_created_or_updated

Subscribe a callback to a project, which is executed when a label is created or updated. See the related recipe for more explanation on how to use it.

Parameters :

  • project_id : str
  • callback : function of (str, str) -> None
    This function takes as input the id of the asset and its content.

Returns :

  • subscription client

labels

Get an array of labels from a project given a set of criteria

Parameters :

  • asset_id : str, optional (default = None)
    Identifier of the asset.
  • asset_status_in : list of str, optional (default = None)
    Returned labels should have a status that belongs to that list, if given.
    Possible choices : {'TODO', 'ONGOING', 'LABELED', 'REVIEWED'}
  • asset_external_id_in : list of str, optional (default = None)
    Returned labels should have an external id that belongs to that list, if given.
  • author_in : list of str, optional (default = None)
    Returned labels should have a label whose status belongs to that list, if given.
  • created_at : string, optional (default = None)
    Returned labels should have a label whose creation date is equal to this date.
    Formatted string should have format : "YYYY-MM-DD"
  • created_at_gt : string, optional (default = None)
    Returned labels should have a label whose creation date is greater than this date.
    Formatted string should have format : "YYYY-MM-DD"
  • created_at_lt : string, optional (default = None)
    Returned labels should have a label whose creation date is lower than this date.
    Formatted string should have format : "YYYY-MM-DD"
  • fields : list of string, optional (default = ['author.email', 'author.id','author.name', 'id', 'jsonResponse', 'labelType', 'secondsToLabel', 'skipped'])
    All the fields to request among the possible fields for the labels.
    See the documentation for all possible fields.
  • first : int, optional (default = None)
    Maximum number of labels to return. Can only be between 0 and 100.
  • honeypot_mark_gt : float, optional (default = None)
    Returned labels should have a label whose honeypot is greater than this number.
  • honeypot_mark_lt : float, optional (default = None)
    Returned labels should have a label whose honeypot is lower than this number.
  • id_contains : list of str, optional (default = None)
    Filters out labels not belonging to that list. If empty, no filtering is applied.
  • json_response_contains : list of str, optional (default = None)
    Returned labels should have a substring of the jsonResponse that belongs to that list, if given.
  • label_id : str
    Identifier of the label.
  • project_id : str
    Identifier of the project.
  • skip : int, optional (default = None)
    Number of labels to skip (they are ordered by their date of creation, first to last).
  • skipped : bool, optional (default = None)
    Returned labels should have a label which is skipped
  • type_in : list of str, optional (default = None)
    Returned labels should have a label whose type belongs to that list, if given.
  • user_id : str
    Identifier of the user.

Returns :

  • a result object which contains the query if it was successful, or an error message else.

Examples :

>>> # List all labels of a project and their assets external ID
>>> playground.labels(project_id=project_id, fields=['jsonResponse', 'labelOf.externalId'])

locks

Get locks

Returns locks

Parameters :

  • lock_id : str, optional (default = None)
    The id of the lock to request. If None, all locks are returned
  • fields : list of string, optional (default = ['id', 'lock_type'])
    All the fields to request among the possible fields for the locks.
    See the documentation for all possible fields.
  • first : int, optional (default = 100)
    Maximum number of locks to return. Can only be between 0 and 100.
  • skip : int, optional (default = 0)
    Number of skipped locks (they are ordered by creation date)

Returns :

  • a result object which contains the query if it was successful, or an error message else.

make_project_public

Make a project public. Warning: This action is permanent and irreversible.

Parameters :

  • project_id : str

Returns :

  • the public token to provide in the public URL

notifications

Get an array of notifications given a set of constraints

Parameters :

  • fields : list of string, optional (default = ['createdAt', 'hasBeenSeen', 'id', 'message', 'status', 'userID'])
    All the fields to request among the possible fields for the notifications
    See the documentation for all possible fields.
  • first : int (default = 100)
    Number of notifications to query
  • has_been_seen : bool, optional (default = None)
    If the notifications returned should have been seen.
  • notification_id : str, optional (default = None)
    If given, will return the notification which has this id
  • skip : int (default = 0)
    Number of notifications to skip (they are ordered by their date of creation, first to last).
  • user_id : string, optional (default = None)
    If given, returns the notifications of a specific user

Returns :

  • a result object which contains the query if it was successful, or an error message else.

organizations

Get organizations respecting a set of criteria

Returns all organizations:

  • with a given organization id
  • containing a user with a given email

Parameters :

  • email : str, optional (default = None)
  • organization_id : str, optional (default = None)
  • fields : list of string, optional (default = ['id', 'name'])
    All the fields to request among the possible fields for the organizations.
    See the documentation for all possible fields.
  • first : int, optional (default = 100)
    Maximum number of organizations to return
  • skip : int, optional (default = 0)
    Number of skipped organizations (they are ordered by creation date)

Returns :

  • a result object which contains the query if it was successful, or an error message else.

Examples :

>>> playground.organizations(organization_id=organization_id, fields=['users.email'])
[{'users': [{'email': 'john@doe.com'}]}]

parse_json_response_for_multi_classification

Parameters :

json_response : dict
A valid JSON response

Returns :

The names of categories from a json_response, for a multi-class classification task

parse_json_response_for_single_classification

Parameters :

json_response : dict
A valid JSON response

Returns :

The names of categories from a json_response, for a single-class classification task

project_users

Return projects and their users (possibly with their KPIs) respecting a set of criteria

Parameters :

  • email : str, optional (default = None)
  • organization_id : str, optional (default = None)
  • project_id : str, optional (default = None)
  • fields : list, optional (default = ['activated', 'id', 'role', 'starred', 'user.email', 'user.id', 'user.name'])
    All the fields to request among the possible fields for the projectUsers.
    See the documentation for all possible fields.
  • first : int, optional (default = 100)
    Maximum number of users to return. Can only be between 0 and 100.
  • skip : int, optional (default = 0)
    Number of project users to skip

Returns :

  • a result object which contains the query if it was successful, or an error message else.

Examples :

>>> # Retrieve consensus marks of all users in project
>>> playground.project_users(project_id=project_id, fields=['consensusMark', 'user.email'])

projects

Get projects given a set of criteria

Parameters :

  • project_id : str, optional (default = None)
    Select a specific project through its project_id.
  • search_query : str, optional (default = None)
    Returned projects with a title or a description matching this string.
  • should_relaunch_kpi_computation : bool, optional (default = None)
    Technical field, added to indicate changes in honeypot or consensus settings.
  • updated_at_gte : string, optional (default = None)
    Returned projects should have a label whose update date is greated or equal to this date.
    Formatted string should have format : "YYYY-MM-DD"
  • updated_at_lte : string, optional (default = None)
    Returned projects should have a label whose update date is lower or equal to this date.
    Formatted string should have format : "YYYY-MM-DD"
  • skip : int, optional (default = 0)
    Number of projects to skip (they are ordered by their creation).
  • fields : list of string, optional (default = ['consensusTotCoverage', 'id', 'inputType', 'interfaceCategory', 'jsonInterface', 'maxWorkerCount', 'minAgreement', 'minConsensusSize', 'roles.id', 'roles.role', 'roles.user.email', 'roles.user.id', 'roles.user.name', 'title'])
    All the fields to request among the possible fields for the projects.
    See the documentation for all possible fields.
  • first : int , optional (default = 100)
    Maximum number of projects to return. Can only be between 0 and 100.

Returns :

  • a result object which contains the query if it was successful, or an error message else.

Examples :

>>> # List all my projects
>>> playground.projects()

reset_password

Reset password

This resolver only works for on-premise installations without Auth0, if your organization allows Kili to send emails.

Parameters :

  • email : str
    Email of the person whose password has to be reset.

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

update_api_key

Update API key

Allows you to modify the API key you use to connect to Kili. This method is currently only active for Kili administrators.

Parameters :

  • email : str
  • new_api_key : str

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

update_password

Allows you to modify the password you use to connect to Kili. This resolver only works for on-premise installations without Auth0.

Parameters :

  • email : str
  • old_password : str
  • new_password_1 : str
    The new password.
  • new_password_2 : str
    A confirmation field for the new password.

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

update_properties_in_asset

Update the properties of one asset

Parameters :

  • asset_id : str
    The id of the asset to modify
  • external_id : str, optional (default = None)
    Change the external id of the asset
  • priority : int, optional (default = None)
    By default, all assets have a priority of 0
  • json_metadata : dict , optional (default = None)
    The metadata given to an asset should be stored in a json like dict with keys
    "imageUrl", "text", "url".
    json_metadata = {'imageUrl': '','text': '','url': ''}
  • consensus_mark : float (default = None)
    Should be between 0 and 1
  • honeypot_mark : float (default = None)
    Should be between 0 and 1
  • to_be_labeled_by : list of str (default = None)
    If given, should contain the emails of the labelers authorized to label the asset
  • content : str (default = None)
    • For a NLP project, the content is directly in text format
    • For an Image / Video / Pdf project, the content must be hosted on a web server,
      and you point Kili to your data by giving the URLs
  • status : str (default = None)
    Should be in {'TODO', 'ONGOING', 'LABELED', 'REVIEWED'}
  • is_used_for_consensus : bool (default = None)
    Whether to use the asset to compute consensus kpis or not
  • is_honeypot : bool (default = None)
    Whether to use the asset for honeypot

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

update_properties_in_assets

Update the properties of one or more assets.

Parameters :

  • asset_ids : List[str]
    The asset IDs to modify
  • external_ids : List[str], optional (default = None)
    Change the external id of the assets
  • priorities : List[int], optional (default = None)
    You can change the priority of the assets
    By default, all assets have a priority of 0.
  • json_metadatas : List[dict] , optional (default = None)
    The metadata given to an asset should be stored in a json like dict with keys
    "imageUrl", "text", "url".
    json_metadata = {'imageUrl': '','text': '','url': ''}
  • consensus_marks : List[float] (default = None)
    Should be between 0 and 1
  • honeypot_marks : List[float] (default = None)
    Should be between 0 and 1
  • to_be_labeled_by_array : List[List[str]] (default = None)
    If given, each element of the list should contain the emails of the labelers authorized to label the asset.
  • contents : List[str] (default = None)
    • For a NLP project, the content can be directly in text format
    • For an Image / Video / Pdf project, the content must be hosted on a web server,
      and you point Kili to your data by giving the URLs
  • status_array : List[str] (default = None)
    Each element should be in {'TODO', 'ONGOING', 'LABELED', 'REVIEWED'}
  • is_used_for_consensus_array : List[bool] (default = None)
    Whether to use the asset to compute consensus kpis or not
  • is_honeypot_array : List[bool] (default = None)
    Whether to use the asset for honeypot

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

Examples :

playground.update_properties_in_assets(    
    asset_ids=["ckg22d81r0jrg0885unmuswj8", "ckg22d81s0jrh0885pdxfd03n"],    
    consensus_marks=[1, 0.7],    
    contents=[None, 'https://to/second/asset.png'],    
    external_ids=['external-id-of-your-choice-1', 'external-id-of-your-choice-2'],    
    honeypot_marks=[0.8, 0.5],    
    is_honeypot_array=[True, True],    
    is_used_for_consensus_array=[True, False],    
    priorities=[None, 2],    
    status_array=['LABELED', 'REVIEWED'],    
    to_be_labeled_by_array=[['test+pierre@kili-technology.com'], None],
)

update_properties_in_label

Update properties of a label

Parameters :

  • label_id : str
    Identifier of the label
  • seconds_to_label : int, optional (default = None)
  • model_name : str, optional (default = None)
  • json_response : dict, optional (default = None)
    The label is given here

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

Examples :

>>> playground.update_properties_in_label(label_id=label_id, json_response={...})

update_properties_in_notification

Modify a notification

This method is currently only active for Kili administrators.

Parameters :

  • notification_id : str
  • hasBeenSeen: bool
  • status : str
  • url : str

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

update_properties_in_organization

Modify an organization

Parameters :

  • organization_id : str
  • name : str
  • address : str
  • license : dict
  • zip_code : str
  • city : str
  • country : str

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

update_properties_in_project

Update properties of a project

Parameters :

  • project_id : str
    Identifier of the project
  • consensus_mark : float, optional (default = None)
    Should be between 0 and 1
  • consensus_tot_coverage : int, optional (default = None)
    Should be between 0 and 100. It is the percentage of the dataset
    that will be annotated several times.
  • description : str, optional (default = None)
  • honeypot_mark : float, optional (default = None)
    Should be between 0 and 1
  • instructions : str, optional (default = None)
  • interface_category : str, optional (default = 'IV2')
    Always use 'IV2'
  • input_type : str, optional (default = None)
    Currently, one of {AUDIO, IMAGE, PDF, TEXT, URL, VIDEO, NA}
  • json_interface : dict, optional (default = None)
    The json parameters of the project, see Edit your interface.
  • min_consensus_size : int, optional (default = None)
    Number of people that will annotate the same asset, for consensus computation.
  • number_of_assets : int, optional (default = None)
    Defaults to 0
  • number_of_assets_with_empty_labels : int, optional (default = None)
    Defaults to 0
  • number_of_remaining_assets : int, optional (default = None)
    Defaults to 0
  • number_of_reviewed_assets : int, optional (default = None)
    Defaults to 0
  • should_relaunch_kpi_computation : bool, optional (default = None)
    Technical field, added to indicate changes in honeypot or consensus settings
  • title : str, optional (default = None)

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

Examples :

>>> playground.update_properties_in_project(project_id=project_id, title='New title')

update_properties_in_project_user

Update properties of a project-user tuple

Parameters :

  • project_user_id : str
  • consensus_mark : float, optional (default = None)
    Should be between 0 and 1.
  • honeypot_mark : float, optional (default = None)
    Should be between 0 and 1.
  • number_of_labeled_assets : int, optional (default = None)
    Number of assets the user labeled in the project.
  • starred : bool, optional (default = None)
    Whether to star the project in the project list.
  • total_duration : int, optional (default = None)
    Total time the user spent in the project.

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

Examples :

>>> for project_user in project_users:
...     playground.update_properties_in_project_user(project_user_id=project_user['id'], honeypot_mark=0)

update_properties_in_role

Update properties of a role

You should be either an admin or a reviewer of the project, or an admin of the organization to be able to change the role of somebody.

Parameters :

  • role_id : str
    Role identifier of the user. E.g. : 'to-be-deactivated'
  • project_id : str
    Identifier of the project
  • user_id : str
    The email or identifier of the user with updated role
  • role : str
    The new role. One of "ADMIN", "REVIEWER", "LABELER", "READER"

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

update_properties_in_user

Update the properties of a user

Parameters :

  • email : str
    The email is the identifier of the user
  • name : str, optional (default = None)
  • organization_id : str, optional (default = None)
    Change the organization the user is related to.
  • organization_role : str, optional (default = None)
    Change the role of the user. One of "ADMIN", "REVIEWER", "LABELER", "READER".
  • activated : bool, optional (default = None)
    In case we want to deactivate a user, but keep it.

Returns :

  • a result object which indicates if the mutation was successful, or an error message else.

users

Get users given a set of constraints

Parameters :

  • api_key : str, optional (default = None) Query an user by its API KEY
  • email : str, optional (default = None)
  • organization_id : str, optional (default = None)
  • fields : list of string, optional (default = ['email', 'id', 'name'])
    All the fields to request among the possible fields for the users.
    See the documentation for all possible fields.
  • first : int, optional (default = 100)
    Maximum number of users to return. Can only be between 0 and 100.
  • skip : int, optional (default = 0)
    Number of skipped users (they are ordered by creation date)

Returns :

  • a result object which contains the query if it was successful, or an error message else.

Examples :

>>> # List all users in my organization
>>> organization = playground.organizations()
>>> organization_id = organizations[0]['id]
>>> playground.users(organization_id=organization_id)
← GraphQL APIAuthentication →