Developers
Open by design
Public code, documented APIs, open reference data and an MCP server: everything you need to connect your tool to Ekylibre, Lexicon and Aiffel.
REST · OpenAPI 3
The Ekylibre API
Ekylibre exposes a JSON REST API (version 2), described in OpenAPI. Each farm is a separate data space (a tenant), selected by the subdomain or the X-Tenant header. You authenticate with a user-bound token obtained from POST /tokens.
Resources (excerpt)
- cultivable_zones
- fields
- products
- animals, equipment, plants…
- variants
- catalogue variants
- interventions
- interventions and their records
- activity_productions
- productions
- input_totals
- input totals
- farm_profiles · farm_accountancy
- farm profile and accounts per season
- lexicon/registered_phytosanitary_*
- registered plant protection products
# 1. Get a token
curl -X POST https://YOUR_INSTANCE/api/v2/tokens \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "password": "…"}'
# 2. List the farm's fields
curl https://YOUR_INSTANCE/api/v2/cultivable_zones \
-H "Authorization: simple-token you@example.com YOUR_TOKEN"Replace YOUR_INSTANCE with the address of your Ekylibre. The token can also be sent as query parameters (access_email and access_token).
JSON · CSV · PostgreSQL
Lexicon in JSON, CSV or SQL
Every Lexicon page also exists in JSON and CSV: add .json or .csv to its address. Most of the data is open, with no key. Datasets reserved for OSFarm members need an API key, sent in the Authorization: Bearer or X-API-Key header. The data can be read from other sites (CORS enabled).
PostgreSQL packages: each dataset is a versioned package you can load into your own database. Versions, licences and source dates are listed in the catalogue.
curl https://lexicon.osfarm.org/phytosanitary/products.json
# Datasets reserved for OSFarm members: add your key
curl https://lexicon.osfarm.org/… \
-H "Authorization: Bearer YOUR_KEY"{
"title": "Produits",
"table": {
"columns": { "name": "Nom", "firm": "Firme", "type": "Type", … },
"rows": [ { "name": { "@type": "Text", "value": "…" }, … }, … ]
},
"credit": { "provider": { "value": "ANSES" }, "license": { … }, "date": { … } },
"page": 1, "items-per-page": 150, "total-pages": …,
"formats": { … }
}Model Context Protocol
Plug an AI assistant into 623M records
Lexicon exposes an MCP server (JSON-RPC over HTTP). A compatible AI assistant can search and cross-reference the datasets, with their sources: identify a plot, look up a plant protection product, find a municipality or a business.
Add this configuration to your MCP client. The server name (lexicon here) is up to you; where the file lives depends on the client.
{
"mcpServers": {
"lexicon": {
"type": "http",
"url": "https://lexicon.osfarm.org/mcp"
}
}
}Ruby on Rails
A connector is a plugin
Ekylibre’s connectors are standalone extensions: Rails engines packaged as Ruby gems, each in its own ekylibre-<name> repository.
One repository, one gem
The plugin declares a Rails::Engine and is added to Ekylibre’s Gemfile.
An integration
It describes the connection to the third-party service (credentials, check) and the syncs to run, for example daily.
Background jobs
Data is fetched by jobs, then turned into Ekylibre objects: interventions, readings, accounting entries.
Extension points
The plugin adds its views, translations and buttons to existing screens.
A published release
As soon as a tag is published on GitHub, the connector appears on this site.
# Gemfile.plugins (loaded by Ekylibre’s Gemfile)
gem 'ekylibre-samsys',
git: 'https://github.com/ekylibre/ekylibre-samsys.git',
tag: '0.7.0'module EkylibreSamsys
class Engine < ::Rails::Engine
initializer :ekylibre_samsys_i18n do |app|
app.config.i18n.load_path += Dir[root.join('config', 'locales', '**', '*.yml')]
end
initializer :ekylibre_samsys_integration do
Samsys::SamsysIntegration.run every: :day do
SamsysFetchUpdateCreateJob.perform_now(…)
end
end
initializer :add_samsys_partials do
Ekylibre::View::Addon.add(:extensions_content_top,
'backend/ride_sets/sync_samsys_toolbar', to: 'backend/ride_sets#index')
end
end
endAbridged excerpt from the ekylibre-samsys plugin.
The 10 stable plugins
Active repositories with at least one published release. Version and licence read from GitHub when the site is built.
| Repository | Purpose | Version | Licence |
|---|---|---|---|
| ekylibre-ednotif | Livestock identification | 1.0.0 | not stated |
| ekylibre-banking | Bank statements | 0.1.0 | not stated |
| ekylibre-hajimari | Onboarding assistant | 0.11.0 | AGPL-3.0 |
| ekylibre-planning | Planning | 1.0.0 | MIT |
| ekylibre-samsys | Connected machinery | 0.7.0 | not stated |
| ekylibre-previmeteo | Connected weather devices | 0.2.1 | not stated |
| ekylibre-weenat | Weather stations and sensors | 0.1.1 | not stated |
| ekylibre-cap2020 | Connected traps | 1.0.0 | not stated |
| ekylibre-viti | Ekyviti | v3.18.0-63.0 | MIT |
| ekylibre-baqio | Wine sales and logistics | 0.5.1 | AGPL-3.0 |
Build your connector
- 1
Start from an existing plugin close to your case: Samsys for machinery, Weenat for sensors, Baqio for sales software.
- 2
Describe the integration: authentication with your service and a connection test.
- 3
Write the data fetch in a job, and map it to Ekylibre’s models using the Onoma and Lexicon nomenclatures.
- 4
Add tests, documentation and translations (at least French and English).
- 5
Publish a first release (tag), then announce it on Discord.
Licences
| Component | Licence |
|---|---|
| Ekylibre (core) | GNU AGPL v3 |
| Plugins and connectors | Stated in each repository (see the table above) |
| Lexicon (code) | Source code open on GitHub |
| Lexicon data | Each dataset keeps its source licence, stated in the catalogue (for example Licence Ouverte 2.0) |
The AGPL keeps Ekylibre’s code free, including when it is offered as an online service: any modified version made available to users must publish its code.
Contribute
Ekylibre’s first commit dates from September 2008: 23,192 commits and 39 contributors to date. Report a bug, suggest an improvement or new data: all contributions are welcome.