Markup
v1
by yashka

Markup

Markup Tool for Ring
API Methods
Images

Endpoint for managing images

Get images
GET /images
Get image
GET /images/{IMAGE_ID}
Create new image
POST /images
Delete image
DELETE /images/{IMAGE_ID}
Get images
GET /images

Request parameters

page_id
number optional

Page number to return

Default:
0
page_limit
number optional

Number of images to return

Default:
1000

Responses

200 OK
Body
New image collection
Examples
{
    "images": [
        {
            "image_id": "image42",
            "image_src": "test_src",
            "url": "s3://images.com/42",
            "video_id": "adasdasdas",
            "frame": 12,
            "object_id": 1234,
            "mac": "adasr434dcsaca",
            "extra_meta": {
                "param": 42,
                "is_reference": true
            },
            "created_at": 12345564563,
            "deleted_at": 414252356235
        }
    ],
    "meta": {
        "page_id": 1,
        "page_limit": 1,
        "total_count": 1
    }
}
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/images_new HTTP/1.1 

HTTP/1.1 200 OK 

{
    "images": [
        {
            "image_id": "image42",
            "image_src": "test_src",
            "url": "s3://images.com/42",
            "video_id": "adasdasdas",
            "frame": 12,
            "object_id": 1234,
            "mac": "adasr434dcsaca",
            "extra_meta": {
                "param": 42,
                "is_reference": true
            },
            "created_at": 12345564563,
            "deleted_at": 414252356235
        }
    ],
    "meta": {
        "page_id": 1,
        "page_limit": 1,
        "total_count": 1
    }
}
Get image
GET /images/{IMAGE_ID}

Get image by image_id

Path variables

IMAGE_ID
string required

Responses

200 OK
Body
Object
image
New image response object
404 Not Found
Body
Object
error
string
Example:
Image {image_id} not found in db
Examples
{
    "error": "Image image_id_123 not found in db"
}
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/images_new/image123 HTTP/1.1 

HTTP/1.1 200 OK 

{
    "image": {
        "image_id": "image123",
        "image_src": "test_src",
        "url": "s3://images.com/42",
        "video_id": "adasdasdas",
        "frame": 12,
        "object_id": 1234,
        "mac": "adasr434dcsaca",
        "extra_meta": {
            "param": 42,
            "is_reference": true
        },
        "created_at": 12345564563,
        "deleted_at": 414252356235
    }
}
Create new image
POST /images

Request body

New image request object
Examples
{
    "image_id": "image42",
    "image_src": "test_src",
    "url": "s3://images.com/42",
    "video_id": "adasdasdas",
    "frame": 12,
    "object_id": 1234,
    "mac": "adasr434dcsaca",
    "extra_meta": {
        "param": 42,
        "is_reference": true
    }
}

Responses

201 Created
Headers
Location
string required

New resource location

Example:
/api/v1/images_new/image_id_1234
409 Conflict
Body
Object
error
string
Example:
Image with id={image_id} already exist
Examples
{
    "error": "Image with id=image_id_123 already exist"
}
400 Bad input

Request body is not a valid image object

Delete image
DELETE /images/{IMAGE_ID}

Path variables

IMAGE_ID
string required

Responses

204 No Content

Image deleted successfully

404 Not Found
Body
Object
error
string
Example:
Image id=image_id123 not found in DB
Example 1
DELETE https://markup-tool.ringlabskiev.com/api/v1/images_new/image_123145 HTTP/1.1 

HTTP/1.1 204 No Content
New image response object
Object
image_id
string
Example:
image42
image_src
string
Example:
test_src
url
string
Example:
s3://images.com/42
video_id
string
Example:
adasdasdas
frame
integer
Example:
12
object_id
integer
Example:
1234
mac
string
Example:
adasr434dcsaca
extra_meta
Object
param
integer
Example:
42
is_reference
boolean
Example:
true
created_at
integer
Example:
12345564563
deleted_at
integer
Example:
414252356235
New image request object

Schema for new image

Object
image_id
string required
Example:
image42
image_src
string required
Example:
test_src
url
string required
Example:
s3://images.com/42
video_id
string nullable
Example:
adasdasdas
frame
integer nullable
Example:
12
object_id
integer nullable
Example:
1234
mac
string nullable
Example:
adasr434dcsaca
extra_meta
Object nullable
param
integer
Example:
42
is_reference
boolean
Example 1
{
    "image_id": "image42",
    "image_src": "test_src",
    "url": "s3://images.com/42",
    "video_id": "adasdasdas",
    "frame": 12,
    "object_id": 1234,
    "mac": "adasr434dcsaca",
    "extra_meta": {
        "param": 42,
        "is_reference": true
    }
}
New image collection
Object
images
Array of New image response object
meta
Paginate Metadata
Image object

Regular image of dataset

Object
Example: 
{
    "id": 1,
    "uri": "s3://path/to/image",
    "dataset_id": 1,
}
id
number

image id

uri
string

image uri

dataset_id
number

dataset id

Face Validation
Set image group results
POST /fr_validation/results
Get image group
GET /fr_validation/images
Set image group results
POST /fr_validation/results

Request parameters

task_id
number required

Request body

Object
<image_id>
Object
confirmed
boolean
Example:
true
Examples
{
    1: {
        "confirmed": true
    },
    2: {
         "confirmed": false
    },
}

Responses

201 Created
v1
POST https://markup-tool.ringlabskiev.com/api/v1/re_id/results HTTP/1.1 

