This API is in beta. Endpoints and response shapes may change before stable release.

Syncing data

The FarmReady API is designed for reliable incremental sync. A complete sync strategy has two parts: fetching updated records and fetching deleted records. Both can be scoped to a time window so your client only processes what has changed.

Fetching updated records

All list endpoints accept an updated_after query parameter. Pass an ISO 8601 timestamp to receive only records created or modified after that point. Combine with page / page_size to page through large change sets.

200 GET /api/shed/organisations/:org_id/receipts?updated_after=2026-06-01T00:00:00Z 
{
  "data": [
    { "id": "...", "updated_at": "2026-06-15T09:32:00Z", ... }
  ],
  "meta": {
    "page": 1,
    "page_size": 50,
    "total_pages": 1,
    "total_entries": 3
  }
}
ℹ Store the timestamp of your last successful sync and pass it as updated_after on your next run. Use the updated_at field on returned records — not your local clock — to advance the cursor.

Fetching deleted records

Deleted records do not appear in standard list responses. To sync deletions, use the dedicated deleted endpoint available on every Shed resource. Each entry contains the record's id and the timestamp it was deleted.

Parameter Type Required Description
deleted_after iso8601 — Return only records deleted after this timestamp.
ids[] uuid[] — Return only deletion records for these specific IDs. Useful for confirming whether a missing record was deleted.
200 GET /api/shed/organisations/:org_id/receipts/deleted?deleted_after=2026-06-01T00:00:00Z 
{
  "data": [
    { "id": "a1b2c3...", "deleted_at": "2026-06-10T14:22:00Z" },
    { "id": "d4e5f6...", "deleted_at": "2026-06-12T09:05:00Z" }
  ]
}
ℹ When both deleted_after and ids[] are supplied, only records matching both filters are returned (AND semantics).
⚠ Deletion records are retained for 60 days. Sync clients that go offline for longer than 60 days should perform a full re-sync rather than relying on the deleted endpoints.

Recommended sync loop

A typical incremental sync run:

  1. Fetch updated records on each list endpoint using updated_after=<last_sync>, paging through all results.
  2. Fetch deleted records on the deleted endpoints using deleted_after=<last_sync> and remove matching records from your local store.
  3. Advance your cursor to the current time.
⚠ Run the deletion fetch after the update fetch. A record deleted between the two requests will correctly be removed in step 2 rather than left as a stale update from step 1.