Overview

The Ango Hub API v2 provides comprehensive programmatic access to manage annotation projects, tasks, assets, workflows, and integrations. This REST API enables you to build custom automation, integrate with existing systems, and scale your annotation operations.

Base URL

EU Server

https://imeritapi.ango.ai/v2

US Server

India Server

Test Server

Authentication

All API endpoints require authentication using an API key. You can generate your API key from your Ango Hub dashboard under Account → API.

How to Authenticate

Include your API key in the request header:

apikey: YOUR_API_KEY_HERE

Example Request

curl -X GET "https://imeritapi.ango.ai/v2/listProjects" \
  -H "apikey: your_actual_api_key_here" \
  -H "Content-Type: application/json"

Security Best Practices

• ⚠️ Never expose your API key in client-side code or public repositories

• 🔄 Rotate your API keys regularly (every 90 days recommended)

Pagination & Sorting

All list endpoints (e.g., /listProjects, /project/{projectId}/tasks) support pagination and sorting to efficiently handle large datasets.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number to retrieve (1-indexed)
limit	integer	10	Number of items per page (max: 100)
sort	string	-createdAt	Field to sort by. Prefix with - for descending order

Sorting Examples

# Get newest projects first (default)
GET /listProjects?sort=-createdAt

# Get oldest projects first
GET /listProjects?sort=createdAt

# Sort alphabetically by name
GET /listProjects?sort=name

# Sort by name descending (Z to A)
GET /listProjects?sort=-name

Pagination Examples

# Get first page with 10 items
GET /listProjects?page=1&limit=10

# Get second page with 50 items
GET /listProjects?page=2&limit=50

# Get all projects (up to 100 per page)
GET /listProjects?limit=100

Error Handling

The API uses standard HTTP status codes and returns consistent error responses.

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Error Response Format

{
  "status": "fail",
  "message": "Validation error - project name is required",
  "errors": [
    {
      "field": "name",
      "message": "Name is required"
    }
  ]
}

Rate Limiting

API requests are rate-limited to ensure fair usage and system stability.

Default Limits

• Standard plan: 100 requests per minute

• Professional plan: 500 requests per minute

• Enterprise plan: Custom limits available

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff when receiving 429 responses.

Request & Response Format

Content Type

Most requests use JSON format:

Content-Type: application/json

File upload endpoints (e.g., /project/{projectId}/instructions, /project/{projectId}/chat) use:

Content-Type: multipart/form-data

Standard Response Structure

Success Response:

{
  "status": "success",
  "data": {
    // Response data here
  }
}

Error Response:

{
  "status": "fail",
  "message": "Error description"
}

Common Use Cases

1. Automated Asset Import

POST /project/{projectId}/cloud
{
  "assets": [
    {"data": "https://example.com/image1.jpg", "externalId": "img-001"},
    {"data": "https://example.com/image2.jpg", "externalId": "img-002"}
  ]
}

2. Batch Task Assignment

POST /task/assign
{
  "project": "project_id",
  "tasks": ["task1", "task2"],
  "user": "[email protected]",
  "stage": "Label"
}

3. Export Completed Annotations

GET /export?project=project_id&status=Completed&format=json

Best Practices

Batch Operations

Use batch endpoints instead of individual requests:

✅ Good: Import 100 assets in one request ❌ Bad: Make 100 separate requests

Implement Retry Logic

Handle transient errors with exponential backoff for 429 and 5xx responses.