Farmos Land Portfolio

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

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

• "When do our leases expire?"
• "What's the rent on the Smith ground?"
• "Total land costs this year?"
• "Show overdue payments"
• "Landlord contact info"
• "Cost per acre by parcel"
• "List all leased parcels"
• "What payments are due in March?"
• "Cash requirements for next month"
• "Mark payment [X] as paid"
• "Mark all March payments paid"
• "Renew the Smith lease"
• "Preview lease renewals"

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

• Returns ALL payments with full details — parcel names, landlord names, overdue status
• Query parameters:
  • 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
• Examples:
  • 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

• Returns ALL upcoming payments within N days (no truncation)
• Use days=60 or days=90 for longer lookahead

Leases (FULL)

GET /api/integration/leases/all

• Returns ALL leases with landlord contact info, rent terms, expiration status
• Query parameters:
  • status — active, expired
  • landlord_id — filter by landlord

Expiring Leases

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

• Returns ALL leases expiring within N days

Landlords (FULL)

GET /api/integration/landlords/all

• Returns ALL landlords with contact info, active lease count, total acres, total rent

Parcels

GET /api/integration/parcels

• Returns ALL parcels with ownership type, acres, county
• Query parameter: ownership_type — owned, leased

Summary Stats

GET /api/integration/summary

• Total acres, owned/leased breakdown, parcel/lease/landlord counts, annual cost

Annual Land Costs (by month and entity)

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

• Monthly cost breakdown by category (rent, mortgage, tax, insurance)
• Entity breakdown
• Query parameters: year, entity_id

Cost Per Field (for P&L)

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

• Land costs allocated to production fields
• Query parameters: year, entity_id

Overdue Items

GET /api/integration/tasks/overdue

• All overdue payments and reminders — high priority items

Actionable Items

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

• Upcoming payments, expiring leases, pending reminders

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:

bash

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

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

bash

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:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

{
  "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

• Parcel: A land unit — either owned or leased.
• Lease types: Cash rent, crop share, flex rent.
• Lease expiration: Critical to track — approaching expirations need proactive attention.
• Land payments: Rent, mortgage, property tax, insurance — each with due dates.

Usage Notes

• Lease expiration tracking is the highest-value query — always flag leases expiring within 6 months.
• Payment status (due/overdue) is critical — flag overdue payments immediately.
• Cost per acre analysis helps compare owned vs leased economics.
• Landlord contact info is private — never share outside admin/manager channels.
• When asked about "cash requirements" or "what do we owe", always use /api/integration/payments/all with date filtering to get the COMPLETE picture.
• For financial planning questions, combine /api/integration/payments/all with /api/integration/finance/costs for the full view.
• Write operations: Always use authenticated endpoints for marking payments paid or renewing leases. Preview first when doing bulk operations.
• Bulk payment marking: When user says "mark all March payments paid", use the bulk-by-date endpoint rather than individual calls.