Content-Type: application/json

{
    "<image_id>": {
        "confirmed": true
    }
}

HTTP/1.1 201 Created
Get image group
GET /fr_validation/images

Request parameters

task_id
number required

Responses

200 OK
Body
Object
images
Array of Image object
Examples
{
    "images": [
        {
            "id": 1,
            "uri": "",
            "dataset_id": 1
        }
    ]
}
204 No Content

Task is Completed

400 Wrong user

User does not have access to this task according to group assignment

Face Recognition
Get reference image
GET /fr/ref-image
Get images
GET /fr/images
Set images results
POST /fr/results
Get reference image
GET /fr/ref-image

Reference image used for task

Request parameters

task_id
integer required

Get reference image for specified task

Responses

200 OK
Body
Object
image
Image object
Examples
{
    "image": {
        "id": 1,
        "uri": "",
        "dataset_id": 1
    }
}
404 Not Found
Get images
GET /fr/images

Request parameters

task_id
number required
count
number optional

Responses

200 OK
Body
Object
images
Array of Image object
reference
Image object
Examples
{
    "images": [
        {
            "id": 1,
            "uri": "",
            "dataset_id": 1
        }
    ],
    "reference": {
        "id": 1,
        "uri": "",
        "dataset_id": 1
    }
}
Set images results
POST /fr/results

Request parameters

task_id
number required

Request body

Object
<image_id>
Object
confirmed
boolean
Example:
true
Examples
{
    1: {
        "confirmed": true
    },
    2: {
         "confirmed": false
    },
}

Responses

201 Created
v1
POST https://markup-tool.ringlabskiev.com/api/v1/re_id/results HTTP/1.1 

Content-Type: application/json

{
    "<image_id>": {
        "confirmed": true
    }
}

HTTP/1.1 201 Created
Object Classification
Get Images For Object Classification
GET /object-classification/images
Send Images Result
POST /object-classification/results
Get Images For Object Classification
GET /object-classification/images

Request parameters

task_id
number required
count
number optional

Responses

200 OK
Body
Object
images
Array
Object
id
integer
Example:
1
uri
string
Example:
s3://path/to/image
meta
Object
dataset_id
integer
Example:
1
Examples
{
    "images": [
        {
            "id": 1,
            "uri": "s3://path/to/image",
            "meta": {},
            "dataset_id": 1
        }
    ]
}
400 Not Found
Send Images Result
POST /object-classification/results

Request parameters

task_id
number required

Request body

Object
1
Object

image_id

confirmed
boolean

boolean

Example:
true
Examples
{
    "1": {
        "confirmed": true
    },
    "2": {
        "confirmed": true
    }
}

Responses

201 Created
Person Diversity
Get Images For Person Diversity
GET /person-diversity/images
Send Images Result For Person Diversity
POST /person-diversity/results
Get Images For Person Diversity
GET /person-diversity/images

Request parameters

task_id
number required
count
number optional

Responses

200 OK
Body
Object
images
Array
Object
id
integer
Example:
1
uri
string
Example:
s3://path/to/image
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/person-diversity/images?task_id=123&count=1 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "images": [
        {
            "id": 1,
            "uri": "s3://path/to/image"
        }
    ]
}
Send Images Result For Person Diversity
POST /person-diversity/results

Request parameters

task_id
integer required

Request body

Object
1
Object

Key - markup_result id

gender
string

(Male|Female)

Example:
Male
age_range
string

(Age_1_14|Age_15_24|Age_25_64|Age_65_plus)

Example:
Age_1_14
ethnicity
string

(African|European|Asian|Hispanic|Other)

Example:
European
Examples
{
    "1": {
        "gender": "Male",
        "age_range": "Age_1_14",
        "ethnicity": "European"
    },
    "7": {
        "gender": "Female",
        "age_range": "Age_5_24",
        "ethnicity": "Other"
    }
}

Responses

201 Created
Re-id
Get reference image
GET /re-id/ref-image
Get images
GET /re-id/images
Set images results
POST /re-id/results
Get reference image
GET /re-id/ref-image

Reference image used for task

Request parameters

task_id
integer required

Get reference image for specified task

Responses

200 OK
Body
Object
image
Image object
Examples
{
    "image": {
        "id": 1,
        "uri": "s3://path/to/image",
        "meta": {},
        "dataset_id": 1
    }
}
404 Not Found
Get images
GET /re-id/images

Request parameters

task_id
number required
count
number optional

Responses

200 OK
Body
Object
images
Array of Image object
Examples
{
    "images": [
        {
            "id": 1,
            "uri": "s3://path/to/image",
            "meta": {},
            "dataset_id": 1
        }
    ]
}
Set images results
POST /re-id/results

Request parameters

task_id
number required

Request body

Object
<image_id>
Object
confirmed
boolean
Example:
true
Examples
{
    1: {
        "confirmed": true
    },
    2: {
         "confirmed": false
    },
}

Responses

201 Created
v1
POST https://markup-tool.ringlabskiev.com/api/v1/re_id/results HTTP/1.1 

Content-Type: application/json

{
    "<image_id>": {
        "confirmed": true
    }
}

HTTP/1.1 201 Created
Authorization
Get Authorized User
GET /me
Get Authorization URL
GET /login
Delete Session
DELETE /me
Get Authorized User
GET /me

Get user if it authenticated

Responses

200 OK

If User Authorized

