API docs by Redocly

Farmable API (2.0)

Download OpenAPI specification:

Farmable Support: [email protected] URL: https://farmable.tech

Welcome to the Farmable API v2.0

Farmable API enables seamless integration between Farmable’s farm management platform and external systems such as ERP software, farm machinery, and other agricultural tools.

What’s New in Version 2.0

  • Continued support for core retrieval endpoints (farms, fields, sales).
  • Enhancements for Spanish farms: regulatory IDs and compliance fields.
  • New endpoints for spray and fertilizer job logs, aligned with EU regulatory demands.
  • Read access to logged work and harvest: applied products with dosage, what was growing on each field, harvested quantities and who picked.

About Farmable

Farmable is a mobile-first farm management solution built by farmers for farmers. It simplifies daily operations with AI-powered features:

  • Crop identification & pest detection
  • Effortless record-keeping for sprays, fertilizers, and harvests
  • Secure data storage & traceable reporting

Why Farmable?

  • Integration-ready: connect with ERP, machinery, and compliance systems.
  • Compliance-focused: automate reporting to government portals.
  • Scalable: supports global operations with local regulations.
  • Sustainability: reduce administrative overhead and ensure regulatory traceability.

For support, contact [email protected].

Partner API

The Farmable API is a RESTful service built on OpenAPI principles. It provides read-only access for partners (e.g., companies connected via the Farmable app) and now extends to write capabilities for job submissions.

Key Features

  • Data Scope: farms, fields, crops, logged work, harvest, teams, timesheets, sales
  • Rate Limiting: 60 requests/minute per API key
    • Check headers: Rate-Limit-Remaining, Rate-Limit-Retry-After-Seconds
  • Data Formats:
    • JSON for requests and responses
    • Dates follow ISO 8601 (e.g., 2026-07-11T17:15:00Z)
  • Security:
    • API key authentication, sent in the api-key header
    • HTTPS required for all calls
  • Error Handling:
    • Standard HTTP codes (200 OK, 400 Bad Request, 401 Unauthorized, 429 Too Many Requests)
    • JSON error messages carrying an errorId to quote when reporting a problem

Retrieve causes

Retrieve causes to which partner has access.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve crop varieties

Retrieve crop varieties to which partner has access. Each entry belongs to a field (fieldId) and references its crop (cropId).

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve crops

Retrieve crops to which partner has access.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve equipments

Retrieve equipments to which partner has access.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve farm members

Retrieve farm members to which partner has access.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve farms

Retrieve farms to which partner has access.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create fertilizer job

Create a new fertilizer job for fields.

Authorizations:
api-key
Request Body schema: application/json
required
completedDate
string <date> ^\d{4}-\d{2}-\d{2}$

Job completion date

documentOnSewageSludge
boolean

Document on sewage sludge (required for Spanish locations)

farmId
required
integer <int32>

Farm ID

fields
required
Array of integers <int32> [ items <int32 > ]

List of field IDs

memberId
required
integer <int32>

Member ID

startDate
required
string <date> ^\d{4}-\d{2}-\d{2}$

Job start date

required
Array of objects (TreatmentInputV1)

List of treatments to apply

Responses

Request samples

Content type
application/json
{
  • "completedDate": "2024-01-16",
  • "documentOnSewageSludge": true,
  • "farmId": 0,
  • "fields": [
    ],
  • "memberId": 0,
  • "startDate": "2024-01-15",
  • "treatments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0
}

Retrieve fields

Retrieve fields to which partner has access.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve harvest records

Retrieve harvest logged on the farms you have access to: date, the fields it came from and what was growing on them, the quantity in the unit the farm counts in, and the quality grade the farm assigned. This is the only place harvest appears — /v1/jobs deliberately excludes it, so there is nothing to reconcile between the two. A farm may log harvest on its own or from a job; in the second case jobId is set, for reference, though that job is not returned by /v1/jobs. Filter by harvest date with dateFrom and dateTo, same rules as /v1/jobs: send both or neither, at most 366 days apart, any past season. Paging works the same way too.

Authorizations:
api-key
query Parameters
dateFrom
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateFrom=2026-01-01

Earliest harvest date (inclusive), ISO format. Send together with dateTo.

dateTo
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateTo=2026-12-31

Latest harvest date (inclusive), ISO format. At most 366 days after dateFrom.

page
integer >= 0
Default: 0

Zero-based page number. Only meaningful together with pageSize.

pageSize
integer [ 1 .. 1000 ]
Example: pageSize=500

Records per page, 1 to 1000. Omit to receive the whole window in one response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve job records

