## Overview
<p align="justify">
This endpoint lets users create a new custom or preset index by submitting a formula and related metadata. It requires a JSON request body with fields like `name`, `expression`, `description`, `rescale`, and `lens_satellite_id`. Once created, the API returns the index object with a **201 Created** status. This functionality is useful for defining spectral indices like NDVI, or grayscale composites for further processing. **API key authentication is mandatory**. Errors for invalid input or duplication are returned with appropriate codes and messages.

- Method: `POST`

- URL: `/v0/indices`

- Operation: Create a new index with custom parameters

- 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">
The **body** of an API request is where you send the actual data that the server needs to perform an action. You need the following fields in **Body :**

| Field               | Type               | Required | Description |
|---------------------|--------------------|----------|-------------|
| `name`              | `string`           | ✅       | Name of the index (e.g., `"NDVI"`). |
| `description`       | `string`           | ✅       | Short explanation of the index’s purpose. |
| `rescale`           | `integer[]`        | ✅       | Array with min and max rescale values (e.g., `[0, 1]`). |
| `expression`        | `string`           | ✅       | Formula for calculating the index (e.g., `"(B04-B08)/(B04+B08)"`). |
| `colormap`          | `string`           | ✅       | Color palette for rendering the index (e.g., `"rplumbho"`). |
| `lens_satellite_id` | `string`           | ✅       | Satellite ID associated with this index. |
| `expression_type`   | `enum<string>`     | ✅       | Type of expression: `composite`, `index`, or `grayscale`. |
| `type`              | `enum<string>`     | ✅       | Index category: `custom` or `preset`. |

Here is a sample of the Body:

```json body
{
  "name": "NDVI",
  "description": "This formula will give insights about vegetation",
  "rescale": [
    0,
    1
  ],
  "expression": "(B04-B08)/(B04+B08)",
  "colormap": "rplumbho",
  "lens_satellite_id": "0002a3a3-00a2-4b55-842b-44d8202c6d60",
  "expression_type": "index",
  "type": "custom"
}
```

</p>

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

## Path Parameters
<p align="justify">
This endpoint **does not** require any path parameters.
</p>

## Response
<p align="justify">
The response for this endpoint confirms successful index creation with a `201 Created` status. It returns detailed information about the new index, including its ID, name, expression, bands, satellite, 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                                                                 |
|-------------------|------------|-----------------------------------------------------------------------------|
| `bands`             | `string[]`   | List of spectral bands used in the expression                              |
| `colormap`          | `string`     | Name of the colormap applied to the output visualization                   |
| `created_at`        | `string`     | Timestamp when the formula was created (ISO 8601 format)                   |
| `description`       | `string`    | Description of what the formula is intended to analyze or reveal           |
| `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 custom expression                                 |
| `lens_satellite_id` | `string`     | Internal ID of the satellite configuration this formula is tied to         |
| `name`              | `string`     | Human-readable name of the custom formula                                  |
| `rescale`           | `number[]`   | Min and max range used to normalize or rescale the output values           |
| `satellite_name`    | `string`     | Name of the satellite (e.g., "Sentinel-2")                                 |
| `type`              | `string`     | Type of formula, usually "custom" for user-defined expressions             |
| `updated_at`        | `string`     | Timestamp when the formula was last updated (ISO 8601 format)              |

Here is a sample **201** response:

```json 201
{
  "bands": [
    "B01",
    "B02",
    "B03"
  ],
  "colormap": "rplumbho",
  "created_at": "2022-11-14 12:55:49.125928+00:00",
  "description": "This formula will give insights about vegetation",
  "expression": "(B04-B08)/(B04+B08)",
  "expression_type": "index",
  "id": "e9767554-550e-4464-a677-b8cf096073ab",
  "lens_satellite_id": "0002a3a3-00a2-4b55-842b-44d8202c6d60",
  "name": "NDVI",
  "rescale": [
    0,
    1
  ],
  "satellite_name": "Sentinel-2",
  "type": "custom",
  "updated_at": "2022-11-14 12:55:49.125928+00:00"
}
```

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 `name`, `description`, `expression`, `rescale`, `colormap`, `lens_satellite_id`, `expression_type`, and `type`. Make sure all fields are filled correctly as required.

2. **Send the Request:**  
    Make a POST request to: `https://api.pixxel.space/v0/indices`. Include the JSON body and your API key in the headers.

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