REST API V2

V2 REST API References for Image Annotation (Bounding Box / Segmentation)

API Overview for Image Annotation (Bounding Box / Segmentation)

Verb	Endpoint	Description
GET	/v2/labelfiles	Get the loading status when selecting a label file
GET	/v2/folders	Get the folder status when selecting a project folder
GET	/v2/:annotation_type/projects/:project_name	Get the status of creating a project
GET	/v2/:annotation_type/projects/:project_name/reloadstatus	Get the reload status on refreshing/reloading a project
GET	/v2/:annotation_type/projects/importstatus	Get the status of importing a project configuration file
GET	/v2/:annotation_type/projects/exportstatus	Get the status of exporting a project
GET	/v2/:annotation_type/projects/:project_name/statistic	Get the statistics of a project
GET	/v2/:annotation_type/projects/:project_name/addstatus	Get the add images status of a project
PUT	/:annotation_type/projects/:project_name/star	Toggle the starring status of a project
PUT	/v2/labelfiles	Select a label text file
PUT	/v2/folders	Select a project folder
PUT	/v2/projects	Create a new project with preferred options
PUT	/v2/:annotation_type/projects/:project_name/reload	Reload/refresh a project by rechecking through the project folder
PUT	/v2/:annotation_type/projects/:project_name/export/:export_type	Start export process of a project.
PUT	/v2/:annotation_type/projects/:projectname/rename/:new_project_name	Rename an existing project to a new unique project name
PUT	/:annotation_type/projects/:project_name	Close a project
PUT	/v2/:annotation_type/projects/:project_name/imgsrc/rename	Rename project data
PUT	v2/:annotation_type/projects/:project_name/add	Add images to a project
DELETE	/v2/:annotation_type/projects/:project_name/uuids	Delete project data

:annotation_type accepts the following parameter

• bndbox

  • Example: /bndbox/projects/helloworld

• seg .

  • Example: /seg/projects/helloworld

for the corresponding image annotation techniques.

API Detailed Walkthrough

Get the loading status when selecting a label file

GET http://localhost:{port}/v2/labelfiles

Get the loading status when selecting a label file

Path Parameters

Name	Type	Description
	string

200 - message : integer (1 for success) - window_status : integer - window_status = 0 (window open) - window_status = 1(window close) - window_message : string - label_file_path : string (Empty string when label file not selected)

message = 1 (window_status = 0)

{
    "message": 1,
    "window_status": 0,
    "window_message": "WINDOW_OPEN"
}

message = 1 (window_status = 1)

{
    "message": 1,
    "window_status": 1,
    "window_message": "WINDOW_CLOSE",
    "label_file_path": "/Users/johndoe/Downloads/man_label.txt"
}

Get the folder status when selecting a project folder

GET http://localhost:{port}/v2/folders

Get the folder status when selecting a project folder.

Path Parameters

Name	Type	Description
	string

200 - message : integer (1 for success) - window_status : string - window_status = 0 (window open) - window_status = 1 (window close) - window_message : string - project_path : string (Empty string when no project path is selected)

message = 1 (window_status = 0)

{
    "message": 1,
    "window_status": 0,
    "window_message": "WINDOW_OPEN"
}

message = 1 (window_status = 1)

{
    "message": 1,
    "window_status": 1,
    "window_message": "WINDOW_CLOSE",
    "project_path": "/Users/johndoe/Desktop/temp"
}

Get the status of creating a project

GET http://localhost:{port}/v2/:annotation_type/projects/:project_name

Get the status of creating a project.

Path Parameters

Name	Type	Description
project_name*	string	Project name
annotation_tye*	string	Type of annotation

200 - message : integer (1 for success) - file_system_status : integer The category of create project status is displayed with returning integer of file_system_status - file_system_status = 0 (Not initiated) - file_system_status = 1 (Iterating folder) - file_system_status = 2 (Updating database) - file_system_status = 3 (Database updated) - file_system_message : string

message = 1 (file_system_status = 1)

{
    "message": 1,
    "file_system_status": 1,
    "file_system_message": "ITERATING_FOLDER"
}

message = 1 (file_system_status = 2)

