FarmOS Land Portfolio

---

name: farmos-land-portfolio

description: Query land ownership, leases, landlord info, and land payments. Write operations for payment management and lease renewals.

tags: [farming, land, leases, landlords]

---

# FarmOS Land Portfolio

Track owned and leased land, lease terms, landlord relationships, payments, and annual land costs.

CRITICAL: Data Completeness Rules

**NEVER use partial or truncated data. These rules are non-negotiable:**

1. **NEVER use `/api/integration/dashboard`** — it truncates results to 5 items. Partial payment data is worse than no data because it creates a false sense of completeness.

2. **ALWAYS use the `/all` endpoints** listed below for complete data.

3. **If an endpoint returns an error or empty results, REPORT THE FAILURE to the user.** Do not silently fall back to a different endpoint or present partial data.

4. **ALWAYS state the total count** of records returned so the user knows the data is complete. Example: "Found 11 payments due in March totaling $175,058."

5. **If you cannot get complete data, say so explicitly.** "I was unable to retrieve complete payment data" is infinitely better than showing 5 of 11 payments.

When This Skill Triggers

Access Control

Lease terms, rent amounts, and landlord info are sensitive business data. Restrict to admin or manager roles only.

**Role mapping:** Check the sender's role in `~/.openclaw/farmos-users.json`. If the user is not admin or manager, tell them they don't have access to land portfolio data.

API Base

http://100.102.77.110:8009

Integration Endpoints (No Auth Required) — READ OPERATIONS ONLY

**IMPORTANT: Use auth endpoints for WRITE operations (mark-paid, renewals). Use integration `/all` endpoints for READ operations (listing payments, leases, landlords).**

Payments (FULL — use this, not dashboard)

GET /api/integration/payments/all

- `status` — pending, paid, overdue, scheduled

- `payment_type` — rent, mortgage, property_tax, insurance, improvement, other

- `parcel_id` — filter by specific parcel

- `due_date_from` — YYYY-MM-DD range start

- `due_date_to` — YYYY-MM-DD range end

- `crop_year` — filter by crop year

- All overdue: `/api/integration/payments/all?status=overdue`

- March 2026 payments: `/api/integration/payments/all?due_date_from=2026-03-01&due_date_to=2026-03-31`

- All rent payments: `/api/integration/payments/all?payment_type=rent`

Upcoming Payments (next N days)

GET /api/integration/payments/upcoming?days=30

Leases (FULL)

GET /api/integration/leases/all

- `status` — active, expired

- `landlord_id` — filter by landlord

Expiring Leases

GET /api/integration/leases/expiring?days=90

Landlords (FULL)

GET /api/integration/landlords/all

Parcels

GET /api/integration/parcels

Summary Stats

GET /api/integration/summary

Annual Land Costs (by month and entity)

GET /api/integration/finance/costs?year=2026

Cost Per Field (for P&L)

GET /api/integration/finance/cost-per-field?year=2026

Overdue Items

GET /api/integration/tasks/overdue

Actionable Items

GET /api/integration/tasks/actionable?days_ahead=30

Authenticated Endpoints — WRITE OPERATIONS

These require JWT auth. See Authentication section below.

Authentication

This skill accesses protected FarmOS endpoints that require a JWT token.

**To get a token:** Run the auth helper with the appropriate role:

TOKEN=$(~/clawd/scripts/farmos-auth.sh admin)

**To use the token:** Include it as a Bearer token:

curl -H "Authorization: Bearer $TOKEN" http://100.102.77.110:8009/api/endpoint

**Token expiry:** Tokens last 15 minutes. If you get a 401 response, request a new token.

Mark Single Payment Paid

POST /api/payments/{id}/mark-paid

Authorization: Bearer {token}

Content-Type: application/json

Body:

{
  "paid_date": "2026-02-15",
  "notes": "Check #1234"
}

Mark Multiple Payments Paid (Bulk)

POST /api/payments/bulk/mark-paid

Authorization: Bearer {token}

Content-Type: application/json

Body:

{
  "payment_ids": [12, 34, 56],
  "paid_date": "2026-02-15",
  "notes": "Batch check run"
}

Mark Payments Paid by Date Range

POST /api/payments/bulk/mark-paid-by-date

Authorization: Bearer {token}

Content-Type: application/json

Body:

{
  "due_date_from": "2026-03-01",
  "due_date_to": "2026-03-31",
  "paid_date": "2026-02-15",
  "payment_type": "rent",
  "notes": "March rent payments"
}

Use this when the user says "mark all March payments as paid" or similar bulk date-based operations.

Preview Lease Renewal

POST /api/leases/renewal-preview

Authorization: Bearer {token}

Content-Type: application/json

Body:

{
  "lease_ids": [5, 12],
  "new_start_date": "2027-03-01",
  "rent_increase_percent": 3.0
}

Returns: Preview of what the renewed leases would look like, including new payment schedules. Use this BEFORE executing bulk renewals so the user can confirm.

Execute Bulk Lease Renewal

POST /api/leases/bulk-renew

Authorization: Bearer {token}

Content-Type: application/json

Body:

{
  "lease_ids": [5, 12],
  "new_start_date": "2027-03-01",
  "new_end_date": "2028-02-28",
  "new_rent_amount": 52000.00,
  "rent_increase_percent": 3.0,
  "notes": "Annual renewal with 3% increase"
}

**IMPORTANT:** Always preview first, confirm with user, then execute.

Year-End Rollover Preview

POST /api/payments/year-end-rollover/preview

Authorization: Bearer {token}

Content-Type: application/json

Body:

{
  "from_year": 2026,
  "to_year": 2027
}

Returns: Preview of payment schedules that would be created for the new crop year.

Year-End Rollover Execute

POST /api/payments/year-end-rollover/execute

Authorization: Bearer {token}

Content-Type: application/json

Body:

{
  "from_year": 2026,
  "to_year": 2027,
  "apply_rent_increase": true,
  "rent_increase_percent": 2.5
}

**IMPORTANT:** This creates next year's payment schedules based on current year leases. Always preview first.

FORBIDDEN Endpoints — Do NOT Use

| Endpoint | Why |

|----------|-----|

| `GET /api/integration/dashboard` | **Truncates to 5 items. NEVER use this.** |

Key Concepts

Usage Notes