AOIs

An AOI (Area of Interest) is the container the rest of the SatMRV workflow attaches to — it covers one or more of your Fields, and everything downstream (stratification data orders, stratification zones, sample plans, samples) is scoped to one. This page covers AOI CRUD and pricing. See ./OVERVIEW.mdx for the base URL, auth, and response envelope shared across all of SatMRV, and for how AOIs fit into the wider workflow.

Endpoints

Method	Path	Purpose
GET	`aois/`	List AOIs
POST	`aois/`	Create an AOI
GET	`aois/{id}/`	Retrieve a single AOI
PUT / PATCH	`aois/{id}/`	Update an AOI
DELETE	`aois/{id}/`	Soft-delete an AOI (returns 204)
GET	`aois/{id}/price/`	Look up pricing for an AOI

All paths above are relative to https://backend.spacenus.de/api/v1.2/sat-mrv/.

Permissions

Every AOI endpoint also requires your company to have an active stratification subscription — a company without one is rejected regardless of which permission slugs its role holds.

Action	Required permission
List / Retrieve / Price	`aoi.view`
Create	`aoi.create`
Update / Partial update	`aoi.edit`
Delete	`aoi.delete`

Creating an AOI

POST https://backend.spacenus.de/api/v1.2/sat-mrv/aois/
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "North Block AOI",
  "description": "Stratification pilot for the north block",
  "field_uuids": ["FIELD_UUID_1", "FIELD_UUID_2"]
}

Field	Type	Required	Notes
`name`	string	No
`description`	string	No
`field_uuids`	array of strings (UUIDs), write-only	Yes	The Fields this AOI covers

A successful create returns HTTP 200 (the shared envelope normalizes the underlying 201 to 200 — see ./OVERVIEW.mdx):

{
  "status": "success",
  "message": "AOI created successfully.",
  "data": {
    "aoi_uuid": "AOI_UUID",
    "name": "North Block AOI",
    "description": "Stratification pilot for the north block",
    "aoi_fields": [
      {"field_uuid": "FIELD_UUID_1"},
      {"field_uuid": "FIELD_UUID_2"}
    ],
    "is_map_requested": false
  }
}

Exact message wording isn't guaranteed byte-for-byte — treat status and data as the stable contract.

Response fields

Beyond the standard nested company/created_by fields present on every SatMRV resource:

Field	Notes
`aoi_uuid`	Server-generated identifier for the AOI
`aoi_fields`	Nested, read-only list of the Fields linked to this AOI
`is_map_requested`	Read-only boolean

List responses (GET aois/) additionally include two read-only counts per AOI: total_saved_sample_plan_maps and total_saved_stratification_maps.

Pricing lookup

GET aois/{id}/price/ tells you what a stratification/SOC order would cost for this AOI.

GET https://backend.spacenus.de/api/v1.2/sat-mrv/aois/AOI_UUID/price/
Authorization: Bearer YOUR_TOKEN

A successful lookup returns HTTP 200:

{
  "status": "success",
  "message": "...",
  "data": {
    "area": 12.4,
    "prices": [
      {"map_type": "STR", "total_price": 37.2, "price_per_unit": 3, "aoi_area": 12.4},
      {"map_type": "SOC", "total_price": 62.0, "price_per_unit": 5, "aoi_area": 12.4}
    ]
  }
}

If your company has no subscription price configured for stratification, you instead get HTTP 404:

{
  "message": "You do not have a subscription for stratification service."
}

Any other lookup failure also returns HTTP 404, with a generic error message.

"Already ordered" discount, not a pricing bug. If a stratification data order already exists for this AOI under your company, total_price and price_per_unit in the price response are forced to 0 — you've already paid for that order, so this is intentional, not an error. Don't be surprised if a price lookup on an AOI you've already ordered for comes back free.

Status codes

Status	Meaning here
200	List, retrieve, update, price, and create (create's underlying 201 is normalized to 200)
204	Delete succeeded (soft delete)
400	Request body failed validation
403	Missing the required permission slug, or your company has no active stratification subscription
404	AOI not found, or (price lookup) no subscription price configured / a generic lookup failure

What's next

Once you have an AOI, order the data it needs to be stratified — see ./STRATIFICATION_DATA_ORDERS.mdx — then move on to the stratification workflow to produce zones and a sample plan.