Farms API: Create, Read, Update, and Delete Fincas

The Farms API is the foundation of the Surqo platform. Every farm (finca) you register becomes the anchor for sensor readings, AI analyses, and real-time agronomic KPIs. Each farm stores the GPS coordinates and crop type that allow the system to pull accurate weather forecasts and apply crop-specific thresholds. Free-plan accounts are limited to one active farm — instead of creating a second farm you can edit the existing one to change the crop type or location.

Create a farm

Free-plan users are limited to 1 farm. Attempting to create a second farm returns a 400 FARM_LIMIT_REACHED error. Edit your existing farm to change the crop type or other details.

If owner_email or owner_name are omitted, the API automatically fills them from the authenticated user’s profile.

POST /api/v1/farms/ — Rate limit: 10 requests / minute

Request body

name

string

required

Human-readable farm name. Maximum 200 characters.

crop_type

string

required

Primary crop grown on the farm. Accepted values: maíz, yuca, plátano, café, arroz, algodón.

latitude

float

required

Farm latitude in decimal degrees. Must be between -90 and 90.

longitude

float

required

Farm longitude in decimal degrees. Must be between -180 and 180.

owner_name

string

Full name of the farm owner. Falls back to the authenticated user’s full_name when omitted.

owner_email

string

Contact email for the farm owner. Falls back to the authenticated user’s email when omitted.

area_hectares

float

Farm surface area in hectares. Must be greater than 0.

altitude_masl

integer

Altitude above sea level in metres.

department

string

Colombian department where the farm is located. Defaults to "Córdoba".

municipality

string

Municipality within the department.

Response `201`

Returns a FarmResponse object.

uuid

Unique farm identifier. Use this UUID in all subsequent farm-scoped requests.

name

string

Farm name as stored.

crop_type

string

Crop type as stored.

latitude

float

GPS latitude.

longitude

float

GPS longitude.

area_hectares

float | null

Farm area in hectares.

altitude_masl

integer | null

Altitude in metres above sea level.

owner_name

string | null

Resolved owner name.

owner_email

string | null

Resolved owner contact email.

department

string

Colombian department.

municipality

string | null

Municipality.

is_active

boolean

Whether the farm is currently active. Defaults to true on creation.

created_at

datetime

ISO 8601 timestamp of when the farm was created.

Example

curl -X POST https://surqo-api.fly.dev/api/v1/farms/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finca La Esperanza",
    "crop_type": "maíz",
    "latitude": 8.7575,
    "longitude": -75.8891,
    "area_hectares": 12.5,
    "owner_email": "agricultor@ejemplo.com",
    "department": "Córdoba"
  }'

Response 201

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Finca La Esperanza",
  "crop_type": "maíz",
  "latitude": 8.7575,
  "longitude": -75.8891,
  "area_hectares": 12.5,
  "altitude_masl": null,
  "owner_name": "Juan Pérez",
  "owner_email": "agricultor@ejemplo.com",
  "department": "Córdoba",
  "municipality": null,
  "is_active": true,
  "created_at": "2026-06-28T14:00:00Z"
}

Error: farm limit reached

When a free-plan user already has one farm, the API responds with:

Response 400

{
  "code": "FARM_LIMIT_REACHED",
  "message": "Cada cuenta puede registrar 1 finca. Edita tu finca existente para cambiar el cultivo."
}

List farms

GET /api/v1/farms/ — Auth required Returns all farms belonging to the authenticated user.

Query parameters

active_only

boolean

When true (default), only farms with is_active = true are returned. Set to false to include deactivated farms.

Response `200`

Returns an array of FarmResponse objects. See the Create a farm section for the full field reference.

curl https://surqo-api.fly.dev/api/v1/farms/ \
  -H "Authorization: Bearer <token>"

Get a farm

GET /api/v1/farms/{farm_id} — Auth required Returns a single farm by its UUID.

farm_id

uuid

required

The UUID of the farm to retrieve.

Returns 403 if the farm belongs to a different user, and 404 if the farm does not exist.

curl https://surqo-api.fly.dev/api/v1/farms/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>"

Update a farm

PATCH /api/v1/farms/{farm_id} — Auth required Partially updates a farm. Only the fields you include in the request body are modified; all other fields remain unchanged.

