API

How to use the Token-API of DataGym

Overview

With our REST-API you can easily manage your data within the DataGym application. This documentation will guide you through installation, setup and descriptions of each available endpoint.

Usage

To use the API you need a valid API token for your organisation.

You have two options to authenticate your application/call against our API.

• Authorization header

"Authorization": "Token <your_DataGym_API_token>"

• Request parameter

https://app.datagym.ai/api/v1/project?token=<your_DataGym_API_token>

Get All Projects

GET https://app.datagym.ai/api/v1/project

This endpoint allows you to get all Projects for the organisation of your API token.

Query Parameters

Name	Type	Description
token	string	Request parameter to verify your request.

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request.

200 Projects successfully retrieved.

[
  {
    "id": "17b0bda7-fc2a-4423-9269-ac28914bb7c8",
    "name": "Project1",
    "shortDescription": "Project1 Description",
    "description": null,
    "timestamp": 1582719639296,
    "labelConfigurationId": "8ffd901f-7b33-42f9-bf6e-86dd68e16cbd",
    "labelIterationId": "42527661-f9d5-4362-901b-d346d936daa5",
    "owner": "1801d7a4-cdb8-4667-bbda-f2b614626586",
    "mediaType": "IMAGE",
    "datasets": [
      {
        "id": "6e7ebeef-9c84-41c5-84fd-7696ce92c484",
        "name": "Dataset1",
        "shortDescription": null,
        "timestamp": 1583144402428,
        "owner": "1801d7a4-cdb8-4667-bbda-f2b614626586",
        "imagesCount": 0,
        "projectCount": 1,
        "mediaType": "IMAGE"
      },
      {
        "id": "85e159fa-0096-4d58-95aa-5503dc3ef33a",
        "name": "Dataset2",
        "shortDescription": "Dataset2 short description",
        "timestamp": 1583140144066,
        "owner": "1801d7a4-cdb8-4667-bbda-f2b614626586",
        "imagesCount": 3,
        "projectCount": 1,
        "mediaType": "IMAGE"
      }
    ]
  },
  {
    "id": "9eee46d9-53ab-4c0c-8cea-075ec4ce08f5",
    "name": "Project2",
    "shortDescription": "Project2 Description",
    "description": null,
    "timestamp": 1582710802922,
    "datasets": [],
    "labelConfigurationId": "818d3b3b-9445-4afb-bbad-781a23858486",
    "labelIterationId": "0e3bc344-5c2d-4587-aff9-a1a672ca0c75",
    "owner": "de82f6de-4196-47d8-afe8-f2b614626586",
    "mediaType": "IMAGE"
  }
]

401 Could not find an organisation matching this token.

{"msg": "Unauthorized. None or invalid credentials."}

Get Dataset by Id

GET https://app.datagym.ai/api/v1/dataset/{datasetId}

This endpoint allows you to get a Dataset by its Id.

Path Parameters

Name	Type	Description
datasetId	string	The Id of the Dataset.

Query Parameters

Name	Type	Description
token	string	Request param to verify your request.

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request.

200 Dataset successfully retrieved.

{
    "id": "7e3cfb2d-4ffc-4d85-bdec-be54775ae6b9",
    "name": "Dataset1",
    "shortDescription": null,
    "timestamp": 1584715253826,
    "owner": "2b02b66a-c370-4388-99b4-97fac18092258",
    "projectCount": 1,
    "mediaType": "IMAGE",
    "images": [
        {
            "id": "870b286b-b04b-475f-84f4-eb82fa5dae7e",
            "timestamp": 1584715262990,
            "imageType": "LOCAL",
            "imageName": "test_image_1.jpg"
        },
        {
            "id": "c09d8c87-98ba-44dd-9c7e-9ad281763344",
            "timestamp": 1584957405034,
            "imageType": "SHAREABLE_LINK",
            "imageName": "test_image_2.jpg"
        }
    ]
}

401

{"msg": "Unauthorized. None or invalid credentials."}

Get All Datasets

GET https://app.datagym.ai/api/v1/dataset

This endpoint allows you to get all Datasets for the organisation of your API token.

Query Parameters

Name	Type	Description
token	string	Request parameter to verify your request.

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request.

200 Datasets successfully retrieved.

