Assessment API Reference

The Assessment API lets you create and manage crop assessments tied to a farm or field record. An assessment captures a full production profile for a given year — including crop details, inputs (fertilizers, pesticides, seeds, fuel, irrigation), emissions-related data (refrigerants, transport, machinery), and carbon/biomass information.

Base URL

https://backend.spacenus.de/api/v1.2/regen-scope-3

Prerequisite

The resource_id (farm or field) must already exist in the platform via the Farm Management API. The assessment will be rejected if the resource is not registered or does not belong to your company.

Endpoints

Assessment Object

An assessment is a parent object. All data sections (crop details, fertilizers, pesticides, etc.) are nested inside it. Sections that accept a single entry are objects; sections that accept multiple entries are arrays.

Create an Assessment

POST /assessments?api_key=<your_api_key>
Content-Type: application/json

You can submit any combination of nested sections in a single request. All nested sections are optional at creation.

Minimal request

{
  "assessment_year": 2022,
  "resource_id": 1483,
  "resource_type": "farm"
}

Full request example

{
  "assessment_year": 2022,
  "resource_id": 1483,
  "resource_type": "farm",
  "climate_region": "cool_temperate_dry",
  "farm_country": "germany",
  "growing_area": { "value": 50, "unit": "ha" },
  "average_temperature": { "value": 12.5, "unit": "C" },
  "submitted_data_quality": "all_actual_data",
  "crop_details": {
    "crop_type_key": "winter_wheat",
    "total_harvested": { "value": 3, "unit": "tonnes" },
    "farmgate_amount": { "value": 2, "unit": "tonnes" }
  },
  "residues": {
    "residue_management_practice": "left_on_field",
    "above_ground_dry_matter": { "value": 15.5, "unit": "kg_per_hectare" }
 }
  ,
  "fertilizers": [
        {
            "fertilizer_type": "triple_super_phosphate",
            "production_region": "africa_2014",
            "fertilizer_application_rate": {
                "unit": "kg per hectare",
                "value": 140
            },
            "weight_or_units": "product",
            "fertilizer_application_date": "2024-04-12"
        },
        {
            "fertilizer_type": "calcium_ammonium_nitrate",
            "production_region": "europe_2014",
            "fertilizer_application_rate": {
                "unit": "kg per hectare",
                "value": 205
            },
            "weight_or_units": "product",
            "emission_factor_choice": "default_emission_factor",
            "fertilizer_application_date": "2024-05-25"

        }
    ],
    "pesticides": [
        {
            "pesticide_type": "herbicide",
            "pesticide_category": "post_emergence",
            "field_percentage": 100,
            "active_ingredient_percentage": 72,
            "pesticide_application_rate": {
                "unit": "litres per hectare",
                "value": 0.6
            }
        },
        {
            "pesticide_type": "pesticide",
            "pesticide_category": "post_emergence",
            "field_percentage": 100,
            "active_ingredient_percentage": 25,
            "pesticide_application_rate": {
                "unit": "litres per hectare",
                "value": 0.7
            }
        },
        {
            "pesticide_type": "fungicide",
            "pesticide_category": "post_emergence",
            "field_percentage": 100,
            "active_ingredient_percentage": 12.5,
            "pesticide_application_rate": {
                "unit": "litres per hectare",
                "value": 0.9
            }
        }
    ],
    "fuel_and_energy": [
        {
            "by_volume_volume_of_fuel_used": {
                "unit": "litres",
                "value": 224
            },
            "by_volume_energy_source": "diesel_100_mineral",
            "energy_boundary": "within_farm_operations",
            "category_within_farm": "field"
        }
    ],
  "seeds": {
    "purchase_type": "seed",
    "seed_source_type": "hybrid_seed_from_breeder",
    "mass_of_seed": { "value": 4, "unit": "kg" }
  }
}

Response — returns the full assessment object with all nested sections and generated IDs.

{
  "id": 901,
  "assessment_year": 2022,
  "resource_id": 1483,
  "resource_type": "farm",
  "status": "draft",
  "crop_details": {
    "id": 45,
    "crop_type_key": "winter_wheat",
    "total_harvested": { "value": 3, "unit": "tonnes" },
    "farmgate_amount": { "value": 2, "unit": "tonnes" }
  },
  "fertilizers": [],
  "created_at": "2026-05-05T10:22:00Z",
  "updated_at": "2026-05-05T10:22:00Z"
}

Update an Assessment

PATCH /assessments/{id}?api_key=<your_api_key>
Content-Type: application/json

Only the fields included in the request body are updated. Omitted top-level fields are left unchanged.

Update Behaviour for Nested Sections

