Skip to main content

2.6.0

· 3 min read
André Aubin
André Aubin
Trefle Core Team

The API reference has been updated. This release also carries the performance and hardening work from the last two weeks — including one change to pagination that clients paging very deep need to know about.

The reference is up to date​

docs.trefle.io/reference is now 2.6.0.

Fifteen endpoints existed with no entry in the reference at all:

  • GET /api/v1 and GET /api/v1/me
  • GET /api/v1/species/:id/facts — the provenance trail behind every trait value, shipped in 2.5.0 and invisible in the reference ever since
  • GET /api/v1/species/:id/corrections and GET /api/v1/corrections/mine
  • the ten nested collections: genus/:id/species, families/:id/genus, plants/:id/species, distributions/:id/species and their record endpoints

All 45 routes the API answers are now documented. sources[].licence and licence_url — the attribution work from 2.5.0 — are in the published schema, as are complete_data, completion_ratio and synonyms[].sources.

A few things the reference had been getting wrong:

  • Submitting a correction was documented for one record type; the API accepts species, plant and plants.
  • edible_part did not list tubers among its accepted values.
  • soil_texture was documented as an enumeration of French terms. It is an integer scale from 0 (clay) to 10 (rock), and always has been.

These last two came out of fixing the generator that builds the correction field table, which had been silently dropping every multi-value field — duration, the colours, the months, edible_part — leaving them as empty rows.

Deep pagination is capped at page 2,500​

This one can change what your client sees. Requests past page 2,500 (an offset of 50,000 rows) now return a documented 400 instead of an increasingly slow answer.

Postgres has to walk and discard every row before a deep offset, so these requests were degrading quietly: offset 49,980 measured at 26.8ms, offset 200,000 at 109.5ms and climbing. Failing fast with a clear error beats serving a page that takes longer every time you go further.

If you are paging that deep to enumerate the database, that is what the cap is telling you: filter the collection down instead. Proper cursor pagination is the real answer and it is coming, but it replaces page-number links with an opaque cursor — a change to the public pagination contract that deserves its own release rather than being slipped into this one.

Searching by name got about 3,500× faster​

Looking a species up by scientific name could not use the index on that column, because the lookup lowercases it and the index was on the raw value. Every name lookup was a sequential scan over 489,358 rows.

Measured on a full production-size restore: 464.9ms before, 0.131ms after.

Two more query fixes landed with it. Rendering a single plant was making six separate queries for the same rows, one per taxonomic rank; it now makes one. And the species menu in the explore section was making one query per linked source, doubled by the check deciding whether to show the section at all — those three paths alone accounted for 7,654 grouped error-tracking events since October 2025.