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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.imerit.net/api/docs/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.