API Documentation (Deprecated)

Prerequisite: determine your base URL

Before using our API, please first detect and understand what base URL to use.

Deployment	Base URL
Cloud EU instance (Default)	https://imeritapi.ango.ai (alternatively, https://eu-api.ango.ai)
Cloud US instance	https://us-api.ango.ai
Cloud India Instance	https://in-api.ango.ai

List of API Methods

Annotations

Get export from project

GET {baseUrl}/v2/exportV3

Obtain export from project.

Headers

Name	Type	Description
apikey*	String	Your API key.
Content-Type*	String	Response content type. Must be application/json

200: OK Successful operation.

Upload annotations for a single task

GET {baseUrl}/v2/annotate/{task_id}

Update the annotation content of a task regardless of the task's current stage.

Headers

Name	Type	Description
apikey*	String	Your API key.
Content-Type*	String	Response content type. Must be application/json

Then include the annotation content for the task in the raw data section of the request as per the sample request below. Read more about Ango's import format here.

Sample request

curl --location 'https://testapi.ango.ai/v2/annotate/664c8fda7368030015077b74' --header 'apikey: 1234567890' --header 'Content-Type: application/json' --data '{"answer":{"objects":[{"title":"Vehicle","bounding-box":{"width":120.005,"height":135.345,"x":50.3,"y":30.4}}],"classifications":[],"relations":[]},"duration":0}'

Upload pre-labels in bulk

POST {baseUrl}/v2/import/labels

Obtain export from project.

Body:

{ "project": "<PROJECT_ID>", "jsonContent": "string" }

For the contents of jsonContent, please refer to the documentation of the related SDK function. Please note that the assets you are trying to pre-annotate must be located in the project's Start stage. Read more about the Start stage here.

Headers

Name	Type	Description
apikey*	String	Your API key.
Content-Type*	String	Response content type. Must be application/json

Request Body

Name	Type	Description
project	String	Project ID where the assets to pre-label are located.
jsonContent	String	Pre-labels. Please refer to the documentation of the related SDK function.

200: OK Successful operation.

Asset Management

Get Project Assets

GET {baseUrl}/v2/project/{project_id}/assets

Get list of assets in a project.

Path Parameters

Name	Type	Description
project_id	String	ID of the project.

Query Parameters

Name	Type	Description
page	String	Assets are paginated. Page number to obtain. Defaults to the first page.
limit	String	Assets per page. Min/default: 10, max: 1000.

Headers

Name	Type	Description
Content-Type*	String	Response content type. Must be application/json
apikey*	String	Your API key.

200: OK Success

{
    "status": "success",
    "data": {
        "assets": "Successfully created."
    }
}

Upload Assets from Storage

POST {baseUrl}/v2/project/{project_id}/cloud

Uploads files from cloud storage to a specified Ango Hub project as assets.

Example request:

curl --location --request POST 'https://imeritapi.ango.ai/v2/project/61602b346ee9eb45e8273fbb/cloud' --header 'Content-Type: application/json' --header 'apikey: YOUR-API-KEY-HERE' --data-raw '{ "assets": [ { "data": "https://bucket-name.s3.us-east-2.amazonaws.com/1605167545820-0b395d1ef7df81b7558f87eb47a59dda4dbe19bd.jpg", "externalId": "111" }, { "data": "https://bucket-name.s3.us-east-2.amazonaws.com/1605167545822-0b0b60d298c4afebed824d8ee2f793676c7835bf.jpg", "externalId": "113" } ] }'

Path Parameters

Name	Type	Description
project_id	String

Headers

Name	Type	Description
Content-Type*	String	Response content type. Must be application/json
apikey*	String	Your API key.

Request Body

Name	Type	Description
assets*	Array	Array of objects each containing two key-value pairs: "data":"URL"and "externalId":"ID". See example above.

200: OK Success

{
    "status": "success",
    "data": {
        "assets": "Successfully created."
    }
}

Attachments

Create Attachment

