## Overview
<p align="justify">
This endpoint lets users create a new visulaization over an AOI using specified index and assets. It requires a JSON request body with fields like `aoi_id`, `index_id`, and `src_asset_id`. Once created, the API returns the visualization object with a **201 Created** status. **API key authentication is mandatory**. Errors for invalid input or duplication are returned with appropriate codes and messages.

- Method: `POST`

- URL: `/v0/aois/{aoi_id}/visualizations`

- Operation: Create a new visualization oven an AOI

- Authentication Required: Yes

</p>

## Authorization
<p align="justify">
You need the **api key** which you can get from the **API** tab in **Organization Settings**. The api key is required in almost all the commands

```json
Authorization: <YOUR_API_KEY>
```
</p>

## Body
<p align="justify">
You need the following fields in **Body :**

| Field               | Type               | Required | Description |
|---------------------|--------------------|----------|-------------|
| `index_id`          | `string`           | ✅       | ID of the Index to be visualized |
| `src_asset_id`      | `array of string`  | ✅       | ID of the assets of AOI to be included in visualization |

Here is a sample of the Body:

```json body
{
  "index_id": "<string>",
  "src_asset_ids": [
    "<string>",
    "<string>"
  ]
}
```

</p>

## Path Parameters
<p align="justify">
This endpoint require `aoi_id` as the only path parameter.

| Name         | Type     | Required | Description                     |
|--------------|----------|----------|---------------------------------|
| `aoi_id`     | `string` | Yes      | Unique ID of the AOI            |
</p>

## Response
<p align="justify">
The response for this endpoint confirms successful visualization creation with a `201 Created` status. It returns detailed information about the visualization, including its ID, area, bands, expression, geometry, and timestamps. If there's an error, such as missing fields or duplication, a structured error message with relevant status code is returned.

Please refer to the table below for explaination of the fields in the response:

| Name              | Type       | Description                                                                  |
|-------------------|------------|------------------------------------------------------------------------------|
| `aoi_id`          | `array of string`| Unique ID of the AOI                         |
| `created_at`      | `string`     | Timestamp when the visualization was created (ISO 8601 format)                   |
| `expression`      | `string`     | Mathematical expression applied using the selected bands                   |
| `expression_type` | `string`     | Type of the expression (e.g., "index", "formula")                          |
| `id`              | `string`     | Unique identifier of the visualization                                 |
| `index_id`        | `string`     | Unique ID of the AOI        |
| `index_name`      | `string`     | Human-readable name of the index                                  |
| `progress`        | `string`     | Details of progress in visualization creation                     |
| `rescale`         | `number`     | Min and max range used to normalize or rescale the output values           |
| `status`          | `string`     | Status of the visualization("creating", "success", "failed", "partial_success")    |
| `type`            | `string`     | Type of formula, usually "custom" for user-defined expressions             |
| `updated_at`      | `string`     | Timestamp when the visualization was last updated (ISO 8601 format)              |
| `user_id`         | `string`     | Unique ID of the user      |

Here is a sample **201** response:

```json 201
{
  "aoi_id": "<string>",
  "assets": [
    {
      "aoi_id": "<string>",
      "area_in_sq_m": 0,
      "asset_type": "mosaic",
      "band_list": [
        "<string>",
        "<string>"
      ],
      "centroid": [
        77.55,
        12.95
      ],
      "created_at": "2022-11-14 12:55:49.125928+00:00",
      "date": "2022-11-14",
      "description": "<string>",
      "geometry": {
        "coordinates": [
          [
            [
              123
            ]
          ]
        ],
        "type": "<string>"
      },
      "id": "<string>",
      "name": "<string>",
      "path": "https://storage.account",
      "progress": 0,
      "status": "success",
      "updated_at": "2022-11-14 12:55:49.125928+00:00",
      "visualization_id": "<string>"
    }
  ],
  "created_at": "2022-11-14 12:55:49.125928+00:00",
  "expression": "<string>",
  "expression_type": "index",
  "id": "<string>",
  "index_id": "<string>",
  "index_name": "<string>",
  "progress": 100,
  "rescale": [
    0,
    1
  ],
  "status": "success",
  "tenant_id": "<string>",
  "type": "custom",
  "updated_at": "2022-11-14 12:55:49.125928+00:00",
  "user_id": "<string>"
}
```

For this endpoint, there are 3 error responses that you might recieve. The three error responses include: **400 Bad Request** for missing or invalid fields in the request body, **409 Conflict** when an index with similar properties already exists, and **500 Internal Server Error** for unexpected server-side failures. Each returns a structured JSON error with a code, message, and optional details.

```json 400 409 500
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}
```
</p>

## How to use the endpoint
<p align="justify">

1. **Construct your Request:**  
    Create a JSON object with fields like `aoi_id`, `index_id`, and `src_asset_id`. Make sure all fields are filled correctly as required.

2. **Send the Request:**  
    Include the JSON body and path parameter in the headers and make a POST request to `https://api.pixxel.space/v0/aois/{aoi_id}/visualizations`.

3. **Examine the Response:**  
    If successful, the API returns a 201 Created response with the full visualization object, including ID, expression, associated bands, and timestamps. If something is wrong (missing fields, duplicate assets, etc.), you’ll receive a structured error message with a relevant status code.
</p>