{
    "message": 1,
    "file_system_status": 2,
    "file_system_message": "DATABASE_UPDATING"
}

message = 1 (file_system_status = 3)

{
    "message": 1,
    "file_system_status": 3,
    "file_system_message": "DATABASE_UPDATED",
    "unsupported_image_list" : [ "C:\\Users\\yinch\\Pictures\\image_fail_display\\2.jpg"]
}

Get the reload status on refreshing/reloading a project.

GET http://localhost:{port}/v2/:annotation_type/projects/:project_name/reloadstatus

Get the reload status of refreshing/reloading a project.

Path Parameters

Name	Type	Description
project_name*	string	Project name
annotation_type*	string	Type of annotation

200 - message : integer (1 for loading, 4 successfully loaded ) - file_system_status : integer The category of reload status is displayed in the returning integer of file_system_status - file_system_status = 0 (Not initiated) - file_system_status = 1 (Loading and iterating folder) - file_system_status = 2 (Loading and database is updating) - file_system_status = 3 (Loaded and dababase is updated) - file_system_message : string - uuid_add_list : list of string - uuid_delete_list : list of string

message = 1 (file_system_status = 0)

{
    "message": 1,
    "file_system_status": 0,
    "file_system_message": "DID_NOT_INITIATED"
}

message = 1 (file_system_status = 1)

{
    "message": 1,
    "file_system_status": 1,
    "file_system_message": "ITERATING_FOLDER"
}

message = 1 (file_system_status = 2)

{
    "message": 1,
    "file_system_status": 2,
    "file_system_message": "DATABASE_UPDATING"
}

message = 1 (file_system_status = 3)

{
    "message": 1,
    "file_system_status": 3,
    "file_system_message": "DATABASE_UPDATED",
    "uuid_add_list": [
        "7d695dcd-26c9-4da0-8b33-f772ffb1b7eb",
        "5c2cc14a-ac5a-4b7c-a445-df3cc0e6bd98"
    ],
    "uuid_delete_list": [],
    "unsupported_image_list" : [ "C:\\Users\\user\\Pictures\\image_fail_display\\2.jpg"]
}

Get the status of importing a project configuration file

GET http://localhost:{port}/v2/:annotation_type/projects/importstatus

Check the status of importing a project configuration file.

Path Parameters

Name	Type	Description
annotation_type*	string	Type of annotation

200 - message : integer (0 for import window open/import in progress, 1 for success) - file_system_status : integer The category of import status is displayed in the returning integer of file_system_status - file_system_status = 0 (Did not initiated) - file_system_status = 1 (Iterating folder) - file_system_status = 2 (Updating database) - file_system_status = 3 (Database updated) - file_system_status = 4 (Files is successfully imported) - file_system_status = 5 (Process is aborted) - file_system_message : string - error_message : string

message = 0

{
    "message": 0,
    "error_message": ""
}

message = 1 (file_system_status = 0)

{
    "message": 1,
    "file_system_status": 0,
    "file_system_message": "DID_NOT_INITIATED"
}

message = 1 (file_system_status = 1)

{
    "message": 1,
    "file_system_status": 1,
    "file_system_message": "ITERATING_FOLDER"
}

message = 1 (file_system_status = 2)

{
    "message": 1,
    "file_system_status": 2,
    "file_system_message": "DATABASE_UPDATING"
}

message = 1 (file_system_status = 3)

{
    "message": 1,
    "file_system_status": 3,
    "file_system_message": "DATABASE_UPDATED"
    "project_name": "awesome_wonderwoman"
}

message = 4 (success)

{
  "message" : 4,
  "error_message" : "\nName Overlapped. Rename as cute_thor.\nImport project success."
}

message = 5 (failure)

{
    "message": 1,
    "file_system_status": 5,
    "file_system_message": "ABORTED"
}

Get the status of exporting a project

GET http://localhost:{port}/v2/:annotation_type/projects/exportstatus

To check the export status of a project. Should be called after calling export api

Path Parameters

Name	Type	Description
annotation_type*	string	Type of annotation

