SatMRV is Spacenus's soil-sampling and MRV (measurement, reporting, verification) workflow. This page covers the concepts, base URL, auth, response shapes, and rules shared across every SatMRV endpoint, so you have the shared ground before jumping into a specific product's page.
What SatMRV does
The workflow is built around AOIs (Areas of Interest): you define an AOI over one or more Fields, order stratification data for it, run stratification to produce zones, generate a sample plan, save the results, then physically collect and log samples out in the field.
Create an AOI over one or more of your Fields. This is the container everything else in the workflow attaches to.
Order the underlying data needed to stratify the AOI.
Run stratification on the ordered data to produce sampling zones.
Turn the zones into a concrete plan of sample points.
Persist the stratification/sample-plan output you want to keep.
Physically collect samples at the planned points and log the results.
Two older mount points for this same underlying pipeline still exist —
/api/v1.2/regenerative-farming/...and/api/v1.2/sampling/.... SatMRV (/api/v1.2/sat-mrv/...) is the current, actively-maintained surface. Don't build new integrations against the legacy paths.
Base URL and authentication
All SatMRV endpoints are mounted under:
https://backend.spacenus.de/api/v1.2/sat-mrv/Every request must be authenticated. Send your access token as a bearer token:
Authorization: Bearer YOUR_TOKENResponse envelope
Every SatMRV response — like the rest of the Spacenus API — is wrapped in a standard envelope:
- A successful (2xx) response looks like
{"status": "success", "message": ..., "data": ...}. - An error (4xx) response looks like
{"status": "error", "message": ..., "details": ...}.
A permission-denied response (403) carries this shape specifically:
{ "code": "permission_denied", "message": "...", "details": { "required_permission": "...", "action": "...", "resource": "..." } }Check
details.required_permissionwhen debugging a 403 — it tells you exactly which permission slug your token's role/company is missing.
Products at a glance
| Product | What it's for | Guide |
|---|---|---|
| AOIs | Define the area you're sampling, covering one or more Fields; also where you look up stratification/SOC pricing | AOIs |
| Stratification workflow | Run stratification on an AOI's ordered data to produce zones, then generate a sample plan | Stratification Workflow |
| Stratification data orders | Order the underlying data an AOI needs before it can be stratified | Stratification Data Orders |
| Saved maps | Persist stratification and sample-plan results | Saved Maps |
| Samples | Log physically-collected soil samples | Samples |
| Sample-point reports | Reports scoped to an individual sample point | Sample-Point Reports |
| Soil property | Soil property data tied to your samples | Soil Property |
| SOC orders | Order soil organic carbon (SOC) data | Soil Organic Carbon Map (SOC) Orders |
| SOC Projection | Project soil organic carbon forward over time | SOC Projection |
The map_tag / plan_tag draft shortcut
map_tag / plan_tag draft shortcutSeveral actions in the stratification workflow accept an optional map_tag/plan_tag. Omit it and the system resolves to your current unsaved draft automatically; if you do supply one, it must reference an actual unsaved draft slot, or the request is rejected. This comes up in several places across stratification and sample-plan actions — see Stratification Workflow for the full contract.
Pagination
Standard list pagination applies across SatMRV: results default to page size 10, and you can pass ?page=all to get the full, unpaginated result set in the same response envelope. There's one documented exception on the Samples list endpoint — see Samples for that detail.
What's next
Start with AOIs if you haven't created one yet, then follow the workflow through stratification data orders, the stratification workflow, saved maps, and samples. The SOC track (SOC orders, SOC Projection) and reporting endpoints (sample-point reports, soil property) build on the same AOIs and auth/envelope rules covered on this page.