[
  {
    "id": "bfe5dcfd-adee-476e-81a9-3eee75c7c952",
    "name": "Dataset1",
    "shortDescription": "Short_Decription",
    "timestamp": 1582710735167,
    "owner": "de82f6de-4196-47d8-afe8-f2b614876586",
    "projectCount": 1,
    "mediaType": "IMAGE",
    "images": [
      {
        "id": "cdd8e9d1-725f-49e3-9c16-7565706f1520",
        "timestamp": 1582710744785,
        "imageType": "LOCAL",
        "imageName": "87703344_10221265040273456_8218964372425277440_o.jpg"
      },
      {
        "id": "89f169e2-1c37-4b9c-a185-563bb6905c43",
        "timestamp": 1582710745154,
        "imageType": "LOCAL",
        "imageName": "87759806_10221265165156578_6988954776155193344_o.jpg"
      }
    ]
  },
  {
    "id": "bfe5dcfd-adee-476e-81a9-3eee75c7c922",
    "name": "Dataset2",
    "shortDescription": "Short_Decription",
    "timestamp": 1582710735167,
    "owner": "de82f6de-4196-47d8-afe8-f2b614876546",
    "projectCount": 0,
    "mediaType": "IMAGE",
    "images": []
  }
]

401 Could not find an organisation matching to this token.

{"msg": "Unauthorized. None or invalid credentials."}

Create Dataset

POST https://app.datagym.ai/api/v1/dataset

This endpoint allows you to create a Dataset .

Query Parameters

Name	Type	Description
token	string	Request parameter to verify your request.

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request.

Request Body

Name	Type	Description
shortDescription	string	Short description of the Dataset.
name	string	The name of the Dataset.

200 Dataset successfully created.

{
  "id": "45d62020-8f31-4e38-8c1a-f78dcb03135b",
  "name": "Dataset1",
  "shortDescription": "Dataset1_description",
  "timestamp": 1582718162835,
  "owner": "1801d7a4-cdb8-4667-bbda-6af6f86b29d6",
  "projectCount": 0,
  "mediaType": "IMAGE",
  "images": []
}

401 Could not find an organisation matching this token.

{"msg": "Unauthorized. None or invalid credentials."}

Add Dataset to Project

POST https://app.datagym.ai/api/v1/project/{projectId}/dataset/{datasetId}

This endpoint allows you to add a Dataset to a Project.

Path Parameters

Name	Type	Description
datasetId	string	The Id of the Dataset.
projectId	string	The id of the Project.

Query Parameters

Name	Type	Description
token	string	Request parameter to verify your request.

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request.

200 Dataset successfully added to the Project.

401 Could not find organisation matching this token.

{"msg": "Unauthorized. None or invalid credentials."}

412 The Project is already connected with this Dataset.

Remove Dataset from Project

DELETE https://app.datagym.ai/api/v1/project/{projectId}/dataset/{datasetId}/remove

This endpoint allows you to remove the connection between Dataset and Project. The Dataset won't be deleted from the database.

Path Parameters

Name	Type	Description
datasetId	string	The Id of the Dataset.
projectId	string	The Id of the Project.

Query Parameters

Name	Type	Description
token	string	Request parameter to verify your request.

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request.

200 Dataset successfully removed from the Project.

401 Could not find organisation matching this token.

{"msg": "Unauthorized. None or invalid credentials."}

Create image (shareable link set)

POST https://app.datagym.ai/api/v1/image/{datasetId}/url

This endpoint allows you to create several Images at the same time. Supported image mime types are: "image/jpeg" and "image/png"

Path Parameters

Name	Type	Description
datasetId	string	The Id of the Dataset, in which you want to save your images.

Query Parameters

Name	Type	Description
token	string	Request parameter to verify your request.

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request.

Request Body

Name	Type	Description
imageUrlSet	string	Collection of String's with the URL's of the Images, that you want to create.

200 Returns collection with the Image-Url's and the upload status of every Image-Url ( SUCCESS, FAILED, UNSUPPORTED_FORMAT or DUPLICATE)

[
  {
    "internal_image_ID": "3b9c67f9-c2a2-4370-b080-5692b1c8b7ca",
    "external_image_ID": "test_image.jpg",
    "imageUrl": "https://test/test_image.jpg",
    "imageUploadStatus": "SUCCESS"
  },
  {
    "internal_image_ID": null,
    "external_image_ID": null,
    "imageUrl": "https://encrypted-tbn0.gstatic/test.jpg",
    "imageUploadStatus": "FAILED"
  },
  {
    "internal_image_ID": null,
    "external_image_ID": null,
    "imageUrl": "https://encrypted-tbn1/test2.gif",
    "imageUploadStatus": "UNSUPPORTED_FORMAT"
  }
]