Body
Object
user
Object
email
string
Example:
test@ring.com
roles
Array of string
Example: 
["operator", "admin"]
picture
string
Example:
https://lh3.googleusercontent.com/-MLokQf3w8Ug/AAAAAAAAAAI/AAAAAAAAAAA/ACLGyWCtciGra-GafBvxsjTVDl_DrLkO9g/s64-c-mo/photo.jpg
id
number
Example:
1
name
string
Example:
Elon Mask
401 Unauthorized

If User non-authorized

v1
GET http://markup.com/api/v1/session HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "user": {
        "email": "test@ring.com",
        "roles": [
            {
                "id": 1,
                "name": "admin"
            }
        ],
        "picture": "https://lh3.googleusercontent.com/-MLokQf3w8Ug/AAAAAAAAAAI/AAAAAAAAAAA/ACLGyWCtciGra-GafBvxsjTVDl_DrLkO9g/s64-c-mo/photo.jpg",
        "id": 1,
        "name": "Elon Mask"
    }
}
Get Authorization URL
GET /login

Return Google Authorization URL

Responses

200 OK
Body
Object
url
string
Example:
https://accounts.google.com/signin/oauth/oauthchooseaccount?client_id=201661002672-raggr5uiijoat020ue2n7dn5gu781far.apps.googleusercontent.com&as=v2jd2ZGuU5FOic_BnpAklw&destination=https%3A%2F%2Fsirena.qa.ring.com&approval_state=!ChRrZjczWUE4Q1pRUlduSWFCbjJQTBIfRTdqR3IzVlNJT0VUOERFdWhZOThQYzgxa1ZuVUxCWQ%E2%88%99AB8iHBUAAAAAWtWcqchF8yk0e-QcKgVRLzDlFII7q-C5&xsrfsig=AHgIfE9MVTGFTDX11mtbf_RfxnxaHmEG5Q&flowName=GeneralOAuthFlow
400 Bad Request
v1
GET http://markup.com/api/v1/login HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "url": "https://accounts.google.com/signin/oauth/oauthchooseaccount?client_id=201661002672-raggr5uiijoat020ue2n7dn5gu781far.apps.googleusercontent.com&as=v2jd2ZGuU5FOic_BnpAklw&destination=https%3A%2F%2Fsirena.qa.ring.com&approval_state=!ChRrZjczWUE4Q1pRUlduSWFCbjJQTBIfRTdqR3IzVlNJT0VUOERFdWhZOThQYzgxa1ZuVUxCWQ%E2%88%99AB8iHBUAAAAAWtWcqchF8yk0e-QcKgVRLzDlFII7q-C5&xsrfsig=AHgIfE9MVTGFTDX11mtbf_RfxnxaHmEG5Q&flowName=GeneralOAuthFlow"
}
Delete Session
DELETE /me

Responses

204 No Content
401 Unauthorized
v1
DELETE http://markup.com/api/v1/session HTTP/1.1 

HTTP/1.1 204 No Content 

HTTP/1.1 404 Not Found
Datasets
Get all Datasets
GET /datasets
Get Dataset By Id
GET /datasets/{DATASET_ID}
Create Dataset
POST /datasets
Change Dataset
PATCH /datasets/{DATASET_ID}
Delete Dataset
DELETE /datasets/{DATASET_ID}
Bulk delete datasets
PATCH /datasets
Get all Datasets
GET /datasets

Request parameters

page_id
number optional

Page Increment Identifier

Example:
1
page_limit
number optional

Objects per page default=1000

Example:
300

Responses

200 OK
Body
Object
datasets
Array
Object
id
integer
Example:
3
created_at
integer
Example:
1528300892
description
string

Can be null

name
string
Example:
p0u769PyNiazQloW
image_count
number
Example:
32
meta
Object
page_id
integer
Example:
1
page_limit
integer
Example:
2
total_count
integer
Example:
380
400 Bad Request
V1
GET https://markup-tool.ringlabskiev.com/api/v1/datasets?page_id=1&page_limit=2 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "datasets": [
        {
      "id": 3,
      "created_at": 1528300892,
      "description": null,
      "name": "p0u769PyNiazQloW",
      "image_count": 32
    },
    {
      "id": 4,
      "created_at": 1528300892,
      "description": null,
      "name": "nyEsT7kOQZc8Izm8",
      "image_count": 32
    }
    ],
    "meta": {
        "page_id": 1,
        "page_limit": 2,
        "total_count": 380
    }
}

HTTP/1.1 400 Bad Request
Get Dataset By Id
GET /datasets/{DATASET_ID}

Path variables

DATASET_ID
string required
Example:
1

Responses

200 OK

If Dataset finded

Body
Object
dataset
Object
id
integer

A unique identifier for each Datasets. This is automatically generated upon Dataset creation.

Example:
1
name
string

The human-readable name set for the Dataset.

Example:
Dataset_1
description
string
Example:
Dataset_Description
created_at
integer

Time in Unix format

Example:
1523871230266
image_count
number

Number of images in dataset

404 Not Found

If Dataset missing

v1
GET http://markup.com/api/v1/datasets/1 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "dataset": {
        "id": 1,
        "name": "Dataset_1",
        "description": "Dataset_Description",
        "created_at": 1523871230266,
        "image_count": 32
    }
}
Create Dataset
POST /datasets

Request body

Object
name
string required
Example:
Dataset_Name
description
string required
Example:
Dataset_Description
image_filter
Object

filter criteria to include images into newly created dataset

video_ids
Array of string

list of video_ids

macs
Array of string

