Public API Documentation

The Regeno Farmwalk Public API enables external integrations to access farm data, agreements, and document uploads for UK agricultural compliance management.

Farm Data

Access farm details, parcels, and land features

Agreements

Retrieve SFI, CS, Red Tractor compliance data

Vault Uploads

Upload evidence photos, audio, and documents

Base URL

https://api.farmwalk.app/api/v1/public

Authentication

The API supports two authentication methods. Choose the one that best fits your use case.

RECOMMENDED

Organisation API Keys + JWT

Best for server-to-server integrations and applications that act on behalf of your organisation.

Organisation-scoped access
Requires OTP verification
JWT tokens expire in 7 days

Personal Access Tokens (PATs)

Best for personal scripts, CLI tools, and accessing multiple organisations.

User-scoped, multi-org access
No OTP required after creation
Optional expiration dates

Token Scopes

Both API keys and PATs support scopes to limit what operations they can perform:

Scope	Description	Allowed Methods
read	Read-only access	`GET`
write	Full access	`GET` `POST` `PATCH` `DELETE`

Scope Enforcement

Tokens with read scope will receive a 403 INSUFFICIENT_SCOPE error when attempting write operations (POST, PATCH, DELETE).

Option 1: API Key + JWT Headers

Parameter	Type	Required	Description
x-farmwalk-api	string	Yes	Organisation API key (pk.xxx...)
Authorization	string	Yes	Bearer token from /auth/verify

Authentication Flow

Create an API key

Generate a key from your organisation settings (one-time setup)

Initiate login

POST to /auth/login with email and organisation ID

Verify OTP

POST to /auth/verify with the code sent to your email

Use the API

Include both headers in all subsequent requests

Login Request

POST /auth/loginbash

curl -X POST "https://api.farmwalk.app/api/v1/public/auth/login" \
  -H "Content-Type: application/json" \
  -H "x-farmwalk-api: pk.your_api_key_here" \
  -d '{
    "email": "farmer@example.com",
    "organisationId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Verify OTP

POST /auth/verifybash

curl -X POST "https://api.farmwalk.app/api/v1/public/auth/verify" \
  -H "Content-Type: application/json" \
  -H "x-farmwalk-api: pk.your_api_key_here" \
  -d '{
    "session": "AYABeE1d...",
    "code": "123456",
    "email": "farmer@example.com",
    "organisationId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 604800,
  "user": {
    "id": "user-uuid",
    "email": "farmer@example.com",
    "firstName": "John",
    "lastName": "Farmer"
  },
  "organisation": {
    "id": "org-uuid",
    "membership": {
      "role": "farmer",
      "farmAccess": []
    }
  }
}

Token Validity

JWT tokens are valid for 7 days. Store them securely and refresh before expiration by repeating the login flow.

Option 2: Personal Access Token Headers

Parameter	Type	Required	Description
x-farmwalk-api	string	Yes	Personal access token (pat.xxx...)
X-Organisation-Id	uuid	Yes	Organisation to access

Example using PATbash

curl -X GET "https://api.farmwalk.app/api/v1/public/farms" \
  -H "x-farmwalk-api: pat.your_personal_token_here" \
  -H "X-Organisation-Id: 550e8400-e29b-41d4-a716-446655440000"

PATs can access any organisation you're a member of. Use the GET /me/organisations endpoint to list your organisations and their IDs.

Organisation API Keys

Organisation API keys provide access scoped to a single organisation. They are created and managed in your organisation settings. Only organisation owners can create and revoke API keys.

How to create an API key

1
Navigate to your Organisation Settings
Click your organisation name in the top navigation
2
Go to the API Keys tab
This tab is only visible to organisation owners
3
Click Create API Key
Give your key a descriptive name (e.g., "Mobile App", "Integration")
4
Choose the scope
Select Read Only for analytics/reporting, or Read & Write for full access
5
Copy and store your key securely
The full key is only shown once and cannot be retrieved later

Important: Store Your Key Securely

The full API key is only displayed once when created. If you lose it, you will need to create a new key. Never commit API keys to version control or share them publicly.

Key Format

API keys follow the format pk.{64 hex characters}

pk.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

Revoking Keys

If a key is compromised or no longer needed, you can revoke it from the API Keys tab. Revoked keys are immediately invalidated and cannot be used for any further API calls.

Personal Access Tokens (PATs)

Personal Access Tokens allow you to authenticate with your own identity across multiple organisations. PATs are ideal for personal scripts, CLI tools, and developers who need to access multiple organisations.

How to create a Personal Access Token

