Assessments

An Assessment is the top-level record RegenScope3 is built around — it's scoped to one of your own Farms or Fields, and everything downstream (data sections, completeness, submission, the impact report) attaches to one. This page covers assessment CRUD plus a couple of detail/schema helper endpoints. See RegenScope3 API for the base URL, auth, response envelope, and status values shared across all of RegenScope3.

Endpoints

Method	Path	Purpose
GET	`assessments/`	List assessments. Filter by `assessment_year`, `resource_type`, `resource_id`
POST	`assessments/`	Create an assessment, optionally with nested section data inline
GET	`assessments/{id}/`	Retrieve a single assessment
PUT / PATCH	`assessments/{id}/`	Update an assessment
DELETE	`assessments/{id}/`	Delete an assessment
GET	`assessments/{id}/details/`	Alternate read-only detail view. Supports `?group=` and `?enforce_required=`
GET	`assessments/dynamic-schema/`	Serializer-reflection schema, useful for auto-generating a frontend form
GET	`assessments/ghg-values/`	See the warning below — currently returns hardcoded placeholder data

All paths above are relative to https://backend.spacenus.de/api/v1.2/regen-scope-3/.

Permissions

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

assessments/{id}/details/ is served by a separate view (AssessmentDetailView) that enforces plain IsAuthenticated plus the same dynamic permission check, rather than the company-role-based check most of the rest of the app uses. In practice you still need the assessment.view permission — just be aware the underlying auth mechanism for this one endpoint is slightly different if you're debugging an unexpected 401/403 here.

Creating an assessment

POST https://backend.spacenus.de/api/v1.2/regen-scope-3/assessments/
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "resource_type": "farm",
  "resource_id": 482,
  "assessment_year": 2026,
  "climate_region": "warm_temperate_moist",
  "farm_country": "germany",
  "submitted_data_quality": "mix_of_actual_and_estimated_data",
  "growing_area": {"value": 120, "unit": "ha"},
  "average_temperature": {"value": 14.5, "unit": "celsius"}
}

Field	Type	Required	Notes
`resource_type`	string	Yes	Must be `"farm"` or `"field"`
`resource_id`	integer	Yes	Must belong to your own company — an ID from another company is rejected as invalid
`assessment_year`	integer	No
`growing_area`	JSON object	No	Conventionally `{"value": ..., "unit": ...}`, but not strictly validated at create time — full validation happens later at submit time
`average_temperature`	JSON object	No	Same convention/caveat as `growing_area`
`climate_region`	string (enum)	No	One of: `tropical_montane`, `tropical_wet`, `tropical_moist`, `tropical_dry`, `warm_temperate_moist`, `warm_temperate_dry`, `cool_temperate_moist`, `cool_temperate_dry`, `boreal_moist`, `boreal_dry`
`farm_country`	string (enum)	No	One of roughly 200 snake_case country keys (for example `germany`, `pakistan`)
`submitted_data_quality`	string (enum)	No	One of: `all_actual_data`, `all_estimated_data`, `mix_of_actual_and_estimated_data`

A successful create returns HTTP 201:

{
  "status": "success",
  "message": "Assessment created successfully.",
  "data": {
    "id": 918,
    "resource_type": "farm",
    "resource_id": 482,
    "assessment_year": 2026,
    "status": "draft",
    "completeness_percentage": 0,
    "is_ready_for_submission": false,
    "completeness_computed_at": null,
    "climate_region": "warm_temperate_moist",
    "farm_country": "germany",
    "submitted_data_quality": "mix_of_actual_and_estimated_data",
    "growing_area": {"value": 120, "unit": "ha"},
    "average_temperature": {"value": 14.5, "unit": "celsius"}
  }
}

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

You can also include nested section data directly in the create (or update) body — for example a fertilizers array — instead of calling the separate section endpoints documented in Assessment Data Sections. Both approaches write to the same underlying data, so pick whichever shape is more convenient for your client.

A 201 response confirms the assessment record itself was created — it does not guarantee every downstream step succeeded. Some background/async processing kicked off for a new assessment can fail to start; that failure is only logged internally and is not surfaced back in the create response.

Read-only response fields

Field	Notes
`status`	See RegenScope3 API for the current valid values
`completeness_percentage`	Cached — not recomputed live on every GET
`is_ready_for_submission`	Cached — not recomputed live on every GET
`completeness_computed_at`	Timestamp of the last completeness computation

See Completeness and Submission for how to force a fresh completeness check rather than relying on these cached values.

Internal Cool Farm Tool identifiers (cool_farm_resource_uuid, cool_farm_assessment_uuid, cool_farm_assessment_response) are never included in any response from this API. Don't build client logic that expects them.

Detail view: `assessments/{id}/details/`

An alternate, read-only view of an assessment, with two optional query parameters:

?group= — filter the returned data down to a specific section group.
?enforce_required= — validate the assessment's data against required-field rules as part of the response.

GET https://backend.spacenus.de/api/v1.2/regen-scope-3/assessments/918/details/?group=fertilizer&enforce_required=true
Authorization: Bearer YOUR_TOKEN

{
  "status": "success",
  "message": "...",
  "data": {
    "id": 918,
    "status": "draft",
    "completeness_percentage": 42,
    "is_ready_for_submission": false
  }
}

The exact shape of data depends on which group you request and whether enforce_required surfaced any missing-field issues — treat the fields shown above as the stable baseline and expect additional section-scoped fields alongside them.

Dynamic schema

GET assessments/dynamic-schema/ reflects the assessment serializer into a schema description you can use to auto-generate a frontend form, instead of hand-maintaining field lists as the serializer evolves.

GET https://backend.spacenus.de/api/v1.2/regen-scope-3/assessments/dynamic-schema/
Authorization: Bearer YOUR_TOKEN

GET assessments/ghg-values/ currently returns hardcoded placeholder numbers for every request, regardless of any assessment. This endpoint takes no assessment identifier at all and always returns the same fixed values (emissions: 24.8, removals: 5.3, balance derived from those two, unit: "tCO2e") — it does not calculate anything from real data. This is a known bug (filed as a new finding this session), not a documented feature. Do not use this endpoint's response as real data; use GHG Impact Report's impact-report endpoint instead for genuine GHG figures.

Status codes

Status	Meaning here
200	List, retrieve, update, details, dynamic-schema, ghg-values
201	Create
204	Delete
400	Validation failure, including a `resource_id` that belongs to another company
403	Missing the required permission slug
404	Not found — outside your company's scope and not shared with you

What's next

Once an assessment exists, fill it in via assessment data sections, then check its completeness and submit it via completeness & submission.

Endpoints

Permissions

Creating an assessment

Read-only response fields

Detail view: assessments/{id}/details/

Dynamic schema

Status codes

What's next

Detail view: `assessments/{id}/details/`