list of macs

Responses

201 Created

If Dataset is successfully created

Body
Object
dataset
Object
id
integer
Example:
1
name
string
Example:
Dataset_1
description
string
Example:
Dataset_Description
created_at
integer
Example:
1523871230266
updated_at
integer
Example:
1523871230266
409 Conflict

If Dataset with the same name already exist

v1
POST https://markup-tool.ringlabskiev.com/api/v1/datasets HTTP/1.1 

Content-Type: application/json

{
    "name": "Dataset_Name",
    "description": "Dataset_Description",
    "image_filter": {
        "video_ids": [
            "acvfweqwd", "adasdsad"
        ],
        "macs": [
            "12345", "5678"
        ]
    }
}
Change Dataset
PATCH /datasets/{DATASET_ID}

Path variables

DATASET_ID
integer required
Example:
1

Request body

Object
name
string
Example:
New_Dataset_Name
description
string
Example:
New_Dataset_Description

Responses

200 OK
Body
Object
dataset
Object
id
integer
Example:
1
name
string
Example:
New_Dataset_Name
description
string
Example:
New_Dataset_Description
created_at
integer
Example:
1523871230266
updated_at
integer
Example:
1523871230266
v1
PATCH http://markup.com/api/v1/datasets/1 HTTP/1.1 

Content-Type: application/json

{
    "name": "New_Dataset_Name",
    "description": "New_Dataset_Description"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "dataset": {
        "id": 1,
        "name": "New_Dataset_Name",
        "description": "New_Dataset_Description",
        "created_at": 1523871230266,
        "updated_at": 1523871230266
    }
}
Delete Dataset
DELETE /datasets/{DATASET_ID}

Path variables

DATASET_ID
integer required
Example:
1

Responses

204 No Content
404 Not Found
v1
Example 2
DELETE http://markup.com/api/v1/datasets/1 HTTP/1.1 

HTTP/1.1 204 No Content 
DELETE http://markup.com/api/v1/datasets/1 HTTP/1.1 

HTTP/1.1 204 No Content
Bulk delete datasets
PATCH /datasets

Request body

Object
op
string
Example:
delete
ids
Array
Example: 
[1,2]
integer
Example:
1

Responses

200 OK
Body
Object
op
string
Example:
delete
id
integer
Example:
1
result
string
Example:
success
Example 1
PATCH https://markup-tool.ringlabskiev.com/api/v1/datasets HTTP/1.1 

Content-Type: application/json

{
    "op": "delete",
    "ids": [
        1,2
    ]
}

HTTP/1.1 200 OK 

Content-Type: application/json

[{
    "op": "delete",
    "id": 1,
    "result": "success"
},{
    "op": "delete",
    "id": 2,
    "result": "fail"
}]
Tasks
Get all tasks list
GET /tasks
Create task
POST /tasks
Get task
GET /tasks/{TASK_ID}
Get User Tasks
GET /users/{USER_ID}/tasks
Get User Current Active Task
GET /tasks/active
Get Current User Tasks
GET /me/tasks
Update task
PATCH /tasks/{task_id}
Export task results
GET /tasks/{TASK_ID}/export
Get Task Progress
GET /tasks/{TASK_ID}/progress
Delete Task
DELETE /api/v1/tasks/{TASK_ID}
Bulk edit/delete tasks
PATCH /tasks
Get all tasks list
GET /tasks

Request parameters

page_id
integer optional
Default:
0
page_limit
integer optional
Default:
1000
status
Task status optional
group_id
integer optional
pipeline_id
integer optional

Responses

200 OK
Body
Object
tasks
Array of Markup task object
meta
Object
total_count
integer
Example:
54
page_id
integer
Example:
1
page_limit
integer
Example:
10
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/tasks HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "tasks": [
        {
            "id": 121,
            "name": "Task_1",
            "description": "Task_Description",
            "layer_id": 12,
            "dataset_id": 745634,
            "pipeline_id": 1,
            "group_id": 14,
            "status": "created",
            "created_at": 153452348,
            "ref_image_id": 1
        }
    ],
    "meta": {
        "total_count": 54,
        "page_id": 1,
        "page_limit": 10
    }
}
Create task
POST /tasks

Request body

Object
name
string required
Example:
Task_1
description
string required
Example:
Task_Description
layer_id
integer required
Example:
100
dataset_id
integer required
Example:
745634
pipeline_id
integer required
Example:
1
group_id
integer required
Example:
14
status
string
Example:
completed
task_ids
Array of number

List of ids of FaceRecognition tasks to create FRValidation task from. If pipeline_id = 4 then task_ids MUST be present in request body. If pipeline_id != 4 then task_ids MUST NOT be present in request body

Example: 
[
    1, 2, 3
]

Responses

201 Created
Body
Markup task object
Example 1
Example 2

Basic example

POST https://markup-tool.ringlabskiev.com/api/v1/tasks HTTP/1.1 

Content-Type: application/json

{
    "name": "Task_1",
    "description": "Task_Description",
    "layer_id": 100,
    "dataset_id": 745634,
    "pipeline_id": 1,
    "group_id": 14
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": 121,
    "name": "Task_1",
    "description": "Task_Description",
    "layer_id": 12,
    "dataset_id": 745634,
    "pipeline_id": 1,
    "group_id": 14,
    "status": "created",
    "created_at": 153452348,
    "ref_image_id": 1
}

FRValidation task example

POST https://markup-tool.ringlabskiev.com/api/v1/tasks HTTP/1.1 