1
Go to your User Settings
Click your profile icon and select Settings
2
Navigate to the Security tab
This is where you manage your personal tokens
3
Click Create Token
Give your token a name that describes its purpose
4
Choose scope and expiration
Set read-only or full access, and optionally set an expiry date
5
Copy and store your token securely
The full token is only shown once and cannot be retrieved later

Token Format

PATs follow the format pat.{64 hex characters}

pat.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

Using PATs

When using a PAT, you must specify which organisation to access using the X-Organisation-Id header.

Example Request with PATbash

curl -X GET "https://api.farmwalk.app/api/v1/public/farms" \
  -H "x-farmwalk-api: pat.your_token_here" \
  -H "X-Organisation-Id: 550e8400-e29b-41d4-a716-446655440000"

List Your Organisations

Use the /me/organisations endpoint to discover which organisations you can access with your PAT.

GET

/me/organisations

List all organisations you belong to (PAT only, no X-Organisation-Id required)

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/me/organisations" \
  -H "x-farmwalk-api: pat.your_token_here"

Responsejson

{
  "organisations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Green Valley Farms",
      "slug": "green-valley-farms",
      "role": "owner",
      "allowPersonalTokens": true
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Sunrise Agriculture",
      "slug": "sunrise-agriculture",
      "role": "consultant",
      "allowPersonalTokens": true
    }
  ]
}

Organisation PAT Settings

Organisation admins can disable PAT access for their organisation. If allowPersonalTokens is false, you will need to use an organisation API key instead.

Token Expiration

PATs can optionally have an expiration date. When a token expires, it is automatically invalidated. Choose an appropriate expiration based on your security requirements:

30 days - For temporary access or testing
90 days - For short-term projects
1 year - For long-running integrations
No expiration - Only if absolutely necessary

Revoking PATs

You can revoke any of your PATs at any time from the Security tab in your settings. Revoked tokens are immediately invalidated. If you suspect a token has been compromised, revoke it immediately and create a new one.

Rate Limiting

The API enforces rate limits to ensure fair usage and system stability.

Endpoint Type	Window	Max Requests
Authentication	15 minutes	10
Read operations (GET)	1 minute	200
Write operations (POST)	1 minute	30

Rate Limit Headers

All responses include headers to help you track your usage:

Parameter	Type	Required	Description
X-RateLimit-Limit	integer	No	Maximum requests allowed in window
X-RateLimit-Remaining	integer	No	Requests remaining in current window
X-RateLimit-Reset	integer	No	Unix timestamp when limit resets
Retry-After	integer	No	Seconds to wait (on 429 response only)

When you receive a 429 Too Many Requests response, wait for the number of seconds specified in the Retry-After header before making another request.

Farms

Access farm data within your organisation. Results are automatically filtered based on the authenticated user's farm access permissions.

GET

/farms

List all farms the user has access to

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Max items to return (1-100, default 20)
offset	integer	No	Items to skip for pagination
isActive	boolean	No	Filter by active status
myFarmsOnly	0 \| 1	No	Narrow to the caller's "My Farms" — farms pinned by the user OR farms where they're a LEAD / ASSISTANT consultant. Falls through to the wider set if the user has none.
teamFarmsOnly	0 \| 1	No	Narrow to the caller's "Team Farms" (farms sharing a label with the user). Falls through if the user has no team farms.

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/farms?limit=10&isActive=true" \
  -H "x-farmwalk-api: pk.your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

Responsejson