POST {baseUrl}/v2/attachments

Adds an attachment to an existing labeling task.

Example request:

curl --location --request POST 'https://imeritapi.ango.ai/v2/attachments' --header 'apikey: YOUR-API-KEY-HERE' --data-raw '{ "project": "61d444045e299635ed689056", "attachments": [ { "data": "https://angohub-public-assets.s3.eu-central-1.amazonaws.com/uploaded-data-0a0988b2-d6ca-420e-97e6-577b96417989.png", "externalId": "uploaded-data-65dfb652-d7c8-4fa5-b6d5-de6bfe2a4365.png", "attachments": [ { "type": "IMAGE", "value": "https://sample-image.jpg" }, { "type": "VIDEO", "value": "http://sample-video.mp4" }, { "type": "TEXT", "value": "Some sample text" } ] } ] }'

Headers

Name	Type	Description
apikey*	String	Your API key.

Request Body

Name	Type	Description
project*	String	ID of the project where the attachment is to be created. Found at the end of the project URL.
attachments*	Array	Array of objects describing task/attachment pairs. See example.
data*	String	URL to the asset where the attachment is to be added.
externalId*	String	External ID of the asset. Found in the project under the Assets tab.
type*	String	Attachment data type. Available types are IMAGE, VIDEO, and TEXT. Supported IMAGE file types are .png and .jpg. The supported video type is .mp4, and the supported text type is .txt.
value*	String	In case the type is TEXT, the content of the attachment in plain text. In case the type is IMAGE or VIDEO, a URL linking to the image or video.

Batches

Get batches of project

GET {baseUrl}/v2/batches/{project_id}

Obtain list of batches existing within a project.

Path Parameters

Name	Type	Description
project_id	String	ID of the project.

Headers

Name	Type	Description
apikey*	String	Your API key.
Content-Type*	String	Response content type. Must be application/json

200: OK Successful operation.

Create batch in project

POST {baseUrl}/v2/batches/{project_id}

Create new batch in project.

Body:

{ "batches": "string" }

Path Parameters

Name	Type	Description
project_id*	String	ID of the project where the batch is to be created.

Headers

Name	Type	Description
apikey*	String	Your API key.
Content-Type*	String	Response content type. Must be application/json

Request Body

Name	Type	Description
batches*	String	Name of the batch to create.

200: OK Successful operation.

Assign assets to batch

POST {baseUrl}/v2/assignBatches

Create new batch in project.

Body:

{ "assets": ["<ASSET_ID1>", "<ASSET_ID2>"] "batches": ["<BATCH_ID_1>", "<BATCH_ID_2>"] }

Headers

Name	Type	Description
apikey*	String	Your API key.
Content-Type*	String	Response content type. Must be application/json

Request Body

Name	Type	Description
batches*	String or [String]	Name(s) of the batch(es) to assign the asset(s) to.
assets	String or [String]	ID(s) of the asset(s) to assign to the batch(es).

200: OK Successful operation.

Issues

Create Issue

POST {baseUrl}/v2/issues

Creates an issue. If a position parameter is sent, the issue will be created at the position requested (on single images, multi-page TIFFs, video, and text only.)

Example request:

curl --location --request POST 'https://imeritapi.ango.ai/v2/issues' --header 'apikey: YOUR-API-KEY-HERE' --data-raw '{ "content":"Issue Text Here", "labelTask": "6143498454e17400149964d1", "position": "[50,120]" }'

Headers

Name	Type	Description
apikey*	String	Your API key.

Request Body

Name	Type	Description
content*	String	Issue text
labelTask*	String	ID of the label task where the issue is to be created.
position	String	For images: stringified array with the X and Y position where the issue is to be created on the asset. Example: "[50, 120]" For text: stringified index of the character in the text where the issue will be created. Example: "54".
page	Int	For multi-page TIFFs and videos, the zero-indexed page/frame number where the issue is to be displayed.

Organization Management

Get Organization Storages