Content-Type: application/json

{
    "name": "Task_1",
    "description": "Task_Description",
    "layer_id": 100,
    "dataset_id": 745634,
    "pipeline_id": 4,
    "group_id": 14,
    "task_ids": [
        1
    ]
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": 121,
    "name": "Task_1",
    "description": "Task_Description",
    "layer_id": 12,
    "dataset_id": 745634,
    "pipeline_id": 4,
    "group_id": 14,
    "status": "created",
    "created_at": 153452348,
    "ref_image_id": 1
}
Get task
GET /tasks/{TASK_ID}

Path variables

TASK_ID
integer required

Responses

200 OK
Body
Object
task
Markup task object
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/tasks/{TASK_ID} HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "task": {
        "id": 121,
        "name": "Task_1",
        "description": "Task_Description",
        "layer_id": 12,
        "dataset_id": 745634,
        "pipeline_id": 1,
        "group_id": 14,
        "status": "created",
        "created_at": 153452348,
        "ref_image_id": 1
    }
}
Get User Tasks
GET /users/{USER_ID}/tasks

Authentication

Return all user tasks

Path variables

USER_ID
number required
Example:
42

Request parameters

status
Task status optional

Request only tasks with specified status

page_id
integer optional
Example:
1
page_limit
integer optional
Example:
10

Responses

200 OK
Body
Object
tasks
Array of Markup task object
meta
Object
total_count
integer

Total objects count

Example:
54
page_id
integer

Current page id

Example:
1
page_limit
integer

Items per page limit

Example:
10
v1
Example 2
GET https://markup-tool.ringlabskiev.com/api/v1/users/42/tasks HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "tasks": [
        {
            "id": 121,
            "name": "Task_1",
            "description": "Task_Description",
            "layer_id": 12,
            "dataset_id": 745634,
            "pipeline_id": 1,
            "group_id": 14,
            "status": "created",
            "created_at": 153452348,
            "ref_image_id": 1
        }
    ],
    "meta": {
        "total_count": 54,
        "page_id": 1,
        "page_limit": 10
    }
}
GET https://markup-tool.ringlabskiev.com/api/v1/users/42/tasks HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "tasks": [
        {
            "id": 121,
            "name": "Task_1",
            "description": "Task_Description",
            "layer_id": 12,
            "dataset_id": 745634,
            "pipeline_id": 1,
            "group_id": 14,
            "status": "created",
            "created_at": 153452348,
            "ref_image_id": 1
        }
    ],
    "meta": {
        "total_count": 54,
        "page_id": 1,
        "page_limit": 10
    }
}
Get User Current Active Task
GET /tasks/active

Responses

200 OK
Body
Object
task
Object
id
integer
Example:
1
name
string
Example:
Task_1
description
string
Example:
Task_Description
layer_id
integer
Example:
1
dataset_id
integer
Example:
1
pipeline_id
integer
Example:
1
group_id
integer
Example:
1
status
string

The current status of the Task. This can be “active”.

Example:
active
ref_image_id
integer
v1
GET https://markup-tool.ringlabskiev.com/api/v1/tasks/active HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "task": {
        "id": 1,
        "name": "Task_1",
        "description": "Task_Description",
        "layer_id": 1,
        "dataset_id": 1,
        "pipeline_id": 1,
        "group_id": 1,
        "status": "active",
        "ref_image_id": 1
    }
}
Get Current User Tasks
GET /me/tasks

Return all tasks for current user

Request parameters

status
Task status optional

Request only tasks with specified status

page_id
integer optional
Example:
1
page_limit
integer optional
Example:
10

Responses

200 OK
Body
Object
tasks
Array of Markup task object
meta
Object
total_count
integer

Total objects count

Example:
54
page_id
integer

Current page id

Example:
1
page_limit
integer

Items per page limit

Example:
10
v1
Example 2
GET https://markup-tool.ringlabskiev.com/api/v1/me/tasks HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "tasks": [
        {
            "id": 121,
            "name": "Task_1",
            "description": "Task_Description",
            "layer_id": 12,
            "dataset_id": 745634,
            "pipeline_id": 1,
            "group_id": 14,
            "status": "created",
            "created_at": 153452348,
            "ref_image_id": 1
        }
    ],
    "meta": {
        "total_count": 54,
        "page_id": 1,
        "page_limit": 10
    }
}
GET https://markup-tool.ringlabskiev.com/api/v1/me/tasks HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "tasks": [
        {
            "id": 121,
            "name": "Task_1",
            "description": "Task_Description",
            "layer_id": 12,
            "dataset_id": 745634,
            "pipeline_id": 1,
            "group_id": 14,
            "status": "created",
            "created_at": 153452348,
            "ref_image_id": 1
        }
    ],
    "meta": {
        "total_count": 54,
        "page_id": 1,
        "page_limit": 10
    }
}
Update task
PATCH /tasks/{task_id}

Path variables

task_id
integer required

Request body

Object
name
string
Example:
string
description
string
Example:
string
status
string
Example:
one of: created, active, postponed, completed
group_id
string
Example:
integer

Responses

200 OK
Body
Object
task
Markup task object
404 Not Found

Task does not exist OR group does not exist.

Example 1
PATCH https://markup-tool.ringlabskiev.com/api/v1/tasks/2 HTTP/1.1 

Content-Type: application/json

