​
Overview

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

​
Authorization

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

Authorization: <YOUR_API_KEY>

​
Body

The body of an API request is where you send the actual data that the server needs to perform an action. For example, when creating a new AOI, the body contains details like its name, location, description, and related IDs. Think of it like filling out a form — the body holds all the answers you’re submitting. It’s usually sent in JSON format and is required for actions like POST or PUT requests.You need the following fields in Body

FieldTypeRequiredDescription
namestring✅Name of the index (e.g., "NDVI").
descriptionstring✅Short explanation of the index’s purpose.
rescaleinteger[]✅Array with min and max rescale values (e.g., [0, 1]).
expressionstring✅Formula for calculating the index (e.g., "(B04-B08)/(B04+B08)").
colormapstring✅Color palette for rendering the index (e.g., "rplumbho").
lens_satellite_idstring✅Satellite ID associated with this index.
expression_typeenum<string>✅Type of expression: composite, index, or grayscale.
typeenum<string>✅Index category: custom or preset.
Here is a sample of the Body:
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"
}

​
Query Parameters

This endpoint does not require any query parameters.

​
Path Parameters

This endpoint does not require any path parameters.

​
Response

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:

NameTypeDescription
bandsstring[]List of spectral bands used in the expression
colormapstringName of the colormap applied to the output visualization
created_atstringTimestamp when the formula was created (ISO 8601 format)
descriptionstringDescription of what the formula is intended to analyze or reveal
expressionstringMathematical expression applied using the selected bands
expression_typestringType of the expression (e.g., “index”, “formula”)
idstringUnique identifier of the custom expression
lens_satellite_idstringInternal ID of the satellite configuration this formula is tied to
namestringHuman-readable name of the custom formula
rescalenumber[]Min and max range used to normalize or rescale the output values
satellite_namestringName of the satellite (e.g., “Sentinel-2”)
typestringType of formula, usually “custom” for user-defined expressions
updated_atstringTimestamp when the formula was last updated (ISO 8601 format)
Here is a sample 201 response:
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.
400 409 500
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}

​
How to use the endpoint

  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.