# trefle-api: a botanical JSON API and the Rails app behind it

> Trefle is a JSON REST API over plant species, built as a Rails application with a React admin front end bundled through webpack. The public repository doubles as the issue tracker and the roadmap, and the API is documented separately at docs.trefle.io, with the AGPL v3 covering the code.

**treflehq/trefle-api** — 🍀 Trefle is a botanical JSON REST API for plants species, allowing you to search and query over all the registered species, and build the next gardening apps and farming robots.

- Repository: https://github.com/treflehq/trefle-api
- Website: https://trefle.io
- Stars: 586 · Forks: 54
- Language: Ruby
- License: AGPL-3.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/treflehq-trefle-api

## What the repository is for, and what it is not

Trefle is a botanical JSON REST API for plant species, allowing you to search and query over all the registered species, and build the next gardening apps and farming robots. The homepage is treffle.io.

The surprising part of the README is the section titled Why this repo, because it does not describe the feature set. The purpose of this repository is to offer an accessible channel to collect issues and ideas, and to show the public roadmap, the current topics and features to come.

That is an unusual thing for the main repository of a running service to be, and it tells you where to look for the API itself. The website, the getting started guide, the API documentation and the ideas and features board are all separate links, and the boards are GitHub project boards under the treflehq organisation, one for issues and one for ideas.

The contribution model is therefore deliberately narrow. A bug goes to a bug report template and lands on the issues board. A feature idea goes to a feature request template and lands on the ideas and features board. In both cases the maintainers say they will look at it and check it is not a duplicate before moving it along.

What you get as a user of the API is the endpoint reference at docs.trefle.io/reference, and a getting started guide at docs.trefle.io. The README does not document the endpoints, and this repository is not where you would look for them.

The topic tags tell you the domain: biodiversity, database, plants, plants-species, farming-robots, gardening-apps, api-rest, and the hacktoberfest tag, which explains the contribution templates and the idea board.

## A Rails API with a React admin in the same repository

The code is a Ruby on Rails application, and the top level entries describe the whole stack.

There is a config.ru and a Procfile.dev, so the app runs with a rack server, plus a Rakefile, a Gemfile and Gemfile.lock, a Dockerfile and an entrypoint.sh, and the standard Rails directories: app/, config/, db/, lib/, bin/, spec/, public/, storage/, log/, vendor/ and scripts/.

The front end is a separate piece inside the same repository, and the package.json says so plainly with the name trefle-admin and the private flag set. It is a React application, with react and react-dom at 16.13.1, bundled by webpack 5 with babel-loader and sass-loader, and styled with bulma and sass rather than a utility CSS framework. Charts come from britecharts with d3-selection, and the markdown rendering is react-markdown with react-syntax-highlighter.

The build is unusual in one respect, and it is a Rails pattern worth understanding if you deploy it. The dependencies are mostly open ranges, using >= rather than pinned versions, and the resolutions block pins a set of transitive packages that are known to break, including several schema-utils and ajv combinations and a css-loader and semver pairing. That is the standard workaround for a dependency tree that cannot be locked cleanly, and it means the lockfile and the resolutions block have to be read together.

The toolchain is pinned through volta, with node at 24.18.0 and yarn at 1.22.22, and there is a .nvmrc and a .ruby-version alongside it.

There is also a documentation layer inside the repository that explains the domain, and the file names are the guide: COLUMNS.md, CORRECTION_SPECS.md, TAXONOMY.md, DEPLOYMENT.md and CITATION.cff. The taxonomy document is the one that matters if you are building a plant app, because the shape of the hierarchy is what your queries depend on.

## The container build, and the ordering that breaks if you change it

The Dockerfile is the most instructive file in the repository, because it encodes several Rails deployment lessons.

The base is ruby:3.4-alpine, with a large set of system packages installed: the build toolchain, PostgreSQL client libraries, ImageMagick with its dev headers, libxml2, libxslt, zlib, curl, tzdata, yaml, bash, git, and nodejs with yarn. The presence of ImageMagick and libxslt tells you the application processes images and parses XML, which for a botanical database means plant photos and data imports.

The bundle step is worth reading carefully. The Gemfile and Gemfile.lock are copied and installed first, on their own, with bundle install --without development test, four jobs, three retries and the vendor path, before the application source is copied. That is the standard layer-caching pattern, and it means the gem layer is rebuilt only when the lockfile changes.

