Completeness and Submission

Once an assessment's data sections are filled in, there are two more calls in the flow: check whether the assessment is actually ready, then submit it to Cool Farm Tool for real calculation. Base URL, authentication, and the response envelope are the same as everywhere else in this API — see the overview page. For what status values an assessment can be in, see the assessments page.

Checking completeness

GET and POST assessments/{ASSESSMENT_ID}/check-data-completeness/ both return a completeness report — which sections are filled in, and an overall readiness flag. Neither has side effects on the assessment's data.

GET

Builds the completeness report from the data already saved on the assessment. Fast, local-only check.

POST

Does the same completeness check, then additionally validates the assembled data against Cool Farm Tool's own requirements live.

Both GET and POST here return HTTP 200 for a normal result, even when the assessment isn't ready yet. This endpoint doesn't use error status codes to signal "not complete" — that's signaled in the response body itself, via a readiness field, not via the HTTP status. 400 is reserved for a malformed request itself (for example a broken context/serializer), never for "assessment isn't complete."

Submitting for calculation

POST assessments/{ASSESSMENT_ID}/submit/ submits a complete assessment to Cool Farm Tool for real calculation.

Status	Trigger
200	Success — the assessment moves toward a submitted/processing state.
400	The request context itself was invalid, or a value-conversion error occurred while assembling the submission.
422	The assessment isn't ready for submission yet (incomplete data), it's already been submitted, or Cool Farm returned back a draft with outstanding issues.
500	An unexpected internal error.
502	The underlying draft-run step returned an unexpected/falsy result.
503	"Assessment is still being processed. Please try again later." — a genuinely transient state, safe to retry after a short wait.

Call check-data-completeness first and only call submit once its readiness flag is true. submit's 422 for "not ready" essentially duplicates what check-data-completeness already tells you in advance, so use the completeness check to avoid an avoidable failed submit call.

If submit fails partway through (for example an internal exception while assembling the request), the specific error message you get back may not fully reflect the underlying root cause — an internal fallback path can mask the original error. Treat a 500 here as "something went wrong server-side," not as a precise diagnostic. Retry once, then contact Spacenus if it persists.

Once submitted, the report becomes available via the impact report page — that's the next step after a successful submit. Real calculation happens asynchronously against the external Cool Farm Tool service, so expect some delay between a successful submit and the report actually reflecting real numbers — see the impact report page for the exact "not yet calculated" response shape during that window.

Example: check completeness

curl https://backend.spacenus.de/api/v1.2/regen-scope-3/assessments/ASSESSMENT_ID/check-data-completeness/ \
  -H "Authorization: Bearer YOUR_TOKEN"

A response while the assessment is still missing data (still 200):

{
  "status": "success",
  "message": "Assessment completeness evaluated successfully.",
  "data": {
    "assessment_id": "ASSESSMENT_ID",
    "ready_for_cool_farm": false,
    "ready_for_submission": false,
    "completion": {
      "completed_checkpoints": 14,
      "total_checkpoints": 21,
      "missing_checkpoints": 7,
      "percentage": 66.67
    },
    "sections": [
      {
        "section": "fertilizers",
        "status": "incomplete",
        "progress": {"completed_checkpoints": 3, "total_checkpoints": 4},
        "missing_fields": ["fertilizer_application_rate"]
      }
    ],
    "missing_fields": ["fertilizer_application_rate"]
  }
}

Example: submit

curl -X POST https://backend.spacenus.de/api/v1.2/regen-scope-3/assessments/ASSESSMENT_ID/submit/ \
  -H "Authorization: Bearer YOUR_TOKEN"

A successful response:

{
  "status": "success",
  "message": "Assessment submission completed successfully.",
  "data": {
    "assessment_id": "ASSESSMENT_ID",
    "ready_for_submission": true,
    "is_draft": false,
    "assessment_status": "submitted"
  }
}

A 422 response for an assessment that isn't ready yet:

{
  "status": "error",
  "message": "Assessment is not ready for submission.",
  "details": {
    "assessment_id": "ASSESSMENT_ID",
    "ready_for_cool_farm": false,
    "ready_for_submission": false,
    "completion": {
      "completed_checkpoints": 14,
      "total_checkpoints": 21,
      "missing_checkpoints": 7,
      "percentage": 66.67
    },
    "sections": [],
    "missing_fields": ["fertilizer_application_rate"]
  }
}