API Documentation v2.0 API Docs

Introduction

Agrilyst provides a REST compatible API interface that allows users to send metric data into the system for sensors. This documentation is for the API version 2.0. It may be incompatible with previous or future API versions. Please be sure you are using the correct documentation.

API Account

API accounts are per user. By using your access token, you will be able to use the API.

Authentication

The API requires HTTP Basic Authentication for every request. All requests must be sent over HTTPS. Authentication is accomplished with a user and token pair. User is the email address that you used to create your account and token is the API token that can be found on the API keys page.

Note: API Tokens have been shortened for the purposes of this documentation. Your real API token will be longer.

A user with an email address example@agrilyst.com and an API token of 75AFDB82 will use the following command:

curl -u example@agrilyst.com:75AFDB82 https://api.agrilyst.com/api/v2/

URL Encoding

To use URL encoding, use the following format:

https://user:token@api.agrilyst.com/api/v2/

Because the user value is an email address, it has to be escaped in order to form a valid URL. The @ sign is represented by the %40 entity. For example:

curl https://example%40agrilyst.com:75AFDB82@api.agrilyst.com/api/v2/

Note: cURL automatically converts the @ to a %40 if you use the -u option, but not if you put authentication in the URL directly.

GET /health - Health Check

This check is the only API check that does not require authentication. The health check endpoint returns a 200 OK if the API is up and working. Any other status indicates a failure in the API.

Command:

curl \
  -u example@agrilyst.com:75AFDB82 \
  https://api.agrilyst.com/api/v2/health

Successful Return:

{"health":"OK"}

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

GET /version - Version

This check returns the API version. The version endpoint returns a 200 OK and the version number.

Command:

curl \
  -u example@agrilyst.com:75AFDB82 \
  https://api.agrilyst.com/api/v2/version

Successful Return:

{"version":"2.0"}

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

GET /facilities - List Facilities

This endpoint displays all available facilities for your organization.

curl \
  -u example@agrilyst.com:75AFDB82 \
  https://api.agrilyst.com/api/v2/facilities

Successful Return:

[{
  "id": 2,
  "facility_type": "greenhouse",
  "name": "Facility Alpha",
  "postal_code": 90210,
  "size": 5000,
  "size_type": "sqft",
  "time_zone": "UTC"
}, {
  "id": 1,
  "facility_type": "vertical",
  "name": "Facility Beta",
  "postal_code": 14222,
  "size": 10000,
  "size_type": "sqmt",
  "time_zone": "EST"
}]

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

GET /sensor_models - List Sensor Models

This endpoint displays the manufacturer/make of different sensor models that Agrilyst supports. Use the name value when making a sensor in the Create Sensor endpoint.

curl \
  -u example@agrilyst.com:75AFDB82 \
  https://api.agrilyst.com/api/v2/sensor_models

Successful Return:

[
  {
    id: 0,
    name: "priva"
  },
  {
    id: 1,
    name: "link4iponic"
  },
  {
    id: 2,
    name: "wadsworth"
  },
  {
    id: 3,
    name: "avidz"
  },
  {
    id: 4,
    name: "motorleaf"
  },
  {
    id: 99,
    name: "other"
  }
]

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

POST /sensors - Create Sensor

Makes a new sensor in a facility. Check the List Sensor Models endpoint for acceptable inputs for the model parameter.

Optionally, provide a visible flag set to false if you want to hide a sensor from being shown in the dashboard. By default visible is `true`, and sensors are shown in reports and the dashboard.

curl \
  -u example@agrilyst.com:75AFDB82 \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "sensor": {
      "name": "Greenhouse 1 Sensor",
      "model": "priva",
      "facility_id": 98765
    },
  }'
  https://api.agrilyst.com/api/v2/sensors

Successful Return:

Status Code(s): 201

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

GET /sensors - List Sensors

This endpoint displays all available sensors for your organization.

curl \
  -u example@agrilyst.com:75AFDB82 \
  https://api.agrilyst.com/api/v2/sensors

Successful Return:

[{
  "id": 1,
  "name": "Sensor 1",
  "model": "priva",
  "visible": "true",
  "status": "active"
}, {
  "id": 2,
  "name": "Sensor 2",
  "model": "wadsworth",
  "visible": "true",
  "status": "active"
}]

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

GET /sensors/:id - Show Sensor

Get data for a specific sensor in a facility.

curl \
  -u example@agrilyst.com:75AFDB82 \
  https://api.agrilyst.com/api/v2/sensors/123456

Successful Return:

{
  "id": 1,
  "name": "Sensor 1",
  "model": "priva",
  "visible": "true",
  "status": "active"
}

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

PUT /sensors/:id - Update Sensor

Updates a sensor with new information. In this example, the sensor ID to update is 123456. Fields that can be changed are name, model, and visible. Check the List Sensor Models endpoint for acceptable inputs for the model parameter.

curl \
  -u example@agrilyst.com:75AFDB82 \
  -X PUT \
  -d '{
    "sensor": {
      "name": "Greenhouse 1 Sensor",
    },
  }'
  https://api.agrilyst.com/api/v2/sensors/123456

Successful Return:

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

DELETE /sensors/:id - Remove Sensor

Removes the sensor with the given ID (in this example, 123456).

curl \
  -u example@agrilyst.com:75AFDB82 \
  -X DELETE
  https://api.agrilyst.com/api/v2/sensors/123456

Successful Return:

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

POST /sensors/:sensor_id/sensor_metrics - Create Sensor Metric