{
  "items": [
    {
      "id": "farm-uuid",
      "name": "Green Acres Farm",
      "slug": "green-acres-farm",
      "sbiNumber": "123456789",
      "cphNumber": "12/345/6789",
      "totalHectares": 150.5,
      "parcelCount": 12,
      "isActive": true,
      "address": {
        "line1": "Green Acres",
        "town": "Farmington",
        "county": "Devon",
        "postcode": "EX1 2AB"
      },
      "coordinates": {
        "lat": 50.7236,
        "lng": -3.5275
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 5,
  "limit": 10,
  "offset": 0,
  "hasMore": false
}

GET

/farms/{farmId}

Get detailed information about a specific farm

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/farms/farm-uuid" \
  -H "x-farmwalk-api: pk.your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

My Farms & Teams

Personal farm-filter endpoints that mirror what users see inside Regeno:

My Farms — every farm the user has pinned or where they are the LEAD or ASSISTANT consultant. The two inputs are independent: pin and consultant role are managed separately, and a farm appears in My Farms if either is true. POST to /me/pinned-farms toggles the pin component (consultant role can only be set by an org admin).
Team Farms — the farms linked to the teams the user belongs to, intersected with the farms they can access.

Both subsets are also exposed as filters on GET /farms via ?myFarmsOnly=1 and ?teamFarmsOnly=1. Those filters “fall through” (return the wider set) if the user has none pinned or no team farms — matching the in-app behaviour.

GET

/me/pinned-farms

List the caller's My Farms (pinned ∪ consultant-assigned) in the current organisation

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/me/pinned-farms" \
  -H "x-farmwalk-api: pat.your_personal_token" \
  -H "X-Organisation-Id: your-org-uuid"

Responsejson

{
  "items": [
    {
      "farm": {
        "id": "farm-uuid",
        "name": "Green Acres Farm",
        "slug": "green-acres-farm",
        "sbiNumber": "123456789",
        "cphNumber": "12/345/6789",
        "totalHectares": 150.5,
        "parcelCount": 12,
        "isActive": true
      },
      "pin": {
        "pinId": "pin-uuid",
        "pinnedAt": "2026-04-12T08:30:00Z"
      },
      "consultantRole": "LEAD"
    },
    {
      "farm": { "id": "other-farm-uuid", "name": "Riverside Farm" },
      "pin": { "pinId": "pin-uuid-2", "pinnedAt": "2026-05-01T11:00:00Z" },
      "consultantRole": null
    },
    {
      "farm": { "id": "third-farm-uuid", "name": "Hilltop Farm" },
      "pin": null,
      "consultantRole": "ASSISTANT"
    }
  ],
  "total": 3
}

POST

/me/pinned-farms

Toggle a pin on a farm. Pinning is the only user-controllable input to My Farms — consultant role is org-admin. Requires write scope.

Request Body

Parameter	Type	Required	Description
farmId	uuid	Yes	UUID of the farm to pin or unpin. Must be in the current organisation and accessible to the caller.

Example Requestbash

curl -X POST "https://api.farmwalk.app/api/v1/public/me/pinned-farms" \
  -H "x-farmwalk-api: pat.your_personal_token" \
  -H "X-Organisation-Id: your-org-uuid" \
  -H "Content-Type: application/json" \
  -d '{"farmId":"farm-uuid"}'

Response (newly pinned, status 201)json

{
  "action": "pinned",
  "pin": {
    "id": "pin-uuid",
    "userId": "user-uuid",
    "organisationId": "org-uuid",
    "farmId": "farm-uuid",
    "pinnedAt": "2026-05-27T14:02:11Z"
  },
  "farmStillInMyFarms": true,
  "consultantRole": null
}

Response (already pinned, now unpinned, status 200)json

{
  "action": "unpinned",
  "pinId": "pin-uuid",
  "farmStillInMyFarms": false,
  "consultantRole": null
}

Response (unpinned but still a consultant, status 200)json

{
  "action": "unpinned",
  "pinId": "pin-uuid",
  "farmStillInMyFarms": true,
  "consultantRole": "LEAD"
}

GET

/me/team-farms

List the caller's Team Farms — farms sharing a label with the user

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/me/team-farms" \
  -H "x-farmwalk-api: pat.your_personal_token" \
  -H "X-Organisation-Id: your-org-uuid"

Responsejson

{
  "items": [
    {
      "id": "farm-uuid",
      "name": "Green Acres Farm",
      "slug": "green-acres-farm",
      "sbiNumber": "123456789",
      "cphNumber": "12/345/6789",
      "totalHectares": 150.5,
      "parcelCount": 12,
      "isActive": true,
      "address": { "line1": "Green Acres", "town": "Farmington", "postcode": "EX1 2AB" },
      "coordinates": { "lat": 50.7236, "lng": -3.5275 },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "labelIds": ["label-uuid-1", "label-uuid-2"]
}

Agreements

Access scheme agreements across the UK's agricultural compliance landscape — including the major government schemes, assurance schemes, and buyer-led regenerative programmes.

Supported scheme types (schemeType filter values):

SFI — Sustainable Farming Incentive (England)
CS — Countryside Stewardship (England)
SFS — Sustainable Farming Scheme (Wales)
AECS — Agri-Environment Climate Scheme (Scotland)
FFERMIO_BRO — Ffermio Bro Capital Grants (Wales)
NVZ — Nitrate Vulnerable Zone obligations
RED_TRACTOR — Red Tractor assurance
LEAF_MARQUE — LEAF Marque sustainable assurance
HEALTH_SAFETY — Health & Safety compliance
WILDFARMED — Wildfarmed regenerative grain programme
BOORTMALT_MALTING_GROWERS — Boortmalt malting-growers buyer-led scheme

GET

/farms/{farmId}/agreements

List all agreements for a farm

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Max items to return (1-100, default 20)
offset	integer	No	Items to skip for pagination
schemeType	string	No	Filter by scheme: SFI, CS, RED_TRACTOR, HEALTH_SAFETY
status	string	No	Filter by status: PENDING, ACTIVE, EXPIRED, CANCELLED
includeItems	boolean	No	Include agreement items (default true)

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/farms/farm-uuid/agreements?schemeType=SFI&status=ACTIVE" \
  -H "x-farmwalk-api: pk.your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

Responsejson

{
  "items": [
    {
      "id": "agreement-uuid",
      "farmId": "farm-uuid",
      "schemeType": "SFI",
      "reference": "SFI-2024-001234",
      "name": "SFI 2024 Agreement",
      "status": "ACTIVE",
      "startDate": "2024-01-01",
      "endDate": "2026-12-31",
      "complianceScore": 85.5,
      "totalAnnualValue": 12500.00,
      "items": [
        {
          "id": "item-uuid",
          "catalogCode": "SAM1",
          "itemType": "action",
          "status": "active",
          "progress": 0.75,
          "areaHa": 50.0,
          "calculatedPayment": 1100.00,
          "landAssignments": [
            {
              "id": "assignment-uuid",
              "landFeatureId": "parcel-uuid",
              "areaHa": 25.0,
              "status": "assigned",
              "landFeature": {
                "id": "parcel-uuid",
                "name": "Field 1 - Home Meadow",
                "featureType": "parcel"
              }
            }
          ]
        }
      ]
    }
  ],
  "total": 3,
  "limit": 20,
  "offset": 0,
  "hasMore": false
}

GET

/farms/{farmId}/agreements/{agreementId}

Get full agreement details including payments, inspections, and declarations

Vault Uploads

Upload evidence files (photos, audio, documents) to the farm vault. Files are automatically processed for transcription and AI analysis.

Upload Flow

1. Start Upload

2. Upload to S3

3. Finish Upload

POST

/farms/{farmId}/vault/upload/start

Initiate upload, returns presigned S3 URL

Request Body

Parameter	Type	Required	Description
filename	string	Yes	Original filename
mimeType	string	Yes	MIME type (e.g., image/jpeg)
sizeBytes	integer	Yes	File size in bytes (max 500MB)
folderId	uuid	No	Target folder UUID

Step 1: Start Uploadbash

curl -X POST "https://api.farmwalk.app/api/v1/public/farms/farm-uuid/vault/upload/start" \
  -H "x-farmwalk-api: pk.your_api_key" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "field-evidence.jpg",
    "mimeType": "image/jpeg",
    "sizeBytes": 2048576
  }'

Responsejson

{
  "uploadId": "upload-uuid",
  "presignedUrl": "https://s3.eu-west-2.amazonaws.com/bucket/...",
  "s3Key": "orgs/org-id/farms/farm-id/vault/upload-uuid.jpg",
  "s3Bucket": "farmwalk-vault-prod",
  "fileType": "image",
  "expiresIn": 1800,
  "expiresAt": "2024-06-15T12:30:00Z"
}

Step 2: Upload to S3bash

curl -X PUT "$presignedUrl" \
  -H "Content-Type: image/jpeg" \
  --data-binary @field-evidence.jpg

POST

/farms/{farmId}/vault/upload/finish

Complete upload, creates database record

Step 3: Finish Uploadbash

curl -X POST "https://api.farmwalk.app/api/v1/public/farms/farm-uuid/vault/upload/finish" \
  -H "x-farmwalk-api: pk.your_api_key" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadId": "upload-uuid",
    "s3Key": "orgs/org-id/farms/farm-id/vault/upload-uuid.jpg",
    "filename": "field-evidence.jpg",
    "mimeType": "image/jpeg",
    "sizeBytes": 2048576,
    "location": {
      "latitude": 50.7236,
      "longitude": -3.5275,
      "accuracy": 10
    },
    "category": "evidence",
    "tags": ["sfi", "sam1", "soil-assessment"]
  }'

POST

/farms/{farmId}/vault/upload/{uploadId}/renew

Renew presigned URL if expired before upload completed

Presigned URL Expiry

Presigned URLs expire after 30 minutes. If the URL expires before you complete the upload, use the /renew endpoint to get a fresh URL.

Public API Documentation

The Regeno Farmwalk Public API enables external integrations to access farm data, agreements, and document uploads for UK agricultural compliance management.

Farm Data

Access farm details, parcels, and land features

Agreements

Retrieve SFI, CS, Red Tractor compliance data

Vault Uploads

Upload evidence photos, audio, and documents

Base URL

https://api.farmwalk.app/api/v1/public

Authentication

The API supports two authentication methods. Choose the one that best fits your use case.

RECOMMENDED

Organisation API Keys + JWT

Best for server-to-server integrations and applications that act on behalf of your organisation.

Organisation-scoped access
Requires OTP verification
JWT tokens expire in 7 days

Personal Access Tokens (PATs)

Best for personal scripts, CLI tools, and accessing multiple organisations.

User-scoped, multi-org access
No OTP required after creation
Optional expiration dates

Token Scopes

Both API keys and PATs support scopes to limit what operations they can perform:

Scope	Description	Allowed Methods
read	Read-only access	`GET`
write	Full access	`GET` `POST` `PATCH` `DELETE`

Scope Enforcement

Tokens with read scope will receive a 403 INSUFFICIENT_SCOPE error when attempting write operations (POST, PATCH, DELETE).

Option 1: API Key + JWT Headers

Parameter	Type	Required	Description
x-farmwalk-api	string	Yes	Organisation API key (pk.xxx...)
Authorization	string	Yes	Bearer token from /auth/verify

Authentication Flow

Create an API key

Generate a key from your organisation settings (one-time setup)

Initiate login

POST to /auth/login with email and organisation ID

Verify OTP

POST to /auth/verify with the code sent to your email

Use the API

Include both headers in all subsequent requests

Login Request

POST /auth/loginbash

curl -X POST "https://api.farmwalk.app/api/v1/public/auth/login" \
  -H "Content-Type: application/json" \
  -H "x-farmwalk-api: pk.your_api_key_here" \
  -d '{
    "email": "farmer@example.com",
    "organisationId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Verify OTP

POST /auth/verifybash

curl -X POST "https://api.farmwalk.app/api/v1/public/auth/verify" \
  -H "Content-Type: application/json" \
  -H "x-farmwalk-api: pk.your_api_key_here" \
  -d '{
    "session": "AYABeE1d...",
    "code": "123456",
    "email": "farmer@example.com",
    "organisationId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 604800,
  "user": {
    "id": "user-uuid",
    "email": "farmer@example.com",
    "firstName": "John",
    "lastName": "Farmer"
  },
  "organisation": {
    "id": "org-uuid",
    "membership": {
      "role": "farmer",
      "farmAccess": []
    }
  }
}

Token Validity

JWT tokens are valid for 7 days. Store them securely and refresh before expiration by repeating the login flow.

Option 2: Personal Access Token Headers

Parameter	Type	Required	Description
x-farmwalk-api	string	Yes	Personal access token (pat.xxx...)
X-Organisation-Id	uuid	Yes	Organisation to access

Example using PATbash

curl -X GET "https://api.farmwalk.app/api/v1/public/farms" \
  -H "x-farmwalk-api: pat.your_personal_token_here" \
  -H "X-Organisation-Id: 550e8400-e29b-41d4-a716-446655440000"

PATs can access any organisation you're a member of. Use the GET /me/organisations endpoint to list your organisations and their IDs.

Organisation API Keys

Organisation API keys provide access scoped to a single organisation. They are created and managed in your organisation settings. Only organisation owners can create and revoke API keys.

How to create an API key

1
Navigate to your Organisation Settings
Click your organisation name in the top navigation
2
Go to the API Keys tab
This tab is only visible to organisation owners
3
Click Create API Key
Give your key a descriptive name (e.g., "Mobile App", "Integration")
4
Choose the scope
Select Read Only for analytics/reporting, or Read & Write for full access
5
Copy and store your key securely
The full key is only shown once and cannot be retrieved later

Important: Store Your Key Securely

The full API key is only displayed once when created. If you lose it, you will need to create a new key. Never commit API keys to version control or share them publicly.

Key Format

API keys follow the format pk.{64 hex characters}

pk.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

Revoking Keys

If a key is compromised or no longer needed, you can revoke it from the API Keys tab. Revoked keys are immediately invalidated and cannot be used for any further API calls.

Personal Access Tokens (PATs)

How to create a Personal Access Token

1
Go to your User Settings
Click your profile icon and select Settings
2
Navigate to the Security tab
This is where you manage your personal tokens
3
Click Create Token
Give your token a name that describes its purpose
4
Choose scope and expiration
Set read-only or full access, and optionally set an expiry date
5
Copy and store your token securely
The full token is only shown once and cannot be retrieved later

Token Format

PATs follow the format pat.{64 hex characters}

pat.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

Using PATs

When using a PAT, you must specify which organisation to access using the X-Organisation-Id header.

Example Request with PATbash

curl -X GET "https://api.farmwalk.app/api/v1/public/farms" \
  -H "x-farmwalk-api: pat.your_token_here" \
  -H "X-Organisation-Id: 550e8400-e29b-41d4-a716-446655440000"

List Your Organisations

Use the /me/organisations endpoint to discover which organisations you can access with your PAT.

GET

/me/organisations

List all organisations you belong to (PAT only, no X-Organisation-Id required)

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/me/organisations" \
  -H "x-farmwalk-api: pat.your_token_here"

Responsejson

{
  "organisations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Green Valley Farms",
      "slug": "green-valley-farms",
      "role": "owner",
      "allowPersonalTokens": true
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Sunrise Agriculture",
      "slug": "sunrise-agriculture",
      "role": "consultant",
      "allowPersonalTokens": true
    }
  ]
}

