Making requests

Every request goes to a versioned base URL and comes back in the same JSON envelope: a data payload, pagination links, and a meta block. Learn the envelope once and every endpoint reads the same way.

Base URL

The current base URL is https://api.floracodex.com/v2 (API version v2). Every path in these guides is relative to it, so /species means https://api.floracodex.com/v2/species.

Your first request

Fetch a page of species with your project API key. This is the simplest credential and the one most integrations use; the Authentication guide covers the others.

curl https://api.floracodex.com/v2/species \
  -H "Authorization: ApiKey $FLORACODEX_API_KEY"

const res = await fetch("https://api.floracodex.com/v2/species", {
  headers: { Authorization: `ApiKey ${process.env.FLORACODEX_API_KEY}` },
});
const body = await res.json();

import os, requests

res = requests.get(
    "https://api.floracodex.com/v2/species",
    headers={"Authorization": f"ApiKey {os.environ['FLORACODEX_API_KEY']}"},
)
body = res.json()

The response envelope

A collection response wraps three things: the records in data, the page's navigation in links, and the counts in meta.

{
  "data": [
    {
      "id": "...",
      "common_name": "pedunculate oak",
      "scientific_name": "Quercus robur",
      "slug": "quercus-robur",
      "rank": "species"
    }
  ],
  "links": {
    "self": "/v2/species?page=1",
    "next": "/v2/species?page=2",
    "last": "/v2/species?page=25"
  },
  "meta": { "total": 481, "per_page": 20, "current_page": 1, "last_page": 25 }
}

A few things worth knowing up front:

• Page size is fixed at 20. There is no page-size parameter; page through with ?page=. meta.last_page is ceil(total / 20).
• The links are ready to use. Each is a relative path that already carries your query and sort, so you can hand links.next straight back to your client without rebuilding the URL. prev is omitted on the first page, next on the last, and the set thins to just self when there are no results.
• A single record uses the same envelope. A detail response (https://api.floracodex.com/v2/species/{id}) wraps the one record in data too, with a meta carrying last_modified and, where they apply, images_count, sources_count, and synonyms_count. If you came from v1, this is the change to watch: v1 returned the bare record at the top level; v2 always wraps it. Read response.data.

For the specifics of any one endpoint, its parameters, query options, and the exact response schema, see the API reference.

Tracing a request

Every response, success or error, carries an FC-Request-Id header. Log it. If you need to ask us about a specific call, that id lets us find the exact request. The Errors guide covers the failure envelope.

Versioning