Single-entry sections (crop_details, residues, seeds, soil_carbon_changes, non_crop_biomass_estimated, re_deforestation):

• If the section does not yet exist, it is created.

• If it already exists, it is replaced with the new data.

• Send null to delete the section. Multi-entry sections (fertilizers, pesticides, wastewater, co_products, refrigerants, fuel_and_energy, irrigation_energy, transport, non_crop_biomass_measured):

• Entries without an id are treated as new and appended.

• Entries with an id are matched and updated in place.

• Existing entries whose id is not present in the request are deleted.

from_web Query Parameter

Pass ?from_web=true to enable granular nested update logic (used by the web application). Without this flag, multi-entry sections are fully replaced on each PATCH.

PATCH /assessments/901?api_key=<your_api_key>&from_web=true

Example — update crop details and add a pesticide

{
  "crop_details": {
    "total_harvested": { "value": 4, "unit": "tonnes" }
  },
  "pesticides": [
    {
      "pesticide_category": "herbicide",
      "pesticide_type": "glyphosate",
      "pesticide_application_rate": { "value": 2, "unit": "l/ha" }
    }
  ]
}

Fetch an Assessment

GET /assessments/{id}?api_key=<your_api_key>

Returns the full assessment object, including all nested sections.

List Assessments

GET /assessments?api_key=<your_api_key>

Returns all assessments belonging to your company.

Delete an Assessment

DELETE /assessments/{id}?api_key=<your_api_key>

Permanently deletes the assessment and all nested data.

Nested Section Reference

{value, unit} Fields

Many fields use a structured measurement object:

{ "value": 3, "unit": "tonnes" }

Always provide both value and unit when submitting a measurement. value must be a positive float (minimum: 1e-9) unless otherwise noted.

Crop Details

Single entry object. Captures core crop production figures for the assessment. Enter data only for the specific crop and field being assessed, including any associated cover crops or managed field boundaries.

Scope note: Set a clear boundary for all data entered (cradle-to-farm-gate is recommended). Avoid double-counting inputs used for other cash crops, and make sure all emissions within the 12-month harvest cycle are captured.

total_harvested and farmgate_amount — Field Structure

Both fields share the same {value, unit} shape:

Allowed unit values:

Allowed Crop Types

Use the key string (left column) as the value for crop_type_key.

Example

{
  "crop_type_key": "winter_wheat",
  "total_harvested": {
    "value": 250.5,
    "unit": "tonnes"
  },
  "farmgate_amount": {
    "value": 238.0,
    "unit": "tonnes"
  }
}

Notes

• total_harvested is the gross yield before any post-harvest losses; farmgate_amount is the net marketable quantity after processing.
• Emissions intensity in results (kg CO₂e/tonne) is scaled against farmgate_amount.
• Co-products must be entered separately in the co_products section — do not include them here.

Crop Residues

Single entry object. Records above-ground crop residues and how they are managed. Default dry-matter weights are provided automatically based on the crop type; override them with a manual value if you have more precise data.

Note: Residue amounts must be entered as dry weight. Dry weights vary by crop — typically around 90% of fresh weight for cereals and legumes, and between 10–20% for most fruits and vegetables. Residue management emissions appear in results separately from soil carbon effects.

Allowed residue_management_practice values:

Allowed above_ground_dry_matter unit values:

Example

{
  "residue_management_practice": "left_on_field",
  "above_ground_dry_matter": {
    "value": 15.5,
    "unit": "kg_per_hectare"
  }
}

Seeds

Single entry object. Records seed or plug inputs used to produce the assessed crop. Only include seed sourced externally or from on-farm production that is not already captured in a separate assessment.

Note: The purchase_type field controls which fields are active. Fields belonging to the inactive type are automatically set to null by the API. If purchase_type is omitted or sent as null, all seed and plug fields are nulled.

Fields

purchase_type Conditional Behaviour

Allowed seed_source_type values (applicable only when purchase_type = "seed"):

Allowed mass_of_seed unit values:

Examples

Seed-based entry:

{
  "purchase_type": "seed",
  "mass_of_seed": { "value": 180, "unit": "kg" },
  "seed_source_type": "single_variety"
}

Plug-based entry:

{
  "purchase_type": "plug",
  "number_of_plugs": 5000,
  "plugs_in_peat_soil": false
}

No seed input (clear the section):

{
  "purchase_type": null
}

Fertilizers

Array. Each entry represents one fertilizer product applied to the growing area. Include inputs applied to the main crop, any cover crops, and managed field boundaries. Fuel used to apply fertilizers should be entered separately in the Fuel & Energy section.

Note: No production emissions are assumed for manure-based fertilizers, as these are considered by-products of livestock production. Custom emission factors can be entered when better data is available.

Fertilizer types