Creates a new sensor metric under the given sensor ID. Check the List Sensor endpoint to get the list of sensors for your organization.

curl \
  -u example@agrilyst.com:75AFDB82 \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "sensor": {
      "metric": "CO2 Percentage",
      "metric_units": "%",
      "description": "Track carbon dioxide in Greenhouse 1",
    }
  }'
  https://api.agrilyst.com/api/v2/sensors/56789/sensor_metrics

Successful Return:

Status Code(s): 201

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

GET /sensors/:sensor_id/sensor_metrics - List Sensor Metrics

Note: This endpoint is accessible via GET /metrics but this URL is deprecated and will be removed.

This endpoint displays all available metrics for a sensor. You must specify a sensor ID in the request. It returns an array of JSON hashes representing each sensor metric.

curl \
  -u example@agrilyst.com:75AFDB82 \
  https://api.agrilyst.com/api/v2/sensors/1/sensor_metrics

Successful Return:

[{
  "id": 1,
  "metric": "meas grh temp",
  "metric_units": "°C",
  "description": "Zone Greenhouse Temperature",
  "status": "active"
}, {
  "id": 2,
  "metric": "meas CO2",
  "metric_units": "ppm",
  "description": "Zone CO2 Concentration",
  "status": "active"
}]

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

GET /sensors/:sensor_id/sensor_metrics/:id - Show Sensor Metric

Get data for a specific sensor metric under a sensor.

curl \
  -u example@agrilyst.com:75AFDB82 \
  https://api.agrilyst.com/api/v2/sensors/56789/sensor_metrics/54321

Successful Return:

{
  "id": 54321,
  "metric": "CO2 Percentage",
  "metric_units": "%",
  "description": "Track carbon dioxide in Greenhouse 1",
  "status": "active"
}

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

PUT /sensors/:sensor_id/sensor_metrics/:id - Update Sensor Metric

Updates a sensor metric with new information. Fields that can be changed are metric, metric_units, and description.

curl \
  -u example@agrilyst.com:75AFDB82 \
  -X PUT \
  -d '{
    "sensor_metric": {
      "description": "Track CO2 in Greenhouse 2"
    },
  }'
  https://api.agrilyst.com/api/v2/sensors/123456/sensor_metrics/54321

Successful Return:

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

DELETE /sensors/:sensor_id/sensor_metrics/:id - Remove Sensor Metric

Removes the sensor metric with the given ID (in this example, 54321) under a specific sensor.

curl \
  -u example@agrilyst.com:75AFDB82 \
  -X DELETE
  https://api.agrilyst.com/api/v2/sensors/123456/sensor_metrics/54321

Successful Return:

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

POST /sensor_data - Save Sensor Data

Note: This endpoint is accessible via POST /metrics but this URL is deprecated and will be removed.

This endpoint accepts a POST method and saves data recordings for a sensor. It expects three values: a sensor metric ID, a timestamp, and a value. It returns a 200 OK with a status for each metric.

curl \
  -u example@agrilyst.com:75AFDB82 \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "metrics": [
      { "id": 2,
       "value": 42,
       "time": 1471979056
      },
      { "id": 2,
       "value": 55,
       "time": 1471979057
      }
    ]
  }'
  https://api.agrilyst.com/api/v2/metrics

Successful Return:

Status Code(s): 200, list of metrics and status

{
  "status": 200,
  "message": {
    "id=2, time=1471979056, value=42": "saved",
    "id=2, time=1471979057, value=55": "saved"
  }
}

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

GET /tanks - List Tanks

This endpoint displays all available metrics for tanks. You can specify a tank ID in the request. It returns a JSON array.

curl \
  -u example@agrilyst.com:75AFDB82 \
  https://api.agrilyst.com/api/v2/tanks

Successful Return:

[{
  "id": 1,
  "name": "Tank A",
  "capacity": 7641,
  "status": "active"
}, {
  "id": 2,
  "name": "Tank B",
  "capacity": 6644,
  "status": "active"
}, {
  "id": 3,
  "name": "Tank C",
  "capacity": 8526,
  "status": "active"
}]

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

GET /tank_metrics - List Tank Metrics

This endpoint displays all available metrics for a tank. It returns a JSON array of common and organization specific tank metrics.

curl \
  -u example@agrilyst.com:75AFDB82 \
  https://api.agrilyst.com/api/v2/tank_metrics

Successful Return:

[{
  "id": 1,
  "name": "pH",
  "units": "numeric"
}, {
  "id": 2,
  "name": "Temperature",
  "units": "degrees"
}, {
  "id": 3,
  "name": "EC",
  "units": "numeric"
}]

Status Code(s): 200

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code

POST /tank_reading - Save Tank Reading

This endpoint accepts a POST method and saves a reading for a tank. A reading is comprised of a tank_reading object, and several metric objects. It returns a 200 OK with a status for each metric.

curl \
  -u example@agrilyst.com:75AFDB82 \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "tank_reading": {
      "tank_id": 2,
      "time": 1486142194
      "overwrite": true
    },
    "metrics": [
      { "id": 2,
        "value": 4.5
      },
      { "id": 3,
        "value": 50
      }
    ]
  }'
  https://api.agrilyst.com/api/v2/tank_reading

Successful Return:

Status Code(s): 200, list of metrics and status

{
  "status": 200,
  "message": {
    "id=2, time=1471979056, value=42": "saved",
    "id=2, time=1471979057, value=55": "saved"
  }
}

Failed Return:

Status Code(s): Timeout, Any 4xx or 5xx status code