GET {baseUrl}.ai/v2/storages

Obtain list of connected storages in the organization.

Headers

Name	Type	Description
apikey*	String	Your API key.
Content-Type*	String	Response content type. Must be application/json

200: OK Successful operation.

Project Management

List All Projects

GET {baseUrl}/v2/listProjects

Returns a list of all projects visible to the user.

Example request:

curl --location --request GET 'https://imeritapi.ango.ai/v2/listProjects' --header 'Content-Type: application/json' --header 'apikey: YOUR-API-KEY-HERE'

Query Parameters

Name	Type	Description
page	String	Projects are paginated. This parameter is the page number. Will get the first page by default.
limit	String	Number of projects per page (default 10, max 1000).

Headers

Name	Type	Description
Content-Type*	String	Response content type. Must be application/json
apikey*	String	Your API key.

200: OK Success

{
    "status": "success",
    "data": {
        "projects": [
            {
                "_id": "123123123123123123123123",
                "name": "Project Name",
                "description": "Project Description",
                "organization": "234234234234234234234234",
                "createdAt": "2021-10-14T07:44:46.373Z"
            }
        ],
        "total": 1
    }
}

401: Unauthorized Invalid API key

Get Project Information

GET {baseUrl}/v2/project/{project_id}

Returns information about a project, including labeling tools, consensus count, assigned users, review configuration, and name and description.

Example request:

curl --location --request GET 'https://imeritapi.ango.ai/v2/project/61602b346ee9eb45e8273fbb' --header 'Content-Type: application/json' --header 'apikey: YOUR-API-KEY-HERE'

Path Parameters

Name	Type	Description
project_id	String	ID of the project to get. (e.g. 652901255342990015e24922)

Headers

Name	Type	Description
Content-Type*	String	Response content type. Must be application/json
apikey*	String	Your API key.

200: OK Success

{
    "status": "success",
    "data": {
        "project": {
            "categorySchema": {
                "tools": [
                    {
                        "title": "Vehicle",
                        "tool": "bounding-box",
                        "required": false,
                        "schemaId": "4b8ac18a570747f87b27025",
                        "columnField": false,
                        "classifications": [
                            {
                                "title": "Type",
                                "tool": "radio",
                                "required": false,
                                "schemaId": "ae40cb11c104045c1a31698",
                                "columnField": false,
                                "options": [
                                    {
                                        "value": "Car",
                                        "schemaId": "27504d2d08f05b9944aa713"
                                    },
                                    {
                                        "value": "Truck",
                                        "schemaId": "c734a046cbee0646886a067"
                                    },
                                    {
                                        "value": "Bus",
                                        "schemaId": "41abb6003990d2aa1ce3605"
                                    },
                                    {
                                        "value": "Other",
                                        "schemaId": "32b3611a68df286fe6eb281"
                                    }
                                ]
                            }
                        ],
                        "color": "#9c27b0",
                        "shortcutKey": "h"
                    }
                ],
                "classifications": [],
                "relations": []
            },
            "consensusCount": 1,
            "deleted": false,
            "reviewConf": {
                "filters": []
            },
            "_id": "6167dfee2a810d000e9d313f",
            "name": "Project Name",
            "description": "Project Description",
            "user": {
                "organizationRole": "admin",
                "deleted": false,
                "_id": "614348d554e17400149964b1",
                "name": "Name Surname",
                "email": "[email protected]",
                "organization": "61435781cdb61b0013d05a03",
                "lastActiveAt": "2021-10-14T09:55:54.814Z",
                "apiKey": "API-KEY-HERE"
            },
            "organization": "61435781cdb61b0013d05a03",
            "createdAt": "2021-10-14T07:44:46.373Z",
            "assignedTo": [],
            "__v": 0,
            "role": "Manager"
        }
    }
}

400: Bad Request Invalid Project

401: Unauthorized Invalid API key

Get Project Tasks

GET {baseUrl}/v2/project/{project_id}/tasks

