API Documentation (Deprecated)
Prerequisite: determine your base URL
Before using our API, please first detect and understand what base URL to use.
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
apikey*
String
Your API key.
Content-Type*
String
Response content type. Must be application/json
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
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
apikey*
String
Your API key.
Content-Type*
String
Response content type. Must be application/json
Request Body
project
String
Project ID where the assets to pre-label are located.
Asset Management
Get Project Assets
GET {baseUrl}/v2/project/{project_id}/assets
Get list of assets in a project.
Path Parameters
project_id
String
ID of the project.
Query Parameters
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
Content-Type*
String
Response content type. Must be application/json
apikey*
String
Your API key.
{
"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
project_id
String
Headers
Content-Type*
String
Response content type. Must be application/json
apikey*
String
Your API key.
Request Body
assets*
Array
Array of objects each containing two key-value pairs: "data":"URL"and "externalId":"ID". See example above.
{
"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
apikey*
String
Your API key.
Request Body
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
project_id
String
ID of the project.
Headers
apikey*
String
Your API key.
Content-Type*
String
Response content type. Must be application/json
Create batch in project
POST {baseUrl}/v2/batches/{project_id}
Create new batch in project.
Body:
{
"batches": "string"
}
Path Parameters
project_id*
String
ID of the project where the batch is to be created.
Headers
apikey*
String
Your API key.
Content-Type*
String
Response content type. Must be application/json
Request Body
batches*
String
Name of the batch to create.
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
apikey*
String
Your API key.
Content-Type*
String
Response content type. Must be application/json
Request Body
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).
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
apikey*
String
Your API key.
Request Body
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
apikey*
String
Your API key.
Content-Type*
String
Response content type. Must be application/json
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
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
Content-Type*
String
Response content type. Must be application/json
apikey*
String
Your API key.
{
"status": "success",
"data": {
"projects": [
{
"_id": "123123123123123123123123",
"name": "Project Name",
"description": "Project Description",
"organization": "234234234234234234234234",
"createdAt": "2021-10-14T07:44:46.373Z"
}
],
"total": 1
}
}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
project_id
String
ID of the project to get. (e.g. 652901255342990015e24922)
Headers
Content-Type*
String
Response content type. Must be application/json
apikey*
String
Your API key.
{
"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"
}
}
}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
project_id*
String
ID of the project to get the tasks of.
Query Parameters
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
Content-Type*
String
Response content type. Must be application/json
apikey*
String
Your API key.
{
"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
}
}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
project_id*
String
ID of the project.
metric*
String
Metric to obtain.
Headers
apikey*
String
Your API key.
Content-Type*
String
Response content type. Must be application/json
Create new project
POST {baseUrl}/v2/project
Create new project in organization.
Body:
{
"name": "string"
"description": "string"
}
Headers
apikey*
String
Your API key.
Content-Type*
String
Response content type. Must be application/json
Request Body
name*
String
Name of the new project.
description
String
Description of the new project.
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
Content-Type*
String
Response content type. Must be application/json
apikey
String
Your API key.
Request Body
categorySchema*
Dict
Category schema to pass. See example above. Obtain it from the UI, in the project settings -> Category Schema section.
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
Content-Type*
String
Response content type. Must be application/json
apikey
String
Your API key.
Request Body
toStageId*
String
The id of the stage to be requeued.
filters
Dict
Filter tasks
options
Dict
Options to be applied during requeue
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
task_id
String
ID of the task to get information of.
Headers
Content-Type*
String
Response content type. Must be application/json
apikey*
String
Your API key.
{
"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"
}
}
}Get a task's history
GET {baseUrl}/v2/taskHistory/{id}
Gets the history of a task.
Path Parameters
id*
String
ID of the task.
Headers
apikey*
String
Your API key.
Content-Type*
String
Response content type. Must be application/json
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
apikey*
String
Your API key.
Content-Type*
String
Response content type. Must be application/json
Request Body
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.
{
"status": "success",
"data": {
"assets": "Successfully created."
}
}Last updated