200 - message: integer (1 for success, 0 for failure) - export_status: integer(0 for Export not initiated, 1 for Export Starting, 2 for Export Success, 3 for Export fail) - export_status_message: string("EXPORT_NOT_INITIATED", "EXPORT_STARTING", "EXPORT_SUCCESS", "EXPORT_FAIL") When EXPORT_SUCCESS, api will return result of exported project path - project_config_path: "path/to/config/file"

EXPORT_NOT_INITIATED

{
    "message": 1,
    "export_status": 0,
    "export_status_message": "EXPORT_NOT_INITIATED"
}

EXPORT_STARTING

{
    "message": 1,
    "export_status": 1,
    "export_status_message": "EXPORT_STARTING"
}

EXPORT_SUCCESS

{
    "message": 1,
    "export_status": 2,
    "export_status_message": "EXPORT_SUCCESS",
    "project_config_path": "path/to/config/file"
}

EXPORT_FAIL

{
    "message": 1,
    "export_status": 3,
    "export_status_message": "EXPORT_FAIL"
}

Get the statistics of a project

GET http://localhost:{port}/v2/:annotation_type/projects/:project_name/statistic

To get the number of labeled images, the number of unlabeled images, and the number of labels per class in a project

Path Parameters

Name	Type	Description
project_name*	string	Name of project
annotation_type*	string	Type of annotation

200 - message: integer (1 for success, 0 for failure), error_message: string

success

{
    "message":1,
    "labeled_image":1,
    "unlabeled_image":23,
    "label_per_class_in_project":[
        {"label":"lorry","count":0},
        {"label":"bus","count":0},
        {"label":"van","count":1},
        {"label":"car","count":1},
        {"label":"truck","count":0}
    ]
}

failure

{ 
    "message": 0,
    "error_code": 1,
    "error_message": ""Failed to retrieve statistic for project " + :project_name"
}

Get the add images status of a project

GET http://localhost:{port} /v2/:annotation_type/projects/:project_name/addstatus

To get the status of added images to a project

Path Parameters

Name	Type	Description
annotation_type*	String	Type of annotation
project_name*	String	Project name

200: OK - message: integer (1 for success, 0 for failure)

success

{
    "message" : 1,
    "add_image_status" : 0,
    "add_image_message" : "IMAGE_ADDED"
}

failure

{
    "message" : 0,
    "add_image_status" : 1,
    "add_image_message" : "OPERATION FAILED"
}

Toggle the starring status of a project

PUT http://localhost:{port}/:annotation_type/projects/:project_name/star

Toggle the starring status of a project to be on or off.

Path Parameters

Name	Type	Description
project_name*	string	Project name
annotation_type*	string	Type of annotation

Request Body

Name	Type	Description
status	string	Status of the starring of a project Only accept "true" and "false"

200 - message: integer (1 for success, 0 for failure) if failure occurs, - error_code: integer - error_message: string

success

{
    "message": 1
}

failure (error_code = 1)

{ 
    "message": 0,
    "error_code": 1,
    "error_message": "Starring object value is not boolean. Failed to execute"
}

Select a label text file

PUT http://localhost:{port}/v2/labelfiles

Select and load a label text file.

Path Parameters

Name	Type	Description
	string

200 message : integer (1 for success)

success (message = 1)

{
    "message": 1
}

Select a project folder

PUT http://localhost:{port}/v2/folders

Select a folder for a new project.

Path Parameters

Name	Type	Description
	string

200 - message : integer (1 for success)

success (message = 1)

{
    "message": 1
}

Create a new project

PUT http://localhost:{port}/v2/projects

Create a new project name with preferred options

Request Body

Name	Type	Description
status	string	Options of new project: "raw" for creating project from scratch, "config" for importing project from json file
project_name	string	New project name
annotation_type	string	Type of annotation
project_path	string	Absolute path of a folder with data
label_file_path	string	Absolute path of a label file

200 - message : integer (1 for success, 0 for failure) if failure occur (message = 0) - error_code : integer - error_message : string

success

{
    "message": 1
}

failure (error_code = 1)

{
    "message": 0,
    "error_code": 1,
    "error_message": "Parameter of status with RAW, CONFIG is compulsory in request body"
}

Export project

PUT http://localhost:{port}/v2/:annotation_type/projects/:project_name/export/:export_type