The yarn step follows the same pattern, and the comment explains why jsbundling-rails runs yarn build as part of assets:precompile. But the key comment is the one about ordering:

The build of the JS bundles happens BEFORE assets:precompile, because sprockets indexes app/assets/builds when the app boots, so the files must already exist, and running yarn build through the precompile enhancement leaves them out of the sprockets manifest.

That is a genuine footgun. The comment elsewhere says the build must happen before assets:precompile so that the files are already there, and if you reorder the Dockerfile the app boots with a missing manifest.

Two more details. SECRET_KEY_BASE_DUMMY=1 is set for the precompile step, which lets the app boot for precompilation without the real production secret, and that secret is only injected at runtime. And the cleanup line removes node_modules, storage, the yarn cache, the log, the markdown files, the test, kube, frontend and spec directories, and the config/master.key file, so the final image contains no development files and no key file.

## Releases, deployment and the project boards

The release history is recent and moves fast. Version 2.1.0 was published on 2026-09-04, 2.2.0 the same day later, and 2.3.0 on 2026-09-05, with the last push on 2026-10-20. Three releases inside two days suggests a coordinated release rather than incremental feature drops, and the 2.x line is the current major version.

Deployment is documented in DEPLOYMENT.md, which the README describes as the release, canary, switch and rollback runbook. That phrasing matters. The presence of a canary stage and a switch and rollback procedure says the service is deployed as a live multi environment system, not a single server, and the runbook is written for the people who operate it rather than for someone who wants to run their own instance.

The CI badge points at a GitHub Actions workflow, and the repository also carries a .github/ directory, a .agents/ directory, and an .env.local.example and a .env.test alongside a .env, which is a mix you see in an application that is deployed rather than published as a library.

The performance badges are the only indirect quality signal in the README, and they point at Skylight, a Rails APM service, showing request per minute and problem counts. The Ruby code is checked with rubocop, with a .rubocop.yml and a .rubocop_todo.yml, and the .todo file is the usual pattern for a codebase that has a large set of existing offences recorded rather than fixed.

The API is licensed under AGPL v3, with a LICENSE.md at the root, and that has a specific implication. AGPL covers network use, so if you modify the API and run it as a service that others reach over the network, the source has to be offered. The data itself is the other half of the question, and the repository does not state a separate data licence, so anyone building a commercial product on the API should settle both points before shipping.

## Conclusion

Trefle suits a developer building a gardening app, a plant identifier or a farming robot who needs a structured plant taxonomy to query rather than a pile of text to parse. It does not suit you as a self hosted service you can pick up and run, because the repository's stated purpose is to collect issues and ideas and to show the public roadmap, and the deployment notes are a release runbook for the maintainers rather than a setup guide. Before you build on it, read the reference documentation at docs.trefle.io to see what the endpoints actually cover, and check the AGPL v3 terms against how you intend to distribute whatever you build on top of it.

## FAQ

### What is the Trefle API?

It is a botanical JSON REST API for plant species, allowing you to search and query over all the registered species, with the aim of building gardening apps and farming robots. The reference documentation is at docs.trefle.io/reference.

### What is the trefle-api repository for, if not the API documentation?

The stated purpose is to offer an accessible channel to collect issues and ideas, and to show the public roadmap with the current topics and features to come. Bug reports and feature requests go to issue templates and then onto GitHub project boards for issues and for ideas.

### What stack does the trefle-api project use?

A Ruby on Rails application with a React 16 admin front end named trefle-admin, bundled with webpack 5 and sass, styled with bulma, and running in a ruby:3.4-alpine container with nginx-style static serving through Rails. The front end dependencies are mostly open ranges with a resolutions block pinning known problem packages.

### What licence is Trefle under?

AGPL v3, with a LICENSE.md in the repository root. Because AGPL covers network use, running a modified version as a service reachable over the network carries source disclosure obligations, so anyone building a commercial product on top of it should confirm the terms for both the code and the data.

## Sources

- [License: AGPL-3.0](https://github.com/treflehq/trefle-api/blob/master/LICENSE)
- [Project website](https://trefle.io)
- [README](https://github.com/treflehq/trefle-api/blob/master/README.md)
- [Releases](https://github.com/treflehq/trefle-api/releases)
- [treflehq/trefle-api on GitHub](https://github.com/treflehq/trefle-api)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/treflehq-trefle-api