> For the complete documentation index, see [llms.txt](https://docs.imerit.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.imerit.net/api/docs/overview.md).

# 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**

{% tabs %}
{% tab title="EU Server" %}

```
https://imeritapi.ango.ai/v2
```

{% endtab %}

{% tab title="US Server" %}

```
https://us-api.ango.ai/v2
```

{% endtab %}

{% tab title="India Server" %}

```
https://in-api.ango.ai/v2
```

{% endtab %}

{% tab title="Test Server" %}

```
https://testapi.ango.ai/v2
```

{% endtab %}
{% endtabs %}

## 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:

```http
apikey: YOUR_API_KEY_HERE
```

**Example Request**

```bash
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**

```http
# 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**

```http
# 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**

```bash
{
  "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:

```http
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.<br>

## Request & Response Format

**Content Type**

Most requests use JSON format:

```http
Content-Type: application/json
```

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

```http
Content-Type: multipart/form-data
```

#### Standard Response Structure

**Success Response:**

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

**Error Response:**

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

## Common Use Cases

**1. Automated Asset Import**

```http
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**

```http
POST /task/assign
{
  "project": "project_id",
  "tasks": ["task1", "task2"],
  "user": "annotator@example.com",
  "stage": "Label"
}
```

**3. Export Completed Annotations**

```http
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.