Farm Management is the core operational-data area of the Spacenus API: farms, fields, seasons, crops, cultivations, fertilization, and field boundaries. This page covers what every resource in this area has in common — base URL, auth, the response envelope, pagination, sharing, and two cross-resource quirks worth knowing up front. Each resource then has its own page with its exact fields, filters, and examples.
Before you start
All Farm Management endpoints are mounted under:
https://backend.spacenus.de/api/v1.2/Every request must be authenticated. Send your access token as a bearer token:
Authorization: Bearer YOUR_TOKENAs a fallback to the bearer token, these endpoints also accept an API key passed as a query parameter. Lead with the bearer token in your integration — it's the primary supported flow.
Every response, success or error, is wrapped in the same envelope. A 2xx response looks like:
{
"status": "success",
"message": "...",
"data": { }
}A 4xx response looks like:
{
"status": "error",
"message": "...",
"details": { }
}Products at a glance
| Resource | What it is | Endpoint |
|---|---|---|
| Farms | A company's physical farm sites | /farm/ |
| Fields | Boundaries and geospatial data for land parcels within a farm | /field/ |
| Seasons | Named growing periods a cultivation runs within | /season/ |
| Crops | The shared, global crop catalog | /crop/ |
| Cultivations | A crop grown in a field during a season | /cultivation/ |
| Fertilization | Fertilization events recorded against a cultivation | /fertilization/ |
| Boundaries | Geospatial boundary data for fields | see Fields |
The links above use relative Markdown links to sibling pages in this same folder. If your ReadMe project doesn't resolve relative
.mdxlinks this way, look up each page by its title in the docs navigation instead — the endpoint paths in the table are accurate either way.
How the resources fit together
These resources form a hierarchy, not a flat list of unrelated tables: a Farm contains Fields; a Cultivation ties one Field to one Crop within one Season (Season x Crop x Field); and Fertilization events are recorded against a Cultivation, not a Field directly. This is why, for example, creating a fertilization record asks you for a cultivation_id rather than a field_id — the cultivation is what already identifies which field, season, and crop the fertilization applies to.
Pagination
List endpoints are paginated with a default page size of 10. Pass ?page=all to get every result in one call — the response is still wrapped in the same paginated shape:
{
"count": 42,
"next": null,
"previous": null,
"results": [ ]
}Sharing across companies (?share=true)
?share=true)Farms (and Seasons, Cultivations, and Fertilization — see each resource's own page) support a ?share=true query parameter on list and retrieve requests. When another company has created a ShareGrant with your company, adding ?share=true swaps the queryset to the resources shared with you by that other company.
?share=trueis a toggle, not a merge. With it set, you see only the shared company's resources — not your own resources plus the shared ones. Omit the parameter (or set it tofalse) to see your own company's resources as usual.
Foreign keys: always write the _id form
_id formEvery serializer in Farm Management is built on a shared base that auto-injects both a nested, read-only object and a writable
{field}_idfield for each foreign-key relationship. For example, a Farm response includes a nestedcompanyobject for reading, but on write you sendcompany_id(notcompany) — the API only accepts the_idform for creating or updating a relationship. This applies to every FK across every resource here:farm_id,field_id,crop_id,cultivation_id,season_id, and so on.The one exception is
created_by(andrequest_by, where present) — these are read-only nested objects only; there's nocreated_by_idto write.
Soft delete
DELETE on any Farm Management resource is a soft delete: it sets a deleted_at timestamp rather than physically removing the row. Deleted rows never reappear in list or retrieve results. A successful delete returns 204 No Content with no body.
Bulk create
Bulk create — POSTing a JSON array instead of a single object to the same create endpoint — is supported on Farms, Fields, Seasons, Cultivations, and Fertilization. It is not supported on Crops (see Crops).
The status code returned for a bulk array containing an invalid item is inconsistent across resources, for historical rather than deliberate reasons:
POST /field/andPOST /season/return 402 Payment Required for a bulk array with any invalid item (a single invalid object on these two still returns 400).POST /farm/,POST /cultivation/, andPOST /fertilization/return a unified 400 for both single-object and bulk-array validation failures.Don't assume this is consistent across resources — check the status code documented on each resource's own page before writing bulk error-handling logic against a specific one.
Permission errors
A 403 from any Farm Management endpoint uses a structured body instead of the generic error envelope:
{
"code": "permission_denied",
"message": "You do not have permission to access this resource.",
"details": {
"required_permission": "farm.view",
"action": "list",
"resource": "FarmViewSet"
}
}required_permission names the specific dynamic-permission slug your token's role/membership is missing; each resource's own page lists the exact slugs it checks per action.
What's next
Head to the page for the resource you're integrating — Farms, Fields, Seasons, Crops, Cultivations, or Fertilization — for its exact fields, filters, and examples. Everything on this page applies underneath all of them.