Retrieve completed and planned activity logged on the farms you have access to: activity type, farm and field IDs, dates, applied products with dosage and unit, the assigned team member, notes and status. Filter by completion date (inclusive, ISO dates). Omitting both bounds returns the last year. The 366-day limit applies to how wide the window is, not how far back it reaches: any past season can be retrieved, one request per season — dateFrom=2024-01-01&dateTo=2024-12-31 is fine. Always send both bounds. Sending only dateFrom leaves the upper bound at today, which for an older start date exceeds the limit and returns 400 rather than quietly narrowing the window. Paging is opt-in: pass pageSize to receive pages ordered by descending job id (a stable key, so records never move between pages) and keep requesting until a page comes back shorter than pageSize. Omit pageSize and the whole window arrives in one response. Harvest is not included here: it has quantities, pickers and its own records, and is served by /v1/harvests. Nothing about a harvest is lost by its absence from this endpoint.

Authorizations:
api-key
query Parameters
dateFrom
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateFrom=2024-01-01

Earliest completion date (inclusive), ISO format. Send together with dateTo.

dateTo
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateTo=2024-12-31

Latest completion date (inclusive), ISO format. At most 366 days after dateFrom.

page
integer >= 0
Default: 0

Zero-based page number. Only meaningful together with pageSize.

pageSize
integer [ 1 .. 1000 ]
Example: pageSize=500

Records per page, 1 to 1000. Omit to receive the whole window in one response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve job weather

Retrieve weather conditions (temperature, wind, precipitation) logged against a specific job. Farmer-logged weather takes precedence over automatically recorded weather (see the source field).

Authorizations:
api-key
path Parameters
jobId
required
integer >= 1
Example: 42

Job ID.

Responses

Response samples

Content type
application/json
{
  • "jobId": 0,
  • "loggedAt": "string",
  • "precipitation": 0.1,
  • "source": "string",
  • "temperature": 0.1,
  • "windDirection": "string",
  • "windSpeed": 0.1
}

Retrieve justifications

Retrieve justifications to which partner has access.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve sales

Retrieve sales to which partner has access.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create spray job

Create a new spray job for fields.

Authorizations:
api-key
Request Body schema: application/json
required
causeIds
required
Array of strings <uuid> [ items <uuid > ]

List of cause IDs

completedDate
string

Job completion date

equipmentId
required
integer <int32>

Equipment ID

farmId
required
integer <int32>

Farm ID

fields
required
Array of integers <int32> [ items <int32 > ]

List of field IDs

justificationIds
required
Array of strings <uuid> [ items <uuid > ]

List of justification IDs

memberId
required
integer <int32>

Member ID

startDate
required
string

Job start date

required
Array of objects (TreatmentInputV1)

List of treatments to apply

Responses

Request samples

Content type
application/json
{
  • "causeIds": [
    ],
  • "completedDate": "2024-01-16",
  • "equipmentId": 0,
  • "farmId": 0,
  • "fields": [
    ],
  • "justificationIds": [
    ],
  • "memberId": 0,
  • "startDate": "2024-01-15",
  • "treatments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0
}

Retrieve team members

Retrieve all team members to which partner has access.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve teams

Retrieve all teams to which partner has access.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve timesheets

Retrieve all timesheet records including date, start time, end time and duration in hours. Records without an end time belong to team members that are still clocked in. Records without a team member ID were recorded by the team lead for the whole team. Optionally filter by start date (inclusive, ISO date).

Authorizations:
api-key
query Parameters
dateFrom
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateFrom=2026-01-01

Earliest start date (inclusive), ISO format.

dateTo
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateTo=2026-01-31

Latest start date (inclusive), ISO format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve clock-in times

Retrieve clock-in (start) times per team member. Entries without a team member ID were recorded by the team lead for the whole team. Optionally filter by date (inclusive, ISO date).

Authorizations:
api-key
query Parameters
dateFrom
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateFrom=2026-01-01

Earliest clock-in date (inclusive), ISO format.

dateTo
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateTo=2026-01-31

Latest clock-in date (inclusive), ISO format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve clock-out times

Retrieve clock-out (end) times per team member. Only records that have been clocked out are returned. Entries without a team member ID were recorded by the team lead for the whole team. Optionally filter by clock-in date (inclusive, ISO date).

Authorizations:
api-key
query Parameters
dateFrom
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateFrom=2026-01-01

Earliest clock-in date (inclusive), ISO format.

dateTo
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateTo=2026-01-31

Latest clock-in date (inclusive), ISO format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve timesheet tasks

Retrieve tasks completed during a timesheet entry (e.g. Spray, Other). Optionally filter by timesheet start date (inclusive, ISO date).

Authorizations:
api-key
query Parameters
dateFrom
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateFrom=2026-01-01

Earliest timesheet start date (inclusive), ISO format.

dateTo
string <date> ^\d{4}-\d{2}-\d{2}$
Example: dateTo=2026-01-31

Latest timesheet start date (inclusive), ISO format.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve treatments

Retrieve treatments to which partner has access. Optionally filter by field IDs.

Authorizations:
api-key
query Parameters
fieldIds
string^$|^[1-9][0-9]*(,[1-9][0-9]*)*$
Example: fieldIds=12,45,78

CSV of field IDs. If omitted or empty, returns all treatments.

Responses

Response samples

Content type
application/json
[
  • {
    }
]