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
Get All Projects
https://app.datagym.ai/api/v1/project
This endpoint allows you to get all Projects for the organisation of your API token.
Request
Response
Request
Headers
Authorization
optional
string
Authorization token to verify your request.
Query Parameters
token
optional
string
Request parameter to verify your request.
Response
200: OK
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: Unauthorized
Could not find an organisation matching this token.
{"msg": "Unauthorized. None or invalid credentials."}
get
Get Dataset by Id
https://app.datagym.ai/api/v1/dataset/{datasetId}
This endpoint allows you to get a Dataset by its Id.
Request
Response
Request
Path Parameters
datasetId
required
string
The Id of the Dataset.
Headers
Authorization
optional
string
Authorization token to verify your request.
Query Parameters
token
optional
string
Request param to verify your request.
Response
200: OK
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: Unauthorized
{"msg": "Unauthorized. None or invalid credentials."}
get
Get All Datasets
https://app.datagym.ai/api/v1/dataset
This endpoint allows you to get all Datasets for the organisation of your API token.
Request
Response
Request
Headers
Authorization
optional
string
Authorization token to verify your request.
Query Parameters
token
optional
string
Request parameter to verify your request.
Response
200: OK
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: Unauthorized
Could not find an organisation matching to this token.
{"msg": "Unauthorized. None or invalid credentials."}
post
Create Dataset
https://app.datagym.ai/api/v1/dataset
This endpoint allows you to create a Dataset .
Request
Response
Request
Headers
Authorization
optional
string
Authorization token to verify your request.
Query Parameters
token
optional
string
Request parameter to verify your request.
Body Parameters
shortDescription
optional
string
Short description of the Dataset.
name
required
string
The name of the Dataset.
Response
200: OK
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: Unauthorized
Could not find an organisation matching this token.
{"msg": "Unauthorized. None or invalid credentials."}
post
Add Dataset to Project
https://app.datagym.ai/api/v1/project/{projectId}/dataset/{datasetId}
This endpoint allows you to add a Dataset to a Project. 
Request
Response
Request
Path Parameters
datasetId
required
string
The Id of the Dataset.
projectId
required
string
The id of the Project.
Headers
Authorization
optional
string
Authorization token to verify your request.
Query Parameters
token
optional
string
Request parameter to verify your request.
Response
200: OK
Dataset successfully added to the Project.
​
401: Unauthorized
Could not find organisation matching this token.
{"msg": "Unauthorized. None or invalid credentials."}
412: Precondition Failed
The Project is already connected with this Dataset.
​
delete
Remove Dataset from Project
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.
Request
Response
Request
Path Parameters
datasetId
required
string
The Id of the Dataset.
projectId
required
string
The Id of the Project.
Headers
Authorization
optional
string
Authorization token to verify your request.
Query Parameters
token
optional
string
Request parameter to verify your request.
Response
200: OK
Dataset successfully removed from the Project.
​
401: Unauthorized
Could not find organisation matching this token.
{"msg": "Unauthorized. None or invalid credentials."}
post
Create image (shareable link set)
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"
Request
Response
Request
Path Parameters
datasetId
required
string
The Id of the Dataset, in which you want to save your images.
Headers
Authorization
optional
string
Authorization token to verify your request.
Query Parameters
token
optional
string
Request parameter to verify your request.
Body Parameters
imageUrlSet
required
string
Collection of String's with the URL's of the Images, that  you want to create.
Response
200: OK
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: Unauthorized
{"msg": "Unauthorized. None or invalid credentials."}
post
Create image (local)
https://app.datagym.ai/api/v1/image/{datasetId}/file
Upload a local image to the dataset.
Request
Response
Request
Path Parameters
datasetId
required
string
The Id of the Dataset, in which you want to save your images.
Headers
X-filename
required
string
The specific image name.
Authorization
optional
string
Authorization token to verify your request.
Body Parameters
required
object
The image file in the body (only one image in *.jpg, *.jpeg, and *.png format)
Response
200: OK
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: Unauthorized
{"msg": "Unauthorized. None or invalid credentials."}
get
Download Image
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.
Request
Response
Request
Path Parameters
imageId
required
string
The Id of the Image, that you want to download.
Headers
Authorization
optional
string
Authorization token to verify your request.
Query Parameters
token
optional
string
Request parameter to verify your request.
Response
200: OK
Downloading the Image.
​
401: Unauthorized
Could not find organisation matching this token. 
{"msg": "Unauthorized. None or invalid credentials."}
delete
Delete Image
https://app.datagym.ai/api/v1/image/{imageId}
This endpoint allows you to delete an Image.
Request
Response
Request
Path Parameters
imageId
required
string
The Id of the Image, that you want to delete.
Headers
Authorization
optional
string
Authorization token to verify your request.
Query Parameters
token
optional
string
Request parameter to verify your request.
Response
200: OK
Image successfully deleted.
​
401: Unauthorized
{"msg": "Unauthorized. None or invalid credentials."}
get
Export Labels
https://app.datagym.ai/api/v1/export/{projectId}
This endpoint allows you to export the Labels from a Project.
Request
Response
Request
Path Parameters
projectId
required
string
The Id of the Project
Headers
Authorization
optional
string
Authorization token to verify your request.
Query Parameters
token
optional
string
Request parameter to verify your request.
Response
200: OK
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: Unauthorized
{"msg": "Unauthorized. None or invalid credentials."}
post
Import label
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.
Request
Response
Request
Path Parameters
projectId
required
string
The Id of the project.
Headers
Authorization
optional
string
Authorization token to verify your request.
Body Parameters
payload
optional
string
The prelabeled data.
Response
200: OK
​
401: Unauthorized
{"msg": "Unauthorized. None or invalid credentials."}
get
Export segmentation bitmaps
/api/v1/export/bitmap/{taskId}/{exportKey}
Streams the image segmentation bitmap.
Request
Response
Request
Path Parameters
taskId
required
string
Id internally used by DataGym.ai
exportKey
required
string
The export key defined within your label configuration.
Response
200: OK
Streams the .bmp file
401: Unauthorized
{"msg": "Unauthorized. None or invalid credentials."}
404: Not Found
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" : [ ]
}
delete
Clear Label Configuration
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'.
Request
Response
Request
Path Parameters
configId
required
string
The Id of the Label Configuration
Headers
Authorization
optional
string
Authorization token to verify your request
Query Parameters
token
optional
string
Request parameter to verify your request
Response
200: OK
The Entries and the related to them Values are deleted.
​
401: Unauthorized
{"msg": "Unauthorized. None or invalid credentials."}
put
Upload Label Configuration
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.
Request
Response
Request
Path Parameters
configId
required
string
The Id of the Label Configuration
Headers
Authorization
optional
string
Authorization token to verify your request
Query Parameters
token
optional
string
Request parameter to verify your request
Body Parameters
entries
required
string
List of all Entries from the new Label Configuration
Response
200: OK
Label Configuration successfully uploaded.
​
401: Unauthorized
{"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