Organisation PAT Settings

Organisation admins can disable PAT access for their organisation. If allowPersonalTokens is false, you will need to use an organisation API key instead.

Token Expiration

PATs can optionally have an expiration date. When a token expires, it is automatically invalidated. Choose an appropriate expiration based on your security requirements:

30 days - For temporary access or testing
90 days - For short-term projects
1 year - For long-running integrations
No expiration - Only if absolutely necessary

Revoking PATs

Rate Limiting

The API enforces rate limits to ensure fair usage and system stability.

Endpoint Type	Window	Max Requests
Authentication	15 minutes	10
Read operations (GET)	1 minute	200
Write operations (POST)	1 minute	30

Rate Limit Headers

All responses include headers to help you track your usage:

Parameter	Type	Required	Description
X-RateLimit-Limit	integer	No	Maximum requests allowed in window
X-RateLimit-Remaining	integer	No	Requests remaining in current window
X-RateLimit-Reset	integer	No	Unix timestamp when limit resets
Retry-After	integer	No	Seconds to wait (on 429 response only)

When you receive a 429 Too Many Requests response, wait for the number of seconds specified in the Retry-After header before making another request.

Farms

Access farm data within your organisation. Results are automatically filtered based on the authenticated user's farm access permissions.

GET

/farms

List all farms the user has access to

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Max items to return (1-100, default 20)
offset	integer	No	Items to skip for pagination
isActive	boolean	No	Filter by active status
myFarmsOnly	0 \| 1	No	Narrow to the caller's "My Farms" — farms pinned by the user OR farms where they're a LEAD / ASSISTANT consultant. Falls through to the wider set if the user has none.
teamFarmsOnly	0 \| 1	No	Narrow to the caller's "Team Farms" (farms sharing a label with the user). Falls through if the user has no team farms.

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/farms?limit=10&isActive=true" \
  -H "x-farmwalk-api: pk.your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