401

{"msg": "Unauthorized. None or invalid credentials."}

Create image (local)

POST https://app.datagym.ai/api/v1/image/{datasetId}/file

Upload a local image to the dataset.

Path Parameters

Name	Type	Description
datasetId	string	The Id of the Dataset, in which you want to save your images.

Headers

Name	Type	Description
X-filename	string	The specific image name.
Authorization	string	Authorization token to verify your request.

Request Body

Name	Type	Description
	object	The image file in the body (only one image in *.jpg, *.jpeg, and *.png format)

200 Return the image date like the name and the internal id.

{
   'id': '9316607e-2d3e-402c-810a-9852c63217a0',
   'image_name': 'awesome_image', 
   'image_type': 'LOCAL', 
   'timestamp': 1592377072458 
}

401

{"msg": "Unauthorized. None or invalid credentials."}

Download Image

GET https://app.datagym.ai/api/v1/image/{imageId}

This endpoint allows you to download an Image. For video projects, a pre-signed temporary accessible URL will be returned to download the video.

Path Parameters

Name	Type	Description
imageId	string	The Id of the Image, that you want to download.

Query Parameters

Name	Type	Description
token	string	Request parameter to verify your request.

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request.

200 Downloading the Image.

401 Could not find organisation matching this token.

{"msg": "Unauthorized. None or invalid credentials."}

Delete Image

DELETE https://app.datagym.ai/api/v1/image/{imageId}

This endpoint allows you to delete an Image.

Path Parameters

Name	Type	Description
imageId	string	The Id of the Image, that you want to delete.

Query Parameters

Name	Type	Description
token	string	Request parameter to verify your request.

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request.

200 Image successfully deleted.

401

{"msg": "Unauthorized. None or invalid credentials."}

Export Labels

GET https://app.datagym.ai/api/v1/export/{projectId}

This endpoint allows you to export the Labels from a Project.

Path Parameters

Name	Type	Description
projectId	string	The Id of the Project

Query Parameters

Name	Type	Description
token	string	Request parameter to verify your request.

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request.

200 Downloading the Label Configuration and all Label Values for the current Project.

[
  {
    "label_classes": [
      {
        "class_name": "rectangle1_key",
        "geometry_type": "rectangle"
      }
    ]
  },
  {
    "internal_image_ID": "87dcfde0-30c3-446a-b9dc-3121621c40b5",
    "external_image_ID": "87678961_10221265039233430_6011932407320543232_o.jpg",
    "labeler": "25dcfde0-30c3-336a-b9dc-2521621c40f4",
    "status": "completed",
    "global_classifications": {},
    "labels": {
      "rectangle1_key": [
        {
          "geometry": [
            {
              "x": 535,
              "y": 258,
              "w": 804,
              "h": 541
            }
          ],
          "classifications": {}
        }
      ]
    }
  }
]

401

{"msg": "Unauthorized. None or invalid credentials."}

Import label

POST https://app.datagym.ai/api/v1/project/{projectID}/prediction

Post your JSON formatted data to DataGym. The format of the prelabeled data is described in the description of Import Data under the Project documentation.

Path Parameters

Name	Type	Description
projectId	string	The Id of the project.

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request.

Request Body

Name	Type	Description
payload	string	The prelabeled data.

200

401

{"msg": "Unauthorized. None or invalid credentials."}

Export segmentation bitmaps

GET /api/v1/export/bitmap/{taskId}/{exportKey}

Streams the image segmentation bitmap.

Path Parameters

Name	Type	Description
taskId	string	Id internally used by DataGym.ai
exportKey	string	The export key defined within your label configuration.

200

Streams the .bmp file

401

{"msg": "Unauthorized. None or invalid credentials."}

404 Example response if the export key was not found.

{
  "key" : "ex_notfound",
  "params" : [ "lcEntry", "entry_key", "unknown-key" ],
  "msg" : "lcEntry with entry_key unknown-key not found.",
  "code" : 404,
  "details" : [ ]
}

Clear Label Configuration

DELETE https://app.datagym.ai/api/v1/config/{configId}

Deletes all Entries from the current Label Configuration. The Values, that are related to this Entries, will also be deleted. The Label Configuration Entity will NOT be deleted. The state of all Tasks with state ''COMPLETED' or 'REVIEWED' will be set to 'WAITING_CHANGED'.