farm_id

uuid

required

The UUID of the farm to update.

Request body (all fields optional)

name

string

New farm name (max 200 characters).

crop_type

string

Updated crop type. Accepted values: maíz, yuca, plátano, café, arroz, algodón.

owner_name

string

Updated owner name.

owner_email

string

Updated owner contact email.

area_hectares

float

Updated farm area in hectares (must be > 0).

altitude_masl

integer

Updated altitude above sea level.

department

string

Updated department.

municipality

string

Updated municipality.

is_active

boolean

Set to false to deactivate the farm without deleting it.

Returns 403 if the farm belongs to a different user, and 404 if the farm does not exist.

curl -X PATCH https://surqo-api.fly.dev/api/v1/farms/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"crop_type": "café", "area_hectares": 15.0}'

Delete a farm

DELETE /api/v1/farms/{farm_id} — Auth required Permanently removes a farm and all data directly tied to it.

farm_id

uuid

required

The UUID of the farm to delete.

Deletion is irreversible. The operation:

Unlinks all associated AI analyses (they are preserved but their farm_id is set to null).
Permanently deletes all sensor readings and alerts for the farm.

Returns 204 No Content on success. Returns 403 if the farm belongs to a different user, and 404 if the farm does not exist.

curl -X DELETE https://surqo-api.fly.dev/api/v1/farms/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>"

Get farm KPIs

GET /api/v1/farms/{farm_id}/kpis — Auth required Returns a snapshot of agronomic key performance indicators computed from the farm’s sensor readings over the last 24 hours. This endpoint is designed for dashboard widgets and status cards.

farm_id

uuid

required

The UUID of the farm.

Response `200`

vpd_kpa

float

Vapour Pressure Deficit in kilopascals, calculated via the Magnus equation from air temperature and humidity readings.

avg_air_temp_c

float

Average air temperature (°C) over the last 24 hours.

avg_humidity_pct

float

Average relative air humidity (%) over the last 24 hours.

avg_soil_moisture_pct

float

Average soil moisture (%) over the last 24 hours.

soil_health_score

integer

Composite soil health score from 0 to 100.

pest_risk

object

Show pest_risk fields

risk_pct

integer

Estimated pest / disease risk as a percentage (0–100).

pathogens

array

List of detected or likely pathogens (e.g. ["roya"]).

conditions

string

Human-readable description of current conditions affecting pest risk.

readings_count_24h

integer

Number of sensor readings received in the last 24 hours.

latest_reading_at

datetime

Timestamp of the most recent sensor reading.

curl https://surqo-api.fly.dev/api/v1/farms/a1b2c3d4-e5f6-7890-abcd-ef1234567890/kpis \
  -H "Authorization: Bearer <token>"

Response 200

{
  "vpd_kpa": 1.42,
  "avg_air_temp_c": 29.5,
  "avg_humidity_pct": 68.3,
  "avg_soil_moisture_pct": 44.1,
  "soil_health_score": 75,
  "pest_risk": {
    "risk_pct": 35,
    "pathogens": ["roya"],
    "conditions": "Condiciones moderadas para hongos"
  },
  "readings_count_24h": 96,
  "latest_reading_at": "2026-06-28T14:35:00Z"
}

Visión General

Endpoints

Conceptos Avanzados

Farms API: Create, Read, Update, and Delete Fincas

Create a farm

Request body

Response `201`

Example

Error: farm limit reached

List farms

Query parameters

Response `200`

Get a farm

Update a farm

Request body (all fields optional)

Delete a farm

Get farm KPIs

Response `200`

Build docs developers (and LLMs) love

Visión General

Endpoints

Conceptos Avanzados

Documentation Index

​Create a farm

​Request body

​Response 201

​Example

​Error: farm limit reached

​List farms

​Query parameters

​Response 200

​Get a farm

​Update a farm

​Request body (all fields optional)

​Delete a farm

​Get farm KPIs

​Response 200

Build docs developers (and LLMs) love

Create a farm

Request body

Response `201`

Example

Error: farm limit reached

List farms

Query parameters

Response `200`

Get a farm

Update a farm

Request body (all fields optional)

Delete a farm

Get farm KPIs

Response `200`