​
Overview

The Create a new AOI endpoint lets users create an Area of Interest by submitting a POST request with required metadata and geometry. It requires an API key and a well-structured JSON body that includes fields like name, description, geometry, project ID, and item IDs. On success, it returns a 201 Created response with full AOI details. This endpoint streamlines the process of registering spatial areas for Earth Observation analysis. Errors such as bad requests, authorization failures, or duplicate entries are handled through standard error responses.

  • Method: POST
  • URL: /v0/aois
  • Operation: Create a new AOI
  • 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 AOI. Used to identify it within the platform.
descriptionstring✅Descriptive text explaining the purpose or contents of the AOI.
lens_satellite_idstring✅ID of the satellite associated with this AOI’s EO data.
providerstring✅Name of the data provider (e.g., “planetary”).
project_idstring✅ID of the project to which this AOI should be linked.
geometryobject✅GeoJSON object defining the shape of the AOI.
geometry.coordinatesarray✅Coordinates array representing the spatial boundary of the AOI.
geometry.typestring✅Type of geometry (e.g., "Polygon" or "MultiPolygon").
item_idsarray of string✅List of item IDs that the AOI is based on or linked to.
Here is sample of the body:
body
data '{
  "name": "AOI-Bangalore",
  "description": "This AOI contains images related to Bangalore",
  "lens_satellite_id": "ce5dcc14-8291-4b0c-a278-8c05ec426d22",
  "provider": "planetary",
  "project_id": "ce5dcc14-8291-4b0c-a278-8c05ec426d18",
  "geometry": {
    "coordinates": [
      [
        [
          123
        ]
      ]
    ],
    "type": "<string>"
  },
  "item_ids": [
    "TD0123233",
    "TD01232344"
  ]
}'

​
Query Parameters

You dont really need to put query parameters for Create AOI.

​
Path Parameters

You dont really need to put path parameters for Create AOI.

​
Response

The response for the Create AOI API confirms that the AOI was successfully created. It returns a 201 Created status along with detailed information about the new AOI, including its ID, name, geometry, project details, and timestamps. This helps verify that your input was received and processed correctly.Please refer to the table below for explaination of the fields in the response:

FieldTypeDescription
aoi_idstringUnique identifier for the newly created AOI.
namestringName assigned to the AOI by the user.
descriptionstringDescription of the AOI.
lens_satellite_idstringID of the satellite linked to the AOI.
project_idstringID of the project to which the AOI belongs.
imagesobjectContainer for associated images; may be empty.
eo_bandsarrayList of Earth Observation bands used in the AOI.
geometryobjectGeoJSON object representing the AOI’s spatial shape.
geometry.coordinatesarrayArray of coordinates defining the AOI’s geometry.
geometry.typestringGeometry type (e.g., "Polygon", "MultiPolygon").
progressintegerProgress of AOI processing (0–100).
statusstringStatus of the AOI (e.g., "success").
is_favouritebooleanIndicates if the AOI is marked as a favorite.
created_atstringTimestamp of when the AOI was created.
updated_atstringTimestamp of the last update to the AOI.
user_idstringID of the user who created the AOI.
area_in_sq_mfloatTotal area of the AOI in square meters.
centroidarrayGeographical center of the AOI [longitude, latitude].
201
{
  "aoi_id": "e9767554-550e-4464-a677-b8cf096073ab",
  "name": "AOI-Bangalore",
  "description": "This AOI contains images related to Bangalore",
  "lens_satellite_id": "ce5dcc14-8291-4b0c-a278-8c05ec426d22",
  "project_id": "ce5dcc14-8291-4b0c-a278-8c05ec426d18",
  "images": {},
  "eo_bands": [
    "B01",
    "B02",
    "B03"
  ],
  "geometry": {
    "coordinates": [
      [
        [
          123
        ]
      ]
    ],
    "type": "<string>"
  },
  "progress": 100,
  "status": "success",
  "is_favourite": false,
  "created_at": "2022-11-14 12:55:49.125928+00:00",
  "updated_at": "2022-11-14 12:55:49.125928+00:00",
  "user_id": "user-123456",
  "area_in_sq_m": 123456.78,
  "centroid": [
    77.55,
    12.95
  ]
}
If you recieve a Bad Request error (400), Forbidden error (403), Conflict error (409) or the Internal Server Error (500), you will get the following response:
400 403 409 500
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}

​
How to use the endpoint

  1. Construct Your request: Construct the body by creating a JSON object with all required fields like name, description, geometry, IDs, etc and then include it in the POST request to the endpoint.
  2. Send the request Make the POST request to https://api.pixxel.space/v0/aois with the JSON body
  3. Examine the response As a response, the user will see a JSON object with details of the newly created AOI, including its unique ID, name, geometry, project and satellite IDs, status, and timestamps. It confirms successful creation with a 201 Created status. If there’s an error, a structured error message will be returned.