Responsejson

{
  "items": [
    {
      "id": "farm-uuid",
      "name": "Green Acres Farm",
      "slug": "green-acres-farm",
      "sbiNumber": "123456789",
      "cphNumber": "12/345/6789",
      "totalHectares": 150.5,
      "parcelCount": 12,
      "isActive": true,
      "address": {
        "line1": "Green Acres",
        "town": "Farmington",
        "county": "Devon",
        "postcode": "EX1 2AB"
      },
      "coordinates": {
        "lat": 50.7236,
        "lng": -3.5275
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 5,
  "limit": 10,
  "offset": 0,
  "hasMore": false
}

GET

/farms/{farmId}

Get detailed information about a specific farm

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/farms/farm-uuid" \
  -H "x-farmwalk-api: pk.your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

My Farms & Teams

Personal farm-filter endpoints that mirror what users see inside Regeno:

My Farms — every farm the user has pinned or where they are the LEAD or ASSISTANT consultant. The two inputs are independent: pin and consultant role are managed separately, and a farm appears in My Farms if either is true. POST to /me/pinned-farms toggles the pin component (consultant role can only be set by an org admin).
Team Farms — the farms linked to the teams the user belongs to, intersected with the farms they can access.

GET

/me/pinned-farms

List the caller's My Farms (pinned ∪ consultant-assigned) in the current organisation

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/me/pinned-farms" \
  -H "x-farmwalk-api: pat.your_personal_token" \
  -H "X-Organisation-Id: your-org-uuid"

Responsejson

{
  "items": [
    {
      "farm": {
        "id": "farm-uuid",
        "name": "Green Acres Farm",
        "slug": "green-acres-farm",
        "sbiNumber": "123456789",
        "cphNumber": "12/345/6789",
        "totalHectares": 150.5,
        "parcelCount": 12,
        "isActive": true
      },
      "pin": {
        "pinId": "pin-uuid",
        "pinnedAt": "2026-04-12T08:30:00Z"
      },
      "consultantRole": "LEAD"
    },
    {
      "farm": { "id": "other-farm-uuid", "name": "Riverside Farm" },
      "pin": { "pinId": "pin-uuid-2", "pinnedAt": "2026-05-01T11:00:00Z" },
      "consultantRole": null
    },
    {
      "farm": { "id": "third-farm-uuid", "name": "Hilltop Farm" },
      "pin": null,
      "consultantRole": "ASSISTANT"
    }
  ],
  "total": 3
}

POST

/me/pinned-farms

Toggle a pin on a farm. Pinning is the only user-controllable input to My Farms — consultant role is org-admin. Requires write scope.

Request Body

Parameter	Type	Required	Description
farmId	uuid	Yes	UUID of the farm to pin or unpin. Must be in the current organisation and accessible to the caller.

Example Requestbash

curl -X POST "https://api.farmwalk.app/api/v1/public/me/pinned-farms" \
  -H "x-farmwalk-api: pat.your_personal_token" \
  -H "X-Organisation-Id: your-org-uuid" \
  -H "Content-Type: application/json" \
  -d '{"farmId":"farm-uuid"}'

Response (newly pinned, status 201)json

{
  "action": "pinned",
  "pin": {
    "id": "pin-uuid",
    "userId": "user-uuid",
    "organisationId": "org-uuid",
    "farmId": "farm-uuid",
    "pinnedAt": "2026-05-27T14:02:11Z"
  },
  "farmStillInMyFarms": true,
  "consultantRole": null
}

Response (already pinned, now unpinned, status 200)json

{
  "action": "unpinned",
  "pinId": "pin-uuid",
  "farmStillInMyFarms": false,
  "consultantRole": null
}

Response (unpinned but still a consultant, status 200)json

{
  "action": "unpinned",
  "pinId": "pin-uuid",
  "farmStillInMyFarms": true,
  "consultantRole": "LEAD"
}

GET

/me/team-farms

List the caller's Team Farms — farms sharing a label with the user

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/me/team-farms" \
  -H "x-farmwalk-api: pat.your_personal_token" \
  -H "X-Organisation-Id: your-org-uuid"

Responsejson

{
  "items": [
    {
      "id": "farm-uuid",
      "name": "Green Acres Farm",
      "slug": "green-acres-farm",
      "sbiNumber": "123456789",
      "cphNumber": "12/345/6789",
      "totalHectares": 150.5,
      "parcelCount": 12,
      "isActive": true,
      "address": { "line1": "Green Acres", "town": "Farmington", "postcode": "EX1 2AB" },
      "coordinates": { "lat": 50.7236, "lng": -3.5275 },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "labelIds": ["label-uuid-1", "label-uuid-2"]
}

Agreements

Access scheme agreements across the UK's agricultural compliance landscape — including the major government schemes, assurance schemes, and buyer-led regenerative programmes.

Supported scheme types (schemeType filter values):

SFI — Sustainable Farming Incentive (England)
CS — Countryside Stewardship (England)
SFS — Sustainable Farming Scheme (Wales)
AECS — Agri-Environment Climate Scheme (Scotland)
FFERMIO_BRO — Ffermio Bro Capital Grants (Wales)
NVZ — Nitrate Vulnerable Zone obligations
RED_TRACTOR — Red Tractor assurance
LEAF_MARQUE — LEAF Marque sustainable assurance
HEALTH_SAFETY — Health & Safety compliance
WILDFARMED — Wildfarmed regenerative grain programme
BOORTMALT_MALTING_GROWERS — Boortmalt malting-growers buyer-led scheme

GET

/farms/{farmId}/agreements

List all agreements for a farm

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Max items to return (1-100, default 20)
offset	integer	No	Items to skip for pagination
schemeType	string	No	Filter by scheme: SFI, CS, RED_TRACTOR, HEALTH_SAFETY
status	string	No	Filter by status: PENDING, ACTIVE, EXPIRED, CANCELLED
includeItems	boolean	No	Include agreement items (default true)

Example Requestbash

curl -X GET "https://api.farmwalk.app/api/v1/public/farms/farm-uuid/agreements?schemeType=SFI&status=ACTIVE" \
  -H "x-farmwalk-api: pk.your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

Responsejson

{
  "items": [
    {
      "id": "agreement-uuid",
      "farmId": "farm-uuid",
      "schemeType": "SFI",
      "reference": "SFI-2024-001234",
      "name": "SFI 2024 Agreement",
      "status": "ACTIVE",
      "startDate": "2024-01-01",
      "endDate": "2026-12-31",
      "complianceScore": 85.5,
      "totalAnnualValue": 12500.00,
      "items": [
        {
          "id": "item-uuid",
          "catalogCode": "SAM1",
          "itemType": "action",
          "status": "active",
          "progress": 0.75,
          "areaHa": 50.0,
          "calculatedPayment": 1100.00,
          "landAssignments": [
            {
              "id": "assignment-uuid",
              "landFeatureId": "parcel-uuid",
              "areaHa": 25.0,
              "status": "assigned",
              "landFeature": {
                "id": "parcel-uuid",
                "name": "Field 1 - Home Meadow",
                "featureType": "parcel"
              }
            }
          ]
        }
      ]
    }
  ],
  "total": 3,
  "limit": 20,
  "offset": 0,
  "hasMore": false
}

GET

/farms/{farmId}/agreements/{agreementId}

Get full agreement details including payments, inspections, and declarations

Vault Uploads

Upload evidence files (photos, audio, documents) to the farm vault. Files are automatically processed for transcription and AI analysis.

Upload Flow

1. Start Upload

2. Upload to S3

3. Finish Upload

POST

/farms/{farmId}/vault/upload/start

Initiate upload, returns presigned S3 URL

Request Body

Parameter	Type	Required	Description
filename	string	Yes	Original filename
mimeType	string	Yes	MIME type (e.g., image/jpeg)
sizeBytes	integer	Yes	File size in bytes (max 500MB)
folderId	uuid	No	Target folder UUID

Step 1: Start Uploadbash

curl -X POST "https://api.farmwalk.app/api/v1/public/farms/farm-uuid/vault/upload/start" \
  -H "x-farmwalk-api: pk.your_api_key" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "field-evidence.jpg",
    "mimeType": "image/jpeg",
    "sizeBytes": 2048576
  }'

Responsejson

{
  "uploadId": "upload-uuid",
  "presignedUrl": "https://s3.eu-west-2.amazonaws.com/bucket/...",
  "s3Key": "orgs/org-id/farms/farm-id/vault/upload-uuid.jpg",
  "s3Bucket": "farmwalk-vault-prod",
  "fileType": "image",
  "expiresIn": 1800,
  "expiresAt": "2024-06-15T12:30:00Z"
}

Step 2: Upload to S3bash

curl -X PUT "$presignedUrl" \
  -H "Content-Type: image/jpeg" \
  --data-binary @field-evidence.jpg

POST

/farms/{farmId}/vault/upload/finish

Complete upload, creates database record

Step 3: Finish Uploadbash

curl -X POST "https://api.farmwalk.app/api/v1/public/farms/farm-uuid/vault/upload/finish" \
  -H "x-farmwalk-api: pk.your_api_key" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadId": "upload-uuid",
    "s3Key": "orgs/org-id/farms/farm-id/vault/upload-uuid.jpg",
    "filename": "field-evidence.jpg",
    "mimeType": "image/jpeg",
    "sizeBytes": 2048576,
    "location": {
      "latitude": 50.7236,
      "longitude": -3.5275,
      "accuracy": 10
    },
    "category": "evidence",
    "tags": ["sfi", "sam1", "soil-assessment"]
  }'

POST

/farms/{farmId}/vault/upload/{uploadId}/renew

Renew presigned URL if expired before upload completed

Presigned URL Expiry

Presigned URLs expire after 30 minutes. If the URL expires before you complete the upload, use the /renew endpoint to get a fresh URL.

Public API Documentation

Farm Data

Agreements

Vault Uploads

Base URL

Authentication

Organisation API Keys + JWT

Personal Access Tokens (PATs)

Token Scopes

Option 1: API Key + JWT Headers

Authentication Flow

Login Request

Verify OTP

Response

Option 2: Personal Access Token Headers

Organisation API Keys

How to create an API key

Key Format

Revoking Keys

Personal Access Tokens (PATs)

How to create a Personal Access Token

Token Format

Using PATs

List Your Organisations

Token Expiration

Revoking PATs

Rate Limiting

Rate Limit Headers

Farms

Query Parameters

My Farms & Teams

Request Body

Agreements

Query Parameters

Vault Uploads

Upload Flow

Request Body

Command Palette

Public API Documentation

Farm Data

Agreements

Vault Uploads

Base URL

Authentication

Organisation API Keys + JWT

Personal Access Tokens (PATs)

Token Scopes

Option 1: API Key + JWT Headers

Authentication Flow

Login Request

Verify OTP

Response

Option 2: Personal Access Token Headers

Organisation API Keys

How to create an API key

Key Format

Revoking Keys

Personal Access Tokens (PATs)

How to create a Personal Access Token

Token Format

Using PATs

List Your Organisations

Token Expiration

Revoking PATs

Rate Limiting

Rate Limit Headers

Farms

Query Parameters

My Farms & Teams

Request Body

Agreements

Query Parameters

Vault Uploads

Upload Flow

Request Body