## Overview
<p align="justify">
This endpoint allows user to create a download request for assets in an AOI. A successful request returns a list of download id and signed url to download the assets. Authentication via API key is mandatory, and errors like 404 or 500 return standard error messages with relevant codes and details.

- Method: `POST`

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

- Operation: Create a download request for assets in an AOI

- Authentication Required: Yes

</p>

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

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

## Path Parameters
<p align="justify">
The `aoi_id` identifies the exact AOI whose assets are to be downloaded.

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

## Response

<p align="justify">
### Successful Response – 200 OK

A **200 OK** response from the **Create a download request for assets in an AOI** endpoint indicates that the request was successful. It returns a download id, signed url and status.

Refer to the table below for the detailed breakdown of each field in the API response:

**AOI Object Fields**

| Field               | Type     | Description |
|---------------------|----------|:-------------:|
| `download_id`       | `string` | Unique identifier for the Download request. |
| `signed_url`        | `string` | URL to download the requested asset |
| `status`            | `string` | Current status of the download request (e.g., `"success"`). |


Below is the complete JSON request for listing assets for an AOI using the **List Assets for an AOI** endpoint. Customize the values as needed for your search criteria:

``` json 200
{
  "download_id": "<string>",
  "signed_url": "https://storage.account/download",
  "status": "SUCCESS"
}
```

- If you recieve a **Not Found** error (**404**) or the **Internal Server Error** (**500**),  you will get the following response: 
``` json 404 500
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}
```
</p>

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


1. **Construct your Request:**  
    Add your API key to the `Authorization` header and add the path parameter.

2. **Send the Request:**  
    Include the json body with correct path parameter and send the request to: https://api.pixxel.space/v0/aois/{aoi_id}/downloads.

3. **Examine the Response:**  
    A successful response (`200 OK`) returns a `signed_url` which should be used to download the asset.
    In case of failure (404, 500), structured error messages with `code`, `message`, and `details` will be returned.
</p>