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 the exact search term.

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

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

Params

These params need to be provided as a JSON object and send with content-type: application/json.

(required) scientific_name<string>: the exact scientifc name of a species or variety (case sensitive!).

(required) type<enum>: one of Plant or Variety to find exact species or varieties.

(optional) name<string>: the exact name of a species or variety. Mostly used for filtering the exact variety.

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!