Farms

A Farm is a company's physical farm site — the top level of the Farm Management hierarchy. Fields belong to a Farm, and everything else (Cultivations, Fertilization) chains down from there.

This page covers only what's specific to Farms. For the base URL, authentication, the response envelope, pagination, sharing, the foreign-key _id convention, and soft delete, see Farm Management Overview.

Endpoints

Method	Path	Purpose
GET	`/farm/`	List farms
POST	`/farm/`	Create a farm (single object or bulk array)
GET	`/farm/FARM_ID/`	Retrieve a single farm
PUT	`/farm/FARM_ID/`	Replace a farm
PATCH	`/farm/FARM_ID/`	Partially update a farm
DELETE	`/farm/FARM_ID/`	Soft delete a farm

Auth

Requires a Bearer token — see Farm Management Overview for how to send one.

Each action also requires a dynamic permission on top of the token:

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

A request with a valid token but missing the required permission gets an HTTP 403 with the structured body described in Farm Management Overview.

List filters

GET /farm/ accepts these query parameters:

Filter	Type	Matches
`name`	string	Case-insensitive partial match (`icontains`)
`address`	string	Case-insensitive partial match (`icontains`)
`main`	boolean	Exact match — whether the farm is flagged as the company's primary farm
`company`	integer	Exact match on company (generic filter)
`created_by`	integer	Exact match on the creating user (generic filter)
`created_at`	date range	Generic created-at range filter

Create / update fields

Field	Type	Required	Notes
`name`	string, max 255	Yes
`lat`	decimal	No
`lng`	decimal	No
`address`	text	No
`note`	text	No
`main`	boolean	No	Marks this as the company's primary farm

Don't send company, company_id, or created_by — they're set automatically from your authenticated user and token, and aren't accepted as write input.

Response fields

Beyond the fields above, a Farm response also includes:

Field	Notes
`total_fields`	Count of this farm's non-deleted fields
`created_at`	Set on creation
`updated_at`	Set on every update
`company`	Nested, read-only — see Farm Management Overview on the `_id`-for-write convention
`created_by`	Nested, read-only — no `created_by_id` to write

Bulk create

POST /farm/ also accepts a JSON array of farm objects instead of a single object, to create several farms in one request. See Farm Management Overview for how Farms' bulk-error status code (400, for both single and bulk-array validation failures) differs from Fields' and Seasons' (402 for a bulk array with an invalid item).

Status codes

Status	Trigger
200	List, retrieve, create, or update succeeded.
204	Delete succeeded (soft delete; no response body).
400	Validation failure — single object or bulk array.
403	Missing `farm.view` / `farm.create` / `farm.edit` / `farm.delete` permission.
404	Farm not found (wrong `FARM_ID`, wrong company, or already deleted).

Create request

curl -X POST https://backend.spacenus.de/api/v1.2/farm/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "North Ridge Farm",
    "lat": "52.5200",
    "lng": "13.4050",
    "address": "Musterstrasse 1, 12345 Berlin",
    "note": "Primary grain operation",
    "main": true
  }'

Response:

{
  "status": "success",
  "message": "Farm created successfully.",
  "data": {
    "id": 101,
    "name": "North Ridge Farm",
    "lat": "52.5200",
    "lng": "13.4050",
    "address": "Musterstrasse 1, 12345 Berlin",
    "note": "Primary grain operation",
    "main": true,
    "total_fields": 0,
    "company": {
      "id": 7,
      "name": "Musterhof GmbH"
    },
    "created_by": {
      "id": 42,
      "name": "Jane Doe"
    },
    "created_at": "2026-08-19T10:15:00Z",
    "updated_at": "2026-08-19T10:15:00Z"
  }
}