{
    "name": "ololo",
    "description": "new desc",
    "status": "active",
    "group_id": 4
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "task": {
        "id": 121,
        "name": "ololo",
        "description": "new desc",
        "layer_id": 12,
        "dataset_id": 745634,
        "pipeline_id": 1,
        "group_id": 4,
        "status": "active",
        "created_at": 153452348,
        "ref_image_id": 1
    }
}
Export task results
GET /tasks/{TASK_ID}/export

Path variables

TASK_ID
string required

Responses

200 OK
Body
application/octet-stream

A comma separated value file with two columns a path to an image, does the image contains reference person

400 Wrong task state

Task should be in Completed state

404 Not Found

Task not found in db

Get Task Progress
GET /tasks/{TASK_ID}/progress

Path variables

TASK_ID
string required

Responses

200 OK
Body
Object
progress
number

progress in percents

Example:
60
404 Not Found

If task by id is missing

Body
Object
error
string
Example:
Task missing
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/tasks/1/progress HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "progress": 60
}

HTTP/1.1 404 Not Found 

Content-Type: application/json

{
    "error": "Task missing"
}
Data objects
Markup task object
Object
id
integer
Example:
121
name
string
Example:
Task_1
description
string
Example:
Task_Description
layer_id
integer
Example:
12
dataset_id
integer
Example:
745634
pipeline_id
integer
Example:
1
group_id
integer
Example:
14
status
Task status
created_at
number
Example:
153452348
ref_image_id
number

id of reference image

Task status
string
Enumeration:
created
active
postponed
completed
Example:
created
Delete Task
DELETE /api/v1/tasks/{TASK_ID}

Path variables

TASK_ID
number required

Unique Task id

Responses

204 No Content

If deleting was succesfull

400 Bad Request

If id not valid

Bulk edit/delete tasks
PATCH /tasks

Route for bulk operations on tasks. Supports bulk deletion as well as bulk changing task status and task group.

Request body

Object
op
string

One of ‘delete’, ‘replace’

Example:
delete
ids
Array

List of task ids to delete

Example: 
[1,2,3,4]
integer
Example:
1
status
string

one of created, active, postponed, completed

Example:
active
group_id
integer
Example:
1

Responses

200 OK
Body
Object
id
integer
Example:
1
op
string
Example:
delete
result
string
Example:
success
Example 1
PATCH https://markup-tool.ringlabskiev.com/api/v1/tasks HTTP/1.1 

Content-Type: application/json

{
    "op": "replace",
    "ids": [
        1, 2, 3
    ],
    "status": "active",
    "group_id": 2
}

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
    "id": 1,
    "op": "replace",
    "result": "success"
    },
    {
    "id": 2,
    "op": "replace",
    "result": "fail"
    },
    {
    "id": 3,
    "op": "replace",
    "result": "fail"
    }
]
Images import
S3 Import
Import images from S3
POST /dataset/{dataset_id}/import
Import images from S3
POST /dataset/{dataset_id}/import

Path variables

dataset_id
string required

Request body

Object
uri
string
Example:
markup-images

Responses

202 Accepted
Example 1
POST http://markup.com/api/v1/dataset/1/import HTTP/1.1 

Content-Type: application/json

{
    "uri": "s3://{s3_bucket}"
}

HTTP/1.1 201 Created
Users
Get users
GET /users
Add user
POST /users
Get user
GET /users/{USER_ID}
Get user roles
GET /users/{user_id}/roles
Add roles to user
PATCH /users/{user_id}/roles
Remove roles from user
DELETE /users/{user_id}/roles
Get user groups
GET /users/{user_id}/groups
Add user to groups
PATCH /users/{user_id}/groups
Delete user from groups
DELETE /users/{user_id}/groups
Get groups
GET /groups
Get group
GET /groups/{group_id}
Get all users in specific group
GET /groups/{group_id}/users
Add group
POST /groups
Delete user
DELETE /users/{USER_ID}
User data objects
User object schema
Object
id
integer
Example:
14
name
string
Example:
john_doe
email
string
Example:
john.doe@example.com
picture
string
Example:
https://images.com/john_doe.jpg
Group
Object
Example: 
{
    "id": 1,
    "name": "group_1"
}
id
number
name
string
Get users
GET /users

Request parameters

page_id
integer optional
Default:
0
page_limit
string optional
Default:
1000

Responses

200 OK
Body
Object
users
Array of User object schema
meta
Paginate Metadata
Examples
{
    "users": [
        {
            "id": 14,
            "name": "john_doe",
            "email": "john.doe@example.com",
            "picture": "https://images.com/john_doe.jpg"
        }
    ],
    "meta": {
        "page_id": 0,
        "page_limit": 1,
        "total_count": 1
    }
}
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/users?page_id=0&page_limit=1000 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "users": [
        {
            "id": 14,
            "name": "john_doe",
            "email": "john.doe@example.com",
            "picture": "https://images.com/john_doe.jpg"
        }
    ],
    "meta": {
        "page_id": 1,
        "page_limit": 1000,
        "total_count": 32
    }
}
Add user
POST /users

Request parameters

email
string required
name
string optional
picture
string optional

Responses

201 Created
Body
User object schema
409 Conflict
Body
Object
error
string
Get user
GET /users/{USER_ID}

Path variables

USER_ID
string required

Responses

200 OK
Body
User object schema
Get user roles
GET /users/{user_id}/roles

Path variables

user_id
string required

Responses

200 OK
Body
Object
roles
Array of string
meta
Object
total_count
number
Add roles to user
PATCH /users/{user_id}/roles