Returns all tasks in a project, with all of their information, including labeling tools, status, etc.

Example request:

curl --location --request GET 'https://imeritapi.ango.ai/v2/project/615ffd3c455fc7000e6c45eb/tasks' --header 'Content-Type: application/json' --header 'apikey: YOUR-API-KEY-HERE'

Path Parameters

Name	Type	Description
project_id*	String	ID of the project to get the tasks of.

Query Parameters

Name	Type	Description
page	String	Tasks are paginated. Page number of the page of the tasks to obtain. Will get first page by default.
limit	String	Number of tasks per page. Default/minimum: 10, max: 1000.
status[eq]	String	Filter by status. {'Completed', 'TODO'}
batches	String	Filter by batch. Batch ID.
stage	String	Filter by stage. Stage ID.

Headers

Name	Type	Description
Content-Type*	String	Response content type. Must be application/json
apikey*	String	Your API key.

200: OK Success

{
    "status": "success",
    "data": {
        "tasks": [
            {
                "sample": {
                    "isSample": false,
                    "updatedAt": "2021-10-14T08:20:31.259Z"
                },
                "review": {
                    "status": "Todo"
                },
                "answer": {
                    "tools": [
                        {
                            "schemaId": "258f3a07abdb690af46b879",
                            "classifications": [
                                {
                                    "schemaId": "a20942feeaa72bd14d25150",
                                    "answer": "b8135ff7ae3c7ff38347978"
                                },
                                {
                                    "schemaId": "195857feb959465d20c8215",
                                    "answer": "fb19996138864f54eb61839"
                                },
                                {
                                    "schemaId": "c6403fdb451daad92247100",
                                    "answer": "Ocre"
                                }
                            ],
                            "lock": false,
                            "objectId": "014273c35ff83e2e19c9392",
                            "ner": {
                                "start": 10,
                                "end": 15
                            },
                            "metadata": {
                                "createdAt": 1634199730392,
                                "createdBy": "import"
                            }
                        }
                    ],
                    "classifications": [],
                    "relations": []
                },
                "status": "TODO",
                "isBenchmark": false,
                "deleted": false,
                "issues": [],
                "openIssuesCount": 0,
                "isPreLabeled": true,
                "isFlag": false,
                "isStar": false,
                "_id": "6167e84f2a810d000e9d3186",
                "project": "6167dfee2a810d000e9d313f",
                "asset": {
                    "_id": "6167e84f2a810d000e9d3185",
                    "externalId": "text_file.txt",
                    "data": "https://angohub-public-assets.s3.eu-central-1.amazonaws.com/uploaded-data-d187239d-9fc0-4565-983d-50c7b42b258b.txt"
                },
                "organization": "61435781cdb61b0013d05a03",
                "createdAt": "2021-10-14T08:20:31.259Z"
            },
            {
                "sample": {
                    "isSample": false,
                    "updatedAt": "2021-10-14T07:47:23.457Z"
                },
                "review": {
                    "status": "Todo"
                },
                "answer": {
                    "tools": [
                        {
                            "schemaId": "4b8ac18a570747f87b27025",
                            "classifications": [
                                {
                                    "schemaId": "ae40cb11c104045c1a31698",
                                    "answer": "27504d2d08f05b9944aa713"
                                },
                                {
                                    "schemaId": "2ea7c2a0712af78cd9bb827",
                                    "answer": "ca9e9c4c13caa3f11a3d292"
                                },
                                {
                                    "schemaId": "364dc1e2a7ed4d9f57ce731",
                                    "answer": "Ocre"
                                }
                            ],
                            "lock": false,
                            "objectId": "7719679ed20f149af886359",
                            "bounding-box": {
                                "x": 50.3,
                                "y": 30.4,
                                "width": 120.005,
                                "height": 135.345
                            },
                            "metadata": {
                                "createdAt": 1634199268359,
                                "createdBy": "import"
                            }
                        }
                    ],
                    "classifications": [],
                    "relations": []
                },
                "status": "TODO",
                "isBenchmark": false,
                "deleted": false,
                "issues": [],
                "openIssuesCount": 0,
                "isPreLabeled": true,
                "isFlag": false,
                "isStar": false,
                "_id": "6167e08b2a810d000e9d314d",
                "project": "6167dfee2a810d000e9d313f",
                "asset": {
                    "_id": "6167e08b2a810d000e9d314c",
                    "externalId": "test.jpg",
                    "data": "https://angohub-public-assets.s3.amazonaws.com/uploaded-data-15c12f8e-4b46-4d55-8fd4-776455448810.jpg"
                },
                "organization": "61435781cdb61b0013d05a03",
                "createdAt": "2021-10-14T07:47:23.457Z"
            }
        ],
        "total": 2
    }
}

