A Season is a named growing period — for example, "2024 Winter Wheat" — that Cultivations run within. This page covers Season CRUD. Base URL, authentication, the response envelope, the FK _id write pattern, and other shared conventions are covered in the Farm Management overview — this page only covers what's specific to Seasons.
Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /season/ | List seasons. |
POST | /season/ | Create a season — single object or bulk array (see below). |
GET | /season/{id}/ | Retrieve one season. |
PUT | /season/{id}/ | Full update. |
PATCH | /season/{id}/ | Partial update. |
DELETE | /season/{id}/ | Delete a season (see the delete note below). |
Authentication and permissions
Send your access token as a bearer token, as described in the overview page.
Permission slug bug — document the real (buggy) slugs, not
season.*.SeasonViewSet's permission map actually checks thefarm.*slugs, notseason.*(tracked as finding F-043):
Action Required permission (actual) List / Retrieve farm.viewCreate farm.createUpdate / Partial update farm.editDelete farm.deleteGranting a user
season.viewdoes nothing here — it isn't checked anywhere in this path. Conversely, granting a user anyfarm.*permission also silently unlocks the matching Season action as a side effect, since the same slug gates both resources. Check forfarm.*in your integration's permission logic when you need Season access, notseason.*.
Create-body fields
| Field | Type | Required | Notes |
|---|---|---|---|
name | string, max 255 | Yes | |
start_date | date | Yes | |
end_date | date | Yes | Must satisfy end_date <= start_date + 550 days. A request violating this is rejected as invalid — see status codes below. |
As with every Farm Management resource, foreign keys are written with the _id suffix — Seasons themselves don't take an FK on create, but any resource that links to a Season (like Cultivation) expects season_id.
Response fields
Alongside the fields above, a Season response includes two read-only annotated counts:
| Field | Notes |
|---|---|
total_fields | Count of distinct, non-deleted Fields reachable through this season's Cultivations. |
total_cultivations | Count of this season's non-deleted Cultivations. |
Bulk create
POST /season/ accepts either a single object or a JSON array of objects.
A bulk array containing any invalid item returns 402 Payment Required for the whole request — not 400. A single invalid object (non-array body) still returns the expected 400. This is inconsistent with Cultivation and Fertilization (which return a unified 400 either way) — see the overview page's bulk-create section for the full picture across resources. Don't assume 400 covers every Season validation failure in your error-handling logic.
Deleting a season
DELETE /season/{id}/is a hard delete, not the soft-delete-then-hidden pattern used by Farm and Field. The row is actually removed rather than marked with adeleted_attimestamp. A successful delete returns204 No Contenteither way, so the response itself won't tell you which behavior you got — treat a deleted Season as gone for good, not recoverable.
Sharing (?share=true)
?share=true)Season has no direct Field or Farm foreign key, so ?share=true is resolved indirectly: through the season's Cultivations, to each Cultivation's Field, to that Field's sharing scope. The same "either your own seasons, or the shared company's seasons, never merged" behavior described in the overview applies here.
Status codes
| Status | Trigger |
|---|---|
| 200 | List, retrieve, update, or single-object create succeeded. |
| 400 | Single-object create validation failure, or the 550-day end_date rule violation. |
| 402 | Bulk-array create with any invalid item in the array. |
| 403 | Missing permission — checked against the farm.* slugs (see above). |
| 404 | Season not found. |
Example: create a season
curl -X POST https://backend.spacenus.de/api/v1.2/season/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "2024 Winter Wheat",
"start_date": "2024-10-01",
"end_date": "2025-08-01"
}'A successful response:
{
"status": "success",
"message": "Created successfully.",
"data": {
"id": 501,
"name": "2024 Winter Wheat",
"start_date": "2024-10-01",
"end_date": "2025-08-01",
"total_fields": 0,
"total_cultivations": 0
}
}