Allowed fertilizer_application_rate unit values:

Allowed weight_or_units (application_rate_basis) values:

For example: 100 kg/ha of Urea (46% N) can equivalently be entered as 46 kg/ha using "unit of nitrogen (N)".

Fertilizer Production Regions

If uncertain, select "default". The model first attempts to apply a region-specific emission factor; if unavailable, it falls back to a global factor.

Pesticides

Array. Each entry represents one pesticide application. Pesticide inputs contribute to emissions through production, using average emission factors (fewer options are available compared to fertilizers, as less environmental data exists for crop protection products).

Allowed pesticide_category values:

Allowed pesticide_type values:

Allowed pesticide_application_rate unit values:

Wastewater

Array. Each entry represents one wastewater stream. This section is only relevant when pools of standing wastewater are actively managed on the farm and the average annual temperature exceeds 15°C. Skip this section if neither condition applies.

Wastewater includes run-off from land, livestock waste management (e.g. slurry), and any washing or processing activities within the assessment boundary.

Allowed oxygen_demand_type values:

Allowed wastewater_treatment values:

Allowed wastewater_volume unit values:

Allowed oxygen_demand unit values:

Co-Products

Array. Each entry represents one co-product produced alongside the primary crop — either deliberately (co-cropping) or as a direct result of production (e.g. straw). Adding co-products distributes a portion of the total emissions away from the primary crop.

Allowed co_allocation_method values:

Refrigerants

Array. Each entry represents one refrigerant-using piece of equipment on the farm. Use this section if the assessed crop is stored in a refrigerated or air-conditioned facility. Energy used by this equipment should be entered separately in Fuel & Energy.

Allowed equipment_type_key values:

Allowed recovery_pathway_key values:

Allowed refrigerant_allocation_method values:

Allowed refrigerant_type_key values (select from the full list below):

"unknown", "r400_50_50", "r400_60_40", "r401a" through "r422c", "r500" through "r509a", "hfc23" through "hfc43_10mee", "hcfc142b", "cfc114", "cfc115", "cfc12", "cfc13", "hc1270", "hc290", "hc600", "hc600a", "hcfc124", "hcfc22", "hcfc31", "he_e170", "pfc_116", "pfc_218", "pfc_318"

Use "unknown" when the refrigerant type is not identifiable.

Fuel & Energy

Array. Each entry represents one fuel or energy source used in the production and on-farm processing of the assessed crop. Covers all energy within the assessment scope: storage, lighting, drying, cooling, ventilation, irrigation, and contractor energy. Do not double-count with the Machinery or Irrigation sections.

Each entry uses one of four input modes depending on how energy consumption is measured:

By Volume

Allowed by_volume_energy_source values:

Allowed volume unit values: "litres" (metric default), "cubic metres", "gallons", "gallons (US)" (imperial default)

By Weight

Allowed by_weight_energy_source values:

Allowed weight unit values: "tonnes" (metric default), "kg", "tons short" (imperial default), "tons long", "lb"

By Energy

Allowed by_energy_energy_source values:

Allowed energy unit values: "kWh" (metric default), "MJ", "btu", "thm" (imperial default)

By Grid Energy (Custom Emission Factor)

Use this mode when entering grid electricity with a known custom emission factor.

Shared Fields — Boundary and Category

Allowed energy_boundary values:

Allowed category_within_farm values (only applicable when boundary is "within_farm_operations"):

Irrigation Energy

Array. Use this section to estimate fuel and energy use from irrigation when actual consumption data is unavailable. If you have measured energy data, enter it directly in Fuel & Energy instead — do not enter the same usage in both sections.

Provide either total_water_added_depth or total_water_added_volume (not both). If pumping depth and horizontal distance are also provided, the model uses these to refine the energy estimate.

Allowed irrigation_system_type values:

Allowed water_source values:

Allowed power_source values:

Allowed unit values for water depth: "mm" (metric default), "in" (imperial default)

Allowed unit values for pumping distances: "m" (metric default), "ft" (imperial default); also accepts "mm", "cm", "km", "in", "mi"

Allowed unit values for water volume: "litres" (metric default), "cubic metres", "acre inches" (imperial default)

Transport

Array. Each entry represents one transport leg. Use this section to capture fuel and energy from transport when actual consumption data is unavailable. If you have measured fuel data, enter it in Fuel & Energy and avoid double-counting.

Multiple journeys with the same vehicle and distance can be combined into a single entry. For example, five trips delivering 2 tonnes of fertiliser over 20 km by HGV can be entered as one entry: HGV, 10 tonnes, 20 km.

Allowed transport_type values:

Allowed transport_boundary values:

