Table of contents

Intro

On our mission to give everyone interested the knowledge on how to grow useful plants for a food garden, medicinal or regenerative uses, we want the database to be used wherever it can help. This is why we provide an API for developers to add plant data to their applications and services.

Getting access

Currently the API is in a very early stage and is used mostly internally. If you want to have access, please reach out to hello at permapeople dot org with your user account’s email and we will provide you with an API key pair.

Also if you have any questions or feedback, don’t hesitate to reach out to us.

Endpoint

All following requests must be sent to and will return valid JSON (content-type: application/json; charset=utf-8).

https://permapeople.org/api

Authentication

To access all API endpoints header-based authentication must be provided for every request. To authenticate, add the following HTTP headers to your request:

x-permapeople-key-id: YOUR_KEY_ID
x-permapeople-key-secret: YOUE_KEY_SECRET

List plants

List plants ordered by their internal ID. It will return 100 plants as an array called plants.

GET https://permapeople.org/api/plants

# Response

{
  "plants" : [
    {<Plant>},
    {<Plant>},
    {<Plant>}}
    ...
  ]
}

Params

This param needs to be provided as an GET param in the URL, for example ?last_id=100.

(optional) last_id<int>: Works like a cursor and returns only plants after this id. Should be used for paging through the whole list.

Search plants

Returns a list of plants matching a full text search. This means it will find similar named plants too. Make sure to check the plant returned if its the right one you are looking for.

POST https://permapeople.org/api/search

# Response

{
  "plants" : [
    {<Plant>},
    {<Plant>},
    {<Plant>}}
    ...
  ]
}

Params

The param needs to be provided as a JSON object and send with content-type: application/json.

(required) q<string>: search the whole database for this term. Much like the search on the website.

Get a single plant

Returns a plant object for an exact ID.

GET https://permapeople.org/api/plants/<id>

# Response

{
   "id" : 101,
   "type" : "Plant",
   "scientific_name" : "Morus alba",
   "name" : "White mulberry",
   "version" : 10,
   "description" : "Young leaves are edible.",
   "link" : "/plants/morus-alba-white-mulberry",
   "parent_id" : null,
   "slug" : "morus-alba-white-mulberry",
   "updated_at" : "2022-07-30T08:17:26.658Z",
   "created_at" : "2020-08-11T16:09:47.485Z",
   "data" : [
      {
         "key" : "Edible",
         "value" : "true"
      },
      {
         "key" : "Growth",
         "value" : "Medium"
      },
      {
         "key" : "Water requirement",
         "value" : "Moist"
      },
      {
         "key" : "Light requirement",
         "value" : "Full sun, partial sun/shade"
      },
      {
         "key" : "USDA Hardiness zone",
         "value" : "3-9"
      },
      {
         "key" : "Layer",
         "value" : "Trees"
      },
      {
         "key" : "Soil type",
         "value" : "Light (sandy), medium, heavy (clay)"
      },
      {
         "key" : "Family",
         "value" : "Moraceae"
      },
      {
         "key" : "Edible parts",
         "value" : "Fruit, inner bark, leaves"
      }
   ]
}

Create a plant

To create za plant, do a POST request with a valid plant object. A valid plant object has as a minimum a scientific_name, name and note. On success, it will return the whole plant object or will show you an error what went wrong.

POST https://permapeople.org/api/plants

# Response

{
   "id" : 101,
   "type" : "Plant",
   "scientific_name" : "Morus alba",
   "name" : "White mulberry",
   "version" : 10,
   "description" : "Young leaves are edible.",
   "link" : "/plants/morus-alba-white-mulberry",
   "parent_id" : null,
   "slug" : "morus-alba-white-mulberry",
   "updated_at" : "2022-07-30T08:17:26.658Z",
   "created_at" : "2020-08-11T16:09:47.485Z",
   "data" : [
      {
         "key" : "Edible",
         "value" : "true"
      },
      {
         "key" : "Growth",
         "value" : "Medium"
      },
      {
         "key" : "Water requirement",
         "value" : "Moist"
      },
      {
         "key" : "Light requirement",
         "value" : "Full sun, partial sun/shade"
      },
      {
         "key" : "USDA Hardiness zone",
         "value" : "3-9"
      },
      {
         "key" : "Layer",
         "value" : "Trees"
      },
      {
         "key" : "Soil type",
         "value" : "Light (sandy), medium, heavy (clay)"
      },
      {
         "key" : "Family",
         "value" : "Moraceae"
      },
      {
         "key" : "Edible parts",
         "value" : "Fruit, inner bark, leaves"
      }
   ]
}

Params

This param needs to be provided as a JSON object and send with content-type: application/json.

(required) scientific_name<string>: The scientific name of a plant, if in doubt, use wikipedia to find the correct and current name. (required) name<string>: The common name. Here use the most common english name. (required) note<string>: Describe the action you did and what sources you used. (optional) type<enum>: Can be Plant or Variety. If Variety is used, parent_id is required and needs to be an existing plant id.

Update a plant

To update a plant, do a PUT request with the plant object fields you want to change to its own URL. On success, it will return the whole plant object or will show you an error what went wrong.

PUT https://permapeople.org/api/plants/101

# Response

{
   "id" : 101,
   "type" : "Plant",
   "scientific_name" : "Morus alba",
   "name" : "White mulberry",
   "version" : 10,
   "description" : "Young leaves are edible.",
   "link" : "/plants/morus-alba-white-mulberry",
   "parent_id" : null,
   "slug" : "morus-alba-white-mulberry",
   "updated_at" : "2022-07-30T08:17:26.658Z",
   "created_at" : "2020-08-11T16:09:47.485Z",
   "data" : [
      {
         "key" : "Edible",
         "value" : "true"
      },
      {
         "key" : "Growth",
         "value" : "Medium"
      },
      {
         "key" : "Water requirement",
         "value" : "Moist"
      },
      {
         "key" : "Light requirement",
         "value" : "Full sun, partial sun/shade"
      },
      {
         "key" : "USDA Hardiness zone",
         "value" : "3-9"
      },
      {
         "key" : "Layer",
         "value" : "Trees"
      },
      {
         "key" : "Soil type",
         "value" : "Light (sandy), medium, heavy (clay)"
      },
      {
         "key" : "Family",
         "value" : "Moraceae"
      },
      {
         "key" : "Edible parts",
         "value" : "Fruit, inner bark, leaves"
      }
   ]
}

Params

This param needs to be provided as a JSON object and send with content-type: application/json.

(required) <Plant>: the partial plant object with changed fields only. This object needs to have at minimum one changed field, the current version as int (optimistic locking) and a note as string describing the change.

Errors

If the API throws an error, it will always be an appropriate HTTP status code and valid JSON in the following format:

{
  "error": "short description",
  "msg": "longer description on what to do"
}

Help & Feedback

If you have any questions or need help using the API, feel free to reach out per mail (hello at) or on twitter. 🌱✌️ Happy coding!