400: Bad Request Invalid Project

401: Unauthorized Invalid API key

Get a metric from a project

GET {baseUrl}/v2/{project_id}/overview/{metric}

Get a specific metric from a project.

The metric can be one of: "LabelStageGroups", "TimePerTask", "AnnotationStatus", "AnswerDistribution", "ConsensusRanges", "AssetSize".

Path Parameters

Name	Type	Description
project_id*	String	ID of the project.
metric*	String	Metric to obtain.

Headers

Name	Type	Description
apikey*	String	Your API key.
Content-Type*	String	Response content type. Must be application/json

200: OK Successful operation.

Create new project

POST {baseUrl}/v2/project

Create new project in organization.

Body:

{ "name": "string" "description": "string" }

Headers

Name	Type	Description
apikey*	String	Your API key.
Content-Type*	String	Response content type. Must be application/json

Request Body

Name	Type	Description
name*	String	Name of the new project.
description	String	Description of the new project.

200: OK Successful operation.

Create Label Set

POST {baseUrl}/v2/project/{project_id}

Sets the project ontology. For the format of the categorySchema object to pass, please create the ontology from the UI, then follow these instructions to copy it to your clipboard.

Example value for the body:

{
  "categorySchema": {
    "tools": [
      {
        "title": "Vehicle",
        "tool": "bounding-box",
        "schemaId": "e94536...",
        ...
      }
],
    "classifications": [classifications],
    "relations": [relations]
  }
}

Headers

Name	Type	Description
Content-Type*	String	Response content type. Must be application/json
apikey	String	Your API key.

Request Body

Name	Type	Description
categorySchema*	Dict	Category schema to pass. See example above. Obtain it from the UI, in the project settings -> Category Schema section.

200: OK Label set created.

Requeue Tasks

POST {baseUrl}i/v2/project/<PROJECT_ID>/requeueTasks

Requeue tasks from one stage to another.

Example value for the body:

{
    "toStageId": "Label2", // toStageId is mandatory
    "filters": { // filters are optional and inclusive
        "taskIds": [],
        "externalIds": ["cute-cat.jpg"],
        "assetIds": [],
        "fromStageIds": []
    },
    "options": { // options are optional with following defaults
        "removeAnnotations": false,
        "removeAssignee": false,
        "removeStageHistory": false
    }
}

Headers

Name	Type	Description
Content-Type*	String	Response content type. Must be application/json
apikey	String	Your API key.

Request Body

Name	Type	Description
toStageId*	String	The id of the stage to be requeued.
filters	Dict	Filter tasks
options	Dict	Options to be applied during requeue

200: OK Label set created.

Tasks

Get Task

GET {baseUrl}/v2/task/{task_id}

Returns all information about a task given the task's ID.

Example request:

curl --location --request GET 'https://imeritapi.ango.ai/v2/task/616433306b763c8c0e922b14' --header 'Content-Type: application/json' --header 'apikey: YOUR-API-KEY-HERE'

Path Parameters

Name	Type	Description
task_id	String	ID of the task to get information of.

Headers

Name	Type	Description
Content-Type*	String	Response content type. Must be application/json
apikey*	String	Your API key.

200: OK Success