Path Parameters

Name	Type	Description
configId	string	The Id of the Label Configuration

Query Parameters

Name	Type	Description
token	string	Request parameter to verify your request

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request

200 The Entries and the related to them Values are deleted.

401

{"msg": "Unauthorized. None or invalid credentials."}

Upload Label Configuration

PUT https.//app.datagym.ai/api/v1/config/{configId}

This endpoint allows you to upload a Label Configuration. You need to clear your current Label Configuration first before you can upload the new Label Configuration.

Path Parameters

Name	Type	Description
configId	string	The Id of the Label Configuration

Query Parameters

Name	Type	Description
token	string	Request parameter to verify your request

Headers

Name	Type	Description
Authorization	string	Authorization token to verify your request

Request Body

Name	Type	Description
entries	string	List of all Entries from the new Label Configuration

200 Label Configuration successfully uploaded.

401

{"msg": "Unauthorized. None or invalid credentials."}

The Body Parameter entries is a JSON Object with all Entries of the new Label Configuration. There are three required fields for all Entries (geometries and classifications):

• entryKey

• entryValue

• type

Example: JSON with all geometries:

[
    {
        "entryKey": "linekey",
        "entryValue": "LineValue",
        "type": "line",
        "color": "green",
        "shortcut": "1",
        "children": []
    },
    {
        "entryKey": "pointkey",
        "entryValue": "PointValue",
        "type": "point",
        "color": "red",
        "shortcut": "3",
        "children": []
    },
    {
        "entryKey": "polygonkey",
        "entryValue": "PolyValue",
        "type": "polygon",
        "color": "blue",
        "shortcut": "5",
        "children": []
    },
    {
        "entryKey": "rectanglekey",
        "entryValue": "RectValue",
        "type": "rectangle",
        "color": "black",
        "shortcut": "8",
        "children": []
    }
]

After the upload you will see the following Label Configuration for this Project:

Label Configuration

Example: JSON with all classifications:

[
    {
        "entryKey": "checklistkey",
        "entryValue": "CheckValue",
        "type": "checklist",
        "required": true,
        "options": {
            "firstCheckListOptionKey": "firstCheckListOptionValue",
            "secondCheckListOptionKey": "secondCheckListOptionValue",
            "thirdCheckListOptionKey": "thirdCheckListOptionValue"
        },
        "children": []
    },
    {
        "entryKey": "freetextkey",
        "entryValue": "FreeTextValue",
        "type": "freetext",
        "required": false,
        "maxLength": 15,
        "children": []
    },
    {
        "entryKey": "selectkey",
        "entryValue": "SelectValue",
        "type": "select",
        "required": false,
        "options": {
            "firstSelectOptionKey": "firstSelectOptionValue",
            "secondSelectOptionKey": "secondSelectOptionValue",
            "thirdSelectOptionKey": "thirdSelectOptionValue"
        },
        "children": []
    }
]

After the upload you will see the following Label Configuration for this Project:

Label Configuration

You can combine and nest Geometries and Classifications to create your Label Configuration, for example:

[
    {
        "entryKey": "linekey",
        "entryValue": "LineValue",
        "type": "line",
        "color": "green",
        "shortcut": "1",
        "children": [
            {
                "entryKey": "checklistkey",
                "entryValue": "CheckValue",
                "type": "checklist",
                "required": true,
                "options": {
                    "firstCheckListOptionKey": "firstCheckListOptionValue",
                    "secondCheckListOptionKey": "secondCheckListOptionValue",
                    "thirdCheckListOptionKey": "thirdCheckListOptionValue"
                },
                "children": [
                    {
                        "entryKey": "freetextkey",
                        "entryValue": "TextValue",
                        "type": "freetext",
                        "required": false,
                        "maxLength": 15,
                        "children": []
                    }
                ]
            }
        ]
    },
    {
        "entryKey": "pointkey",
        "entryValue": "PointValue",
        "type": "point",
        "color": "red",
        "shortcut": "3",
        "children": []
    },
    {
        "entryKey": "polygonkey",
        "entryValue": "PolyValue",
        "type": "polygon",
        "color": "blue",
        "shortcut": "5",
        "children": []
    },
    {
        "entryKey": "rectanglekey",
        "entryValue": "RectValue",
        "type": "rectangle",
        "color": "black",
        "shortcut": "8",
        "children": []
    }
]

Label Configuration with nested Entries