Path variables

user_id
string required

Request body

Object

Responses

204 No Content
404 Role not found

In case role is not found in db

409 Conflict

In case user already has this role

Example 1
PATCH https://markup-tool.ringlabskiev.com/api/v1/users/2/roles HTTP/1.1 

Content-Type: application/json

[1]
Remove roles from user
DELETE /users/{user_id}/roles

Path variables

user_id
string required

Request body

Object

Responses

204 No Content

Success

404 Not Found

Role not found in db

Example 1
DELETE https://markup-tool.ringlabskiev.com/api/v1/users/1/roles HTTP/1.1 

Content-Type: application/json

[1,2]
Get user groups
GET /users/{user_id}/groups

Path variables

user_id
string required

Request parameters

page_id
integer optional
page_limit
integer optional

Responses

200 OK
Body
Object
roles
Array
Object
id
number
name
string
meta
Paginate Metadata
Examples
{
    "roles": [
        {
            "id": 1,
            "name": "name_1"
        }
    ],
    "meta": {
        "page_id": 0,
        "page_limit": 1000,
        "total_count": 1
    }
}
Add user to groups
PATCH /users/{user_id}/groups

Path variables

user_id
string required

Request parameters

[<group_id1>, …, <group_idN>]

Responses

204 No Content
Delete user from groups
DELETE /users/{user_id}/groups

Path variables

user_id
string required

Request parameters

[<group_id1>, …, <group_idN>]

Responses

204 No Content
Get groups
GET /groups

Request parameters

page_id
number optional
page_limit
number optional

Responses

200 OK
Body
Object
groups
Array of Group
meta
Paginate Metadata
Examples
{
    "groups": [
        {
            "id": 1,
            "name": "group_1"
        }
    ],
    "meta": {
        "page_id": 0,
        "page_limit": 1,
        "total_count": 1
    }
}
Get group
GET /groups/{group_id}

Path variables

group_id
string required

Responses

200 OK
Body
Group
404 Not Found
Get all users in specific group
GET /groups/{group_id}/users

Path variables

group_id
string required

Request parameters

page_id
number optional
page_limit
number optional

Responses

200 OK
Body
Object
users
Object
id
number
name
string
meta
Object
page_id
number
page_limit
number
total_count
number
Add group
POST /groups

Request body

Object
name
string
Example:
group_name

Responses

201 Created
Body
Object
id
integer
name
string
Example:
group_name
409 Conflict
Example 1
Example 2
POST https://markup-tool.ringlabskiev.com/api/v1/groups HTTP/1.1 

Content-Type: application/json

{
    "name": "group_name"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": 1,
    "name": "group_name"
}
POST https://markup-tool.ringlabskiev.com/api/v1/groups HTTP/1.1 

Content-Type: application/json

{
    "name": "group_name duplicate"
}

HTTP/1.1 409 Conflict
Delete user
DELETE /users/{USER_ID}

Path variables

USER_ID
string required

Responses

204 No Content
404 Not Found
Example 1
DELETE https://markup-tool.ringlabskiev.com/api/v1/users/1 HTTP/1.1 

HTTP/1.1 204 No Content
Paginate Metadata
Object
Example: 
{
    "page_id": 0,
    "page_limit": 1000,
    "total_count": 1
}
page_id
number
page_limit
number
total_count
number
Layers

Endpoint to manage Markup Layers

Get all markup layers
GET /layers
Get markup layer
GET /layers/{LAYER_ID}
Create markup layer
POST /layers
Delete markup layer
DELETE /layers/{LAYER_ID}
Get all markup layers
GET /layers

Get all markup layers

Responses

200 OK
Body
Object
layers
Array
Object
id
integer
Example:
1
name
string
Example:
person
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/api/v1/layers HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "layers": [
        {
            "id": 1,
            "name": "person"
        },
        {
            "id": 2,
            "name": "animal"
        }
    ]
}
Get markup layer
GET /layers/{LAYER_ID}

Get markup layer by id

Path variables

LAYER_ID
integer required

Responses

200 OK
Body
Object
layer
Object
id
integer
Example:
1
name
string
Example:
person
404 Not Found
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/layers/1 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "layer": {
        "id": 1,
        "name": "person"
    }
}
Create markup layer
POST /layers

Create markup layer

Request body

Object
name
string
Example:
vehicle

Responses

201 Created
Body
Object
layer
Object
id
integer
Example:
1
name
string
Example:
vehicle
Example 1
POST https://markup-tool.ringlabskiev.com/api/v1/layers HTTP/1.1 

Content-Type: application/json

{
    "name": "vehicle"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "layer": {
        "id": 1,
        "name": "vehicle"
    }
}
Delete markup layer
DELETE /layers/{LAYER_ID}

Delete markup layer

Path variables

LAYER_ID
integer required

Responses

204 No Content
404 Not Found
Example 1
DELETE https://markup-tool.ringlabskiev.com/api/v1/layer/1 HTTP/1.1 

HTTP/1.1 204 No Content
User Notifications
Get User Notifications
GET /me/notifications
Delete Notification
DELETE /me/notifications/{NOTIFICATION_ID}
Get User Notifications
GET /me/notifications

Responses

200 OK
Body
Object
notifications
Array
Object
notification_id
string
Example:
345345
message
string
Example:
to_much_errors
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/me/notifications HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "notifications": [
        {
            "notification_id": "345345",
            "message": "to_much_errors"
        }
    ]
}
Delete Notification
DELETE /me/notifications/{NOTIFICATION_ID}

