## Overview
<p align="justify">
Use this endpoint to request a downloadable bundle of selected assets (e.g., satellite imagery or processed outputs) generated during an insight run on a specific AOI. Once the request is made, the system prepares the package and returns a signed URL to securely download it. The endpoint expects a list of desired **inputs** and/or **outputs** in the request body. This helps in exporting specific data rather than entire insight results.

- Method: `PUT`

- URL: `/v0/aoi/{aoi_id}/insights/{insight_id}/download`

- Operation: Creates a downloadable package from selected insight assets (inputs and outputs).

- 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 path parameters `aoi_id` and `insight_id` are used to uniquely identify the **Area of Interest** and the insight whose data needs to be packaged for download. These are required to ensure the download operation is targeted to the correct asset set.

| Name        | Type   | Required | Description             |
|-------------|--------|----------|-------------------------|
| `aoi_id`      | `string` | Yes      | ID of the Area of Interest |
| `insight_id`  | `string` | Yes      | ID of the insight to download |

</p>

## Query Parameters
<p align="justify">
This endpoint does not use query parameters.
</p>

## Request Body
<p align="justify">
The body of the request should contain lists of input and output asset identifiers to be included in the download package. This allows the user to customize the contents of the download, fetching only the data they need from a potentially large set of generated or used files.

| Name     | Type      | Required | Description                                  |
|----------|-----------|----------|----------------------------------------------|
| `inputs`   | `string[]`  | No       | List of input asset identifiers to include   |
| `outputs`  | `string[]`  | No       | List of output asset identifiers to include  |

Here is a sample body: 

```json body
{
  "inputs": [
    "<string>"
  ],
  "outputs": [
    "<string>"
  ]
}
```
</p>

## Response
<p align="justify">
A successful request returns a 200 OK status with a JSON object containing the insight ID, download status, and a signed URL. This URL can be used to securely download the selected files. The status field helps track whether the download package is ready.

| Field       | Type   | Description                                      |
|-------------|--------|--------------------------------------------------|
| `id`          | `string` | Unique identifier of the insight                |
| `status`      | `string` | Current status of the download request          |
| `signed_url`  | `string` | Temporary URL for downloading the packaged data |

A sample response: 

```json 200
{
  "id": "<string>",
  "status": "<string>",
  "signed_url": "<string>"
}
```

A **400 Bad Request** error is returned when the body is missing or incorrectly formatted. A **403 Forbidden** error is returned when the user does not have permission to access the AOI or insight.

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

## How to use the endpoint
<p>

1. **Construct your Request:**  
    Prepare a JSON body with inputs and outputs arrays (even if only one is used). Replace aoi_id and insight_id in the URL with actual values. Add your auth token in the Authorization header.

2. **Send the Request:**  
    Make a PUT request to `https://api.pixxel.space/v0/aoi/{aoi_id}/insights/{insight_id}/download`. Include your JSON body and headers.

3. **Examine the Response:**  
    On success, you'll get a JSON object containing the insight ID, download status, and a signed URL. Use this URL to download your data. Errors will indicate permission issues or malformed inputs.
</p>