{
    "status": "success",
    "data": {
        "task": {
            "sample": {
                "isSample": false,
                "updatedAt": "2021-10-14T07:47:23.457Z"
            },
            "review": {
                "status": "Todo"
            },
            "answer": {
                "tools": [
                    {
                        "schemaId": "4b8ac18a570747f87b27025",
                        "classifications": [
                            {
                                "schemaId": "ae40cb11c104045c1a31698",
                                "answer": "27504d2d08f05b9944aa713"
                            },
                            {
                                "schemaId": "2ea7c2a0712af78cd9bb827",
                                "answer": "ca9e9c4c13caa3f11a3d292"
                            },
                            {
                                "schemaId": "364dc1e2a7ed4d9f57ce731",
                                "answer": "Ocre"
                            }
                        ],
                        "lock": false,
                        "objectId": "7719679ed20f149af886359",
                        "bounding-box": {
                            "x": 50.3,
                            "y": 30.4,
                            "width": 120.005,
                            "height": 135.345
                        },
                        "metadata": {
                            "createdAt": 1634199268359,
                            "createdBy": "import"
                        }
                    },
                    {
                        "schemaId": "4b8ac18a570747f87b27025",
                        "bounding-box": {
                            "x": 179.8469387755102,
                            "y": 311.79138321995464,
                            "height": 123.58276643990929,
                            "width": 112.24489795918367
                        },
                        "objectId": "4e42a539188471304757866",
                        "classifications": [],
                        "metadata": {
                            "createdAt": 1634207308867,
                            "createdBy": "614348d554e17400149964b1"
                        }
                    }
                ],
                "classifications": [],
                "relations": []
            },
            "status": "Completed",
            "isBenchmark": false,
            "deleted": false,
            "issues": [],
            "openIssuesCount": 0,
            "isPreLabeled": true,
            "isFlag": false,
            "isStar": false,
            "_id": "6167e08b2a810d000e9d314d",
            "project": {
                "_id": "6167dfee2a810d000e9d313f"
            },
            "asset": {
                "_id": "6167e08b2a810d000e9d314c",
                "externalId": "test.jpg",
                "data": "https://angohub-public-assets.s3.amazonaws.com/uploaded-data-15c12f8e-4b46-4d55-8fd4-776455448810.jpg"
            },
            "organization": "61435781cdb61b0013d05a03",
            "createdAt": "2021-10-14T07:47:23.457Z",
            "__v": 0,
            "completedAt": "2021-10-14T10:28:30.025Z",
            "completedBy": "614348d554e17400149964b1",
            "duration": 4141,
            "updatedAt": "2021-10-14T10:28:30.025Z",
            "updatedBy": "614348d554e17400149964b1",
            "assignee": "614348d554e17400149964b1"
        }
    }
}

400: Bad Request Invalid Project

401: Unauthorized Invalid API key

Get a task's history

GET {baseUrl}/v2/taskHistory/{id}

Gets the history of a task.

Path Parameters

Name	Type	Description
id*	String	ID of the task.

Headers

Name	Type	Description
apikey*	String	Your API key.
Content-Type*	String	Response content type. Must be application/json

200: OK Successful operation.

Assign Task to User

POST {baseUrl}/v2/task/assign

Assign a task to a specific user.

Sample body:

{ "project": "<project_ID>", "tasks": [ "<TASK_ID>", "<TASK2_ID>" ], "stage": "<STAGE_ID>", "user": "<USER_EMAIL>" }

Headers

Name	Type	Description
apikey*	String	Your API key.
Content-Type*	String	Response content type. Must be application/json

Request Body

Name	Type	Description
project*		ID of the project where the task to assign is located.
tasks*	[ String ]	List of task IDs of the tasks to assign.
stage*	String	Stage ID where the tasks to assign are located.
user	String	E-mail of the user to which the tasks will be assigned.

200: OK Success

{
    "status": "success",
    "data": {
        "assets": "Successfully created."
    }
}