Allowed weight unit values: "tonnes" (metric default), "kg", "tons short" (imperial default), "tons long", "lb"

Allowed distance unit values: "km" (metric default), "mi" (imperial default)

Machinery Operations

Single structured object. Estimates diesel and biodiesel consumption from farm machinery when actual fuel data is unavailable. Use this as a fallback only — actual fuel data entered in Fuel & Energy is always preferable.

{
  "machinery_operations": true,
  "soil_type": "medium",
  "list_of_machines": [
    {
      "machine_type": "moldboard_plough",
      "fuel_type": "diesel_100_percent_mineral_diesel",
      "number_of_operations": 1,
      "machinery_operations_label": "Primary tillage"
    }
  ]
}

Allowed soil_type values:

Allowed fuel_type values:

Allowed machine_type values (partial list of common types):

The full list of machine type keys is available in the platform's choice dictionary. If the exact machine is not listed, select the closest available option.

Soil Carbon Changes

Single entry object. Models carbon stored in or released from soil due to changes in land use or management practices. Two modelling approaches are available depending on the land history.

Allowed soil_classification values:

Land Use Change Entry

Allowed land use values (for non-grassland states):

Allowed carbon_inputs values:

Allowed tillage values:

Non-Crop Biomass — Estimated

Single entry object. Records intercrops, shade trees, and hedges planted within the last 20 years. Uses a Tier 1 method to estimate carbon captured by these plants. Do not double-count with the Non-Crop Biomass — Measured section.

This section can only be updated while the assessment status is "draft". Attempting to update it after submission returns a validation error.

{
  "intercrops": [
    {
      "intercrop_type": "avocado",
      "intercrop_percentage_occupied": { "value": 20, "unit": "%" },
      "intercrop_planting_density": { "value": 5000, "unit": "plants/ha" }
    }
  ],
  "shade_trees": [
    {
      "shade_tree_type": "tropical_shade_trees_in_wet_areas_canopy_trees",
      "shade_tree_percentage_occupied": { "value": 10, "unit": "%" },
      "shade_tree_planting_density": { "value": 50, "unit": "trees/ha" }
    }
  ],
  "hedges": [
    {
      "hedge_type": "species_mix",
      "hedge_width": { "value": 2, "unit": "m" },
      "hedge_length": { "value": 150, "unit": "m" }
    }
  ]
}

Detailed Component Schemas

1. Intercrops Schema

2. Shade Trees Schema

3. Hedges Schema

Common Measurement Layout

Every metric property defined within the lists above relies on this shared generic dictionary layout:

Allowed intercrop_type values:

Allowed shade_tree_type values:

Allowed hedge_type values:

Allowed planting density unit values: "plants/ha", "trees/ha" (metric), "plants/acre", "trees/acre" (imperial)

Allowed hedge dimension unit values: "m" or "km" (metric), "ft" or "mi" (imperial)

Non-Crop Biomass — Measured

Array. Each entry records annual biomass changes for trees within or immediately adjacent to the field. Only include biomass that is permanent and additional (trees present for more than 20 years should not be included). Do not double-count across adjacent crop assessments.

Allowed main_tree_type values:

Allowed diameter measurement unit values: "m" (metric default), "cm", "ft" (imperial default), "in"

Forestry / Re-deforestation

Single-entry object. Records any deforestation or reforestation of native forest within the growing area during the past 20 years. The model returns zero emissions or removals for events older than 20 years. Toggle between the two modes using.reforestation_or_deforestation.

This is a Tier 1 model and should not be used for formally reporting carbon removals.

Example Payload: Deforestation Tracked

{
  "reforestation_or_deforestation": "deforestation",
  "reforestation": null,
  "deforestation": {
    "forest_type": "boreal_mountain_systems",
    "years_since_forestry_event": 1,
    "age_of_forest_removed": 12,
    "area_affected_by_change_in_forestry": {
      "value": 1,
      "unit": "hectares"
    }
  }
}

Main Object Structure

Nested Object Schemas

Reforestation

Deforestation

Sub-Nested area_affected_by_change_in_forestry Structure

Allowed forest_type values:

Allowed affected_area unit values: "hectares" (metric default), "acres" (imperial default)

Assessment Field Choices

Climate Region Values

Use the key string (left column) as the value for climate_region.

Submitted Data Quality Values

Use the key string (left column) as the value for submitted_data_quality.

Farm Country Values

Use the key string (left column) as the value for farm_country.

Status

Error Reference

Example — resource not found

{
  "resource_id": "The specified farm does not exist."
}

Example — cross-company access attempt

{
  "resource_id": "You do not have permission to create an assessment for this farm."
}

Example — biomass locked after submission

{
  "non_field_errors": "Cannot update biomass in a finalized assessment."
}