Export project into either a configuration file or zipped file (configuration file with data points). Will only start export process. Get the status of project by calling export status api.

Path Parameters

Name	Type	Description
export_type*	string	Type of export file Parameter : "cfg": for config files only "cfgdata": for config files with data
project_name*	string	Project name
annotation_type*	string	Type of annotation

200 - message : integer (1 for success, 0 for failure) if error occur (message = 0): - error_code : integer - error_message : string

success

{
    "message" : 1,
}

failure (error_code = 1)

{
    "message": 0,
    "error_code": 1,
    "error_message": "Export of project failed for :project_name"
}

Rename an existing project to a new unique project name

PUT http://localhost:{port}/v2/:annotation_type/projects/:project_name/rename/:new_project_name

Rename an existing project to a new unique project name.

Path Parameters

Name	Type	Description
new_project_name*	string	New project name
project_name*	string	Project name
annotation_type*	string	Type of annotation

200 message : integer (1 for success, 0 for failure) if failure occur (message = 0) - error_code : integer - error_message : string

success

{
    "message" : 1
}

failure (error_code = 1)

{
    "message": 0,
    "error_code": 1,
    "error_message": "Failed to rename project :project_name"
}

Close a project

PUT http://localhost:{port}/projects/:project_name

Indicate the closing state of a project.

Path Parameters

Name	Type	Description
project_name*	string	Project name

Request Body

Name	Type	Description
status	string	State of the project as "closed" Example: { "status": "closed"}

200 - message: integer (1 for success, 0 for failure) if failure occurs, - error_code: integer - error_message: string

success

{
    "message": 1
}

failure (error_code = 1)

{
    "message": 0,
    "error_code": 1,
    "error_message": "Request body not defined: io.vertx.core.json.DecodeException: Failed to decode:No content to map due to end-of-input\n at [Source: (io.netty.buffer.ByteBufInputStream); line: 1, column: 0"
}

failure (error_code = 2)

{
    "message": 0,
    "error_code": 2,
    "error_message": "Request payload failed to satisfied the status of {\"status\": \"closed\"} for :project_name."
}Segmentation Annotation

Rename project data

PUT http://localhost:{port}/v2/:annotation_type/projects/:project_name/imgsrc/rename

Rename data points of a project. Used inside project workspace. API requires a json body.

Path Parameters

Name	Type	Description
project_name*	string	Name of current project to rename data
annotation_type*	string	Type of annotation

Request Body

Name	Type	Description
new_fname	string	New data filename to change
uuid	string	uuid of data

200

Add images to project

PUT http://localhost:{port}/v2/:annotation_type/projects/:project_name/add

Add selected images from source folder to project folder

Path Parameters

Name	Type	Description
annotation_type*	String	Type of annotation
project_name*	String	Project name

200: OK message: integer (1 for success, 0 for failure)if failure occurs, - error_code: integer- error_message: string

success

{
    "message" : 1
}

failure

{
    "message" : 0,
    "error_code" : 1,
    "error_message" : "Project not exist"
}

Delete project data

DELETE http://localhost:{port}/v2/:annotation_type/projects/:project_name/uuids

Deleting data from project. Will modify the data points in the root folder. When performing deletion, data is placed in a deleted folder.

Path Parameters

Name	Type	Description
project_name*	string	Name of current project
annotation_type*	string	Type of annotation

Request Body

Name	Type	Description
img_path_list	array	Array of strings of data path.
uuid_list	array	Array of strings of uuid of data. Does not support multiple delete for now.

200 Return success message code 1 and array of uuids that is still available for the project

// For success process
{
  "message" : 1,
  "uuid_list" : [ "4930331f-46b0-429e-8e02-9c03660261b1", "7fa70a42-ce16-4dfe-a880-f5d7e0ac5232", "dc584803-caad-407c-89c0-48e633b306f4", "404d61b5-6a39-49d1-8975-d02bca7f1b0f", "64389e29-8c17-47e6-b28a-ebbf4e902e23", "b0f25f5f-c922-4c2b-b418-84ed351c0d94" ]
}

// For failed process
{
  "message" : 0,
  "error_code" : 1, // For user defined error
  "error_message": "Message to explain error"
}