Path variables

NOTIFICATION_ID
string required
Example:
2333

Responses

204 No Content
404 Not Found
v1
DELETE https://markup-tool.ringlabskiev.com/api/v1/me/notifications/2333 HTTP/1.1 

HTTP/1.1 204 No Content
Roles
Get all roles
GET /roles
Get role
GET /roles/{ROLE_ID}
Add role
POST /roles
Delete markup role
DELETE /roles/{ROLE_ID}
Get all permission for markup role
GET /roles/{ROLE_ID}/permissions
Add permission to a role
PATCH /roles/{ROLE_ID}/permissions
Remove permission from a role
DELETE /roles/{ROLE_ID}/permissions
Get all roles
GET /roles

Get all markup roles

Responses

200 OK
Body
Object
roles
Array
Object
id
integer
Example:
1
name
string
Example:
Operator
description
string
Example:
Operator
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/roles HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "roles": [
        {
            "id": 1,
            "name": "Operator",
            "description": "Operator"
        },
        {
            "id": 2,
            "name": "Admin",
            "description": "Admin"
        }
    ]
}
Get role
GET /roles/{ROLE_ID}

Path variables

ROLE_ID
integer required

role id

Responses

200 OK
Body
Object
role
Object
id
integer
Example:
1
name
string
Example:
Admin
description
string
Example:
Admin
404 Role Not Found in db
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/role/1 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "role": {
        "id": 1,
        "name": "Admin",
        "description": "Admin"
    }
}
Add role
POST /roles

Request body

Object
name
string
Example:
Dataset Manager
description
string
Example:
Role for dataset management

Responses

201 Created
Body
Object
role
Object
id
integer
Example:
3
name
string
Example:
Dataset Manager
description
string
Example:
Role for dataset management
Example 1
POST https://markup-tool.ringlabskiev.com/api/v1/roles HTTP/1.1 

Content-Type: application/json

{
    "name": "Dataset Manager",
    "description": "Role for dataset management"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "role": {
        "id": 3,
        "name": "Dataset Manager",
        "description": "Role for dataset management"
    }
}
Delete markup role
DELETE /roles/{ROLE_ID}

Path variables

ROLE_ID
string required

role id

Responses

204 No Content
404 Role Not Found
Example 1
DELETE https://markup-tool.ringlabskiev.com/api/v1/roles/3 HTTP/1.1 

HTTP/1.1 204 No Content
Get all permission for markup role
GET /roles/{ROLE_ID}/permissions

Path variables

ROLE_ID
string required

role id

Responses

200 OK
Body
Object
permissions
Array
Example: 
["BasicUserAccess","ImageRead","UserRead"]
string
Example:
BasicUserAccess
404 Role Not Found
Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/roles/5/permissions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "permissions": [
        "BasicUserAccess"
    ]
}
Add permission to a role
PATCH /roles/{ROLE_ID}/permissions

Path variables

ROLE_ID
string required

Request body

Object
permissions
Array
Example: 
["ImageEdit","UserEdit","LayerRead"]
string
Example:
ImageEdit

Responses

204 No Content
Body
Object
Example 1
PATCH https://markup-tool.ringlabskiev.com/api/v1/roles/{ROLE_ID}/permissions HTTP/1.1 

Content-Type: application/json

{
    "permissions": [
        "ImageEdit",
        "RoleEdit"
    ]
}

HTTP/1.1 204 No Content 

Content-Type: application/json

{}
Remove permission from a role
DELETE /roles/{ROLE_ID}/permissions

Path variables

ROLE_ID
string required

role id

Request body

Object
permissions
Array
Example: 
["ImageEdit","UserEdit"]
string
Example:
ImageEdit

Responses

204 No Content
Example 1
DELETE https://markup-tool.ringlabskiev.com/api/v1/roles/3/permissions HTTP/1.1 

Content-Type: application/json

{
    "permissions": [
        "ImageEdit"
    ]
}

HTTP/1.1 204 No Content
Statistics
Get Task Statistics
GET /statistics
Get Task Statistics
GET /statistics

Request parameters

start_date
string optional

start date ISO String

Example:
2018-10-03
end_date
string optional

end date ISO string

Example:
2018-10-04
task_id
number optional

Task uniq indentifier

Example:
1

Responses

200 OK
Body
Object
users
Array
Object
id
integer
Example:
1
email
string
Example:
ievgeniia.taranenko@ring.com
name
string
Example:
User Name
statistics
Object
annotation_time
integer

Spent time in seconds

Example:
1
marked_pictures
integer
Example:
200
speed
integer
Example:
1200
mistakes
integer
Example:
35
meta
Object
overall_spent
integer
overall_marked
integer
overall_mistakes
integer
avarage_speed
integer
400 Bad request

Start date is later then end date

Example 1
GET https://markup-tool.ringlabskiev.com/api/v1/statistics?start_date=2018-10-03T12:03:52.631Z&end_date=2018-10-03T12:03:52.631Z&task_id=1 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "users": [
        {
            "id": 1,
            "email": "ievgeniia.taranenko@ring.com",
            "name": "User Name",
            "statistics": {
                "annotation_time": 1,
                "marked_pictures": 200,
                "speed": 1200,
                "mistakes": 35
            }
        }
    ],
    "meta": {
        "overall_spent": 200,
        "overall_marked": 5000,
        "overall_mistakes": 120,
        "avarage_speed": 800
    }
}