NAV
CURL Arduino Python Circuitpython Ruby

Adafruit IO HTTP API

The Adafruit IO HTTP API provides access to your Adafruit IO data from any programming language or hardware environment that can speak HTTP. The easiest way to get started is with an Adafruit Learning Guide and a simple Internet of Things capable device like the Feather Huzzah or a more complicated one like the PyPortal.

About the API Docs

This API documentation is hosted on GitHub Pages and is available on GitHub.

Spotted something incorrect or broken? Click here to file an issue on the repository

For questions or comments visit the Adafruit IO Feedback page or the #help-with-adafruit-io channel on the Adafruit Discord server.

Authentication

Your Adafruit IO Key is used to restrict or grant access to your data. The key is unique and covers every use of the Adafruit IO API for your account. You can access your key on any IO page by clicking on the golden key icon:

Or by clicking on the "View Adafruit IO Key" link in the small screen drop-down menu while you're visiting Adafruit IO.

Now you can copy the key directly from the information form that pops up, or copy one of the code samples that includes your key and username together.

Including an Adafruit IO Key

curl -H "X-AIO-Key: b780002b85d6411ca0ad9f9c60195f72" \
    https://io.adafruit.com/api/v2/test_username/feeds

# or

curl "https://io.adafruit.com/api/v2/test_username/feeds?x-aio-key=b780002b85d6411ca0ad9f9c60195f72"

require 'adafruit/io'

username = "test_username"
api_key = "b780002b85d6411ca0ad9f9c60195f72"
api = Adafruit::IO::Client.new key: api_key, username: username

When making HTTP requests to Adafruit IO, you can include the API key as a query parameter named x-aio-key or as a request header named X-AIO-Key. In both cases, "X-AIO-Key" is case insensitive.

NOTE: if you regenerate your AIO key, your old key will be immediately invalidated, so you'll have to replace it in any scripts or sketches where it is in use.

NOTE: it is a best practice to avoid including your API key in the URL as a query parameter. Some situations may require this, but try to avoid it if you can.

Client Libraries

We have lots of client libraries to help you get started with your project:

Note: The following two libraries use V1 of the Adafruit API which have been deprecated.

They're all open source, so if they don't already do what you want, you can fork them and add any feature you'd like.

Rate Limiting

Adafruit IO imposes a rate limit on all data modification APIs to prevent excessive load on the service. If a user performs too many data create, update, or delete actions in a short period of time then the system will start rejecting requests.

If you have a free Adafruit IO Account, the rate limit is 30 data points per minute.

If you have upgraded to an Adafruit IO Plus account, the base rate limit is 60 data points per minute.

If you exceed this limit, a notice will be sent to the {username}/throttle MQTT topic. You can subscribe to the topic if you wish to know when the Adafruit IO rate limit has been exceeded for your user account. This limit applies to all Data record modification actions over the HTTP and MQTT APIs, so if you have multiple devices or clients publishing data, be sure to delay their updates enough that the total rate is below your account limit.

One data record modification is any action that creates, updates, or deletes a single Data record.

A best practice is to only save or modify data within the hot part of your code loop. You want to handle authentication and any other API requests (creating/getting feeds, etc) before you start your main code loop where you save data.

We have general API throttles to ensure the API isn't being improperly used either by accident or for nefarious purposes. This throttle level is higher than any data rate limit throttles, but you may run into it if your code isn't optimized. One example would be if in the main loop of your code you are not only sending data, but also authenticating, retrieving all feeds, or anything else that doesn't involve saving or modifying data to a feed. In that scenario, you would be hitting the API 3x more times than necessary, and could get throttled, even if you're saving data within your allotted rate limit.

Pagination

Adafruit IO’s API returns at most 1000 data points at a time. To get more data if your feed is over 1000 data points, you’ll need to “paginate” the data.

What does this mean?

When you perform an HTTP data GET query, the results are always sorted newest-to-oldest and include 5 X-Pagination-* headers and the Link header field in the response. You can see an example of the headers on the right.

Pagination Headers

X-Pagination-Count: 250
X-Pagination-Limit: 250
X-Pagination-Total: 83027
X-Pagination-Start:
X-Pagination-End: 2019-05-03T17:35:13.637+0000
Link: <https://io.adafruit.com/api/v2/abachman/feeds/humidity/data?end_time=2019-05-03+17%3A35%3A13+UTC&limit=250>;rel="next", <https://io.adafruit.com/api/v2/abachman/feeds/humidity/data?before=eyJ0aW1lX2lkIjoiMEU1M043N0syUjdUR1Y3MEY3UjJFUVlRVlkiLCJmZWVkX2lkIjoiNjE3MzcwLjAifQ%3D%3D&end_time=2019-05-03+17%3A35%3A13+UTC&limit=250>

Whenever Limit and Count are both 1000 and Total is more than 1000, that’s evidence that more data is available. That's where the Link (Link) header comes in.

For Adafruit IO Link always contains at least one URL inside angle brackets, that's the link to the page of data you are currently looking at. In the example above, the first URL is https://io.adafruit.com/api/v2/abachman/feeds/example.counter-1/data?end_time=2019-05-02+22%3A33%3A22+UTC&limit=250. The first URL given in the Link header can be used to request the same data set again in the future. Even if your original request didn't include any parameters, the Link URL will include a start_time parameter that reflects the time at which you made the request. This is how we can make sure you can request the same data repeatedly.

The example Link value above also includes a next section: rel="next", <https://io.adafruit.com/api/v2/abachman/feeds/example.counter-1/data?before=eyJ0aW1lX2lkIjoiMEU0V0RWSk1SNlgxNUgxV0FSR0c2SzFIRUgiLCJmZWVkX2lkIjoiNzMuMCJ9&end_time=2019-05-02+22%3A33%3A22+UTC&limit=250>. The rel="next" part means the URL that follows is a link to the next page of data. As long as there is more data available, the Link header will include a rel="next" URL. It updates on each request, so you can page through data by making a request, parsing the Link header to get a next URL, and then using that URL to make another request. If your initial request includes end_time, start_time, or limit parameters, those parameters will be included in the rel="next" URL. Note that since data request are always sorted by descending created_at date (newest first, oldest last), the next page of data is always the next older page of data.

When visualized on a timeline, the concept of pagination looks like this:

Note that long running, frequently updated feeds could have more than a hundred pages of data. In the example above, with a limit of 250 records, it would take 330 requests to get all the data. If you make requests without a small delay in between, you will hit a rate limit. To avoid this, watch for 429 HTTP error responses and handle them in code by adding a 30 second timeout between requests and request the largest size permitted, right now that's 1000 records.

If your goal is to store and study the data offline, though, you would be better off downloading the whole feed using the Download button built into Adafruit IO on the web.

You can find an example of a paginated data downloading script in Python at this link. Stop by the forums or Discord if you have more questions about getting your Data out of IO.

Data

Data is at the heart of Adafruit IO. Everything your device measures and records becomes a data point on an Adafruit IO Feed.

You can create, read, update, or delete data records. Every CREATE, UPDATE, or DELETE action on a data record counts against your rate limit.

Data points belong to feeds, so every Data API call starts with a Feed URL.

Note that there are endpoints for submitting multiple data points to a feed, and multiple feed values to a group, see feeds/{feed_key}/batch and groups/{groupname}/data endpoints.

Create Data

HTTP Request

POST/api/v2/{username}/feeds/{feed_key}/data

# Send new data with a value of 42
$ curl -F 'value=42' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data

# Send new data with a value of 42 and include optional location metadata
curl -H "Content-Type: application/json" -d '{"value": 42, "lat": 23.1, "lon": "-73.3"}'  -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data

# Adafruit IO Python

# Send data to feed feed_name with a value of 42
io.send_data(location_feed.key, '42')

# Send data to feed `feed_name` with a value of 42 and include optional location metadata
metadata = {'lat': 40.726190,
            'lon': -74.005334,
            'ele': -6,
            'created_at': None}
io.send_data(feed_name.key, data_value, metadata)

# Adafruit IO CircuitPython
# Send data to feed feed_name with a value of 42
io.send_data(location_feed['key'], '42')

# Send data to feed `feed_name` with a value of 42 and include optional location metadata
metadata = {'lat': 40.726190,
            'lon': -74.005334,
            'ele': -6,
            'created_at': None}
io.send_data(feed_name['key'], data_value, metadata)

// Send data to Feed `feedName` with value of 42
feedName->save(42);

// Send data to Feed `feedName` with value 42 and include optional location metadata
feedName->save(42, latValue, lonValue, eleValue);

Response Sample:

{
  "id": "string",
  "value": "string",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

New data

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Body Parameters

Parameter Type Required Description
Request Body object true Data record (datum) including a value field (required) and optionally including: lat, lon, ele (latitude, longitude, and elevation values), and created_at (a date/time string).

Get Feed Data

HTTP Request

GET/api/v2/{username}/feeds/{feed_key}/data

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data

# get the most recent value
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data?limit=1

# get the most recent value before a particular time
$ curl -H "X-AIO-Key: {io_key}" "https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data?limit=1&end_time=2019-05-05T00:00Z"

# get all values in a date range
$ curl -H "X-AIO-Key: {io_key}" "https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data?start_time=2019-05-04T00:00Z&end_time=2019-05-05T00:00Z"

// Not implemented in Adafruit IO Arduino

# Not implemented in Adafruit IO Python

# Not implemented in Adafruit IO CircuitPython

Response Sample:

[
  {
    "id": "string",
    "value": "string",
    "feed_id": 0,
    "feed_key": "string",
    "created_at": "datetime",
    "location": {},
    "lat": 0.0,
    "lon": 0.0,
    "ele": 0.0,
    "created_epoch": 0,
    "expiration": "datetime"
  }
]

Response Parameters

An array of zero or more data points.

This API is paginated.

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Query Parameters

Parameter Type Required Description
start_time string false Start time for filtering, returns records created after given time. Use ISO8601 formatted dates.
end_time string false End time for filtering, returns records created before give time. Use ISO8601 formatted dates.
limit integer false Limit the number of records returned.
include csv string false List of Data record fields to include in response records. Acceptable values are: value, lat, lon, ele, id, and created_at.
before string false System generated token used to produce the next page of data. See The Link Header for details.

Chart Feed Data

HTTP Request

GET/api/v2/{username}/feeds/{feed_key}/data/chart

# Query the chart API for the previous hour.
$ curl -H "X-AIO-Key: {io_key}" 'https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data/chart?hours=1'

Response Sample:

{
  "feed": {
    "id": 0,
    "key": "string",
    "name": "string"
  },
  "parameters": {
    "start_time": "2019-02-28T16:17:09Z",
    "end_time": "2019-04-29T16:17:09Z",
    "resolution": 120,
    "hours": 1440,
    "field": "avg"
  },
  "columns": ["date", "avg"],
  "data": [
    [ "2019-03-01T14:00:00Z", "62.579827586206896" ],
    [ "2019-03-02T18:00:00Z", "64.94642857142857" ],
    [ "...", "..."]
  ]
}

A JSON record containing chart data and the parameters used to generate it. This API will automatically calculate resolution based on the optimal time slice for the given start_time to end_time range or hours value given.

Charts on io.adafruit.com use this API with only the hours parameter to render charts on dashboards and feed pages.

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Query Parameters

Parameter Type Required Description
start_time string false Start time for filtering, returns records created after given time. Use ISO8601 formatted dates.
end_time string false End time for filtering, returns records created before give time. Use ISO8601 formatted dates.
resolution int false Size of aggregation slice in minutes. Must be one of: 1, 5, 10, 30, 60, 120, 240, 480, or 960
hours int false Number of hours to include in the chart. This value is ignored if start_time and end_time are given.
field string false Aggregate field to return. Must be one of: avg, sum, val, min, max, val_count
raw boolean false Force raw chart data to be returned. Not compatible with field or resolution parameters. Use 1 or true for boolean true value.

Create Multiple Data Records

HTTP Request

POST/api/v2/{username}/feeds/{feed_key}/data/batch

$ curl -H "Content-Type: application/json" -d @batch.json -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data/batch

# Adafruit IO Python
data_list = [Data(value=50), Data(value=33)]
aio.send_batch_data(feed_name.key, data_list)

# Not implemented in Adafruit IO CircuitPython

Response Sample:

[
  {
    "id": "string",
    "value": "string",
    "feed_id": 0,
    "feed_key": "string",
    "created_at": "datetime",
    "location": {},
    "lat": 0.0,
    "lon": 0.0,
    "ele": 0.0,
    "created_epoch": 0,
    "expiration": "datetime"
  }
]

New data

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Body Parameters

Parameter Type Required Description
data array true A collection of data records including value (required) and optionally including: lat, lon, ele (latitude, longitude, and elevation values), and created_at (a date/time string).

Get Previous Data

HTTP Request

GET/api/v2/{username}/feeds/{feed_key}/data/previous

# Adafruit IO Python
data = aio.receive_previous(feed.key)

Response Sample:

{
  "id": "string",
  "value": "string",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

Data response

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Query Parameters

Parameter Type Required Description
include string false List of Data record fields to include in response as comma separated list. Acceptable values are: value, lat, lon, ele, id, and created_at.

Get Next Data

HTTP Request

GET/api/v2/{username}/feeds/{feed_key}/data/next

# Adafruit IO Python
data = aio.receive_next(feed.key)

Response Sample:

{
  "id": "string",
  "value": "string",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

Data response

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Query Parameters

Parameter Type Required Description
include string false List of Data record fields to include in response as comma separated list. Acceptable values are: value, lat, lon, ele, id, and created_at.

Get Last Data

HTTP Request

GET/api/v2/{username}/feeds/{feed_key}/data/last

Response Sample:

{
  "id": "string",
  "value": "string",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

Data response

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Query Parameters

Parameter Type Required Description
include string false List of Data record fields to include in response as comma separated list. Acceptable values are: value, lat, lon, ele, id, and created_at.

Get First Data

HTTP Request

GET/api/v2/{username}/feeds/{feed_key}/data/first

# Adafruit IO Python
data = aio.receive(feed.key)

Response Sample:

{
  "id": "string",
  "value": "string",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

Data response.

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Query Parameters

Parameter Type Required Description
include string false List of Data record fields to include in response as comma separated list. Acceptable values are: value, lat, lon, ele, id, and created_at.

Get Most Recent Data

HTTP Request

GET/api/v2/{username}/feeds/{feed_key}/data/retain

Response Sample:

"string",0.0,0.0,0.0

CSV string in value,lat,lon,ele format. The lat, lon, and ele values are left blank if they are not set.

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Get Data Point

HTTP Request

GET/api/v2/{username}/feeds/{feed_key}/data/{id}

# Adafruit IO Python
data = aio.receive(feed_name.key)

# Adafruit IO CircuitPython
data = aio.receive(feed_name['key'])

Response Sample:

{
  "id": "string",
  "value": "string",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

Data response

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key
id string true

Query Parameters

Parameter Type Required Description
include string false List of Data record fields to include in response as comma separated list. Acceptable values are: value, lat, lon, ele, id, and created_at.

Update Data Point

HTTP Request

PUT/api/v2/{username}/feeds/{feed_key}/data/{id}

Response Sample:

{
  "id": "string",
  "value": "string",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

Updated Data

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key
id string true

Body Parameters

Parameter Type Required Description
Request Body object true Data record (datum) including a value field (required) and optionally including: lat, lon, ele (latitude, longitude, and elevation values), and created_at (a date/time string).

Delete Data Point

HTTP Request

DELETE/api/v2/{username}/feeds/{feed_key}/data/{id}

# Adafruit IO Python
aio.delete(feed_name.key, data_id)

# Adafruit IO CircuitPython
aio.delete_data(feed_name['key'], data_id)

Response Sample:

Deleted Group successfully

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key
id string true

Create Group Data

HTTP Request

POST/api/v2/{username}/groups/{group_key}/data

Response Sample:

{
  "id": "string",
  "value": "string",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

New data

Path Parameters

Parameter Type Required Description
username string true a valid username string
group_key string true

Body Parameters

Parameter Type Required Description
group_feed_data object true A record with the feeds property, containing a collection of records with key and value properties.

Example for group_feed_data in the body is as follows: { feeds: [ { key: string, value: string }, ... ], created_at: string (optional), location: { lat: number, lon: number, ele: number } (optional)}

Get Data for Group's Feed

HTTP Request

GET/api/v2/{username}/groups/{group_key}/feeds/{feed_key}/data

# Send new data with a value of 42 to the group's feeds as json
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/data.json -d '{"feeds":[{"key":"{feed_key}","value":42}]}'

Response Sample:

{
  "id": "string",
  "value": "string",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

An array of data

Path Parameters

Parameter Type Required Description
username string true a valid username string
group_key string true
feed_key string true a valid feed key

Create Data in a Group's Feed

HTTP Request

POST/api/v2/{username}/groups/{group_key}/feeds/{feed_key}/data

Response Sample:

{
  "id": "string",
  "value": "string",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

New data

Path Parameters

Parameter Type Required Description
username string true a valid username string
group_key string true
feed_key string true a valid feed key

Body Parameters

Parameter Type Required Description
Request Body object true Data record (datum) including a value field (required) and optionally including: lat, lon, ele (latitude, longitude, and elevation values), and created_at (a date/time string).

Create Data in a Group's Feed

HTTP Request

POST/api/v2/{username}/groups/{group_key}/feeds/{feed_key}/data/batch

Response Sample:

[
  {
    "id": "string",
    "value": "string",
    "feed_id": 0,
    "feed_key": "string",
    "created_at": "datetime",
    "location": {},
    "lat": 0.0,
    "lon": 0.0,
    "ele": 0.0,
    "created_epoch": 0,
    "expiration": "datetime"
  }
]

New data

Path Parameters

Parameter Type Required Description
username string true a valid username string
group_key string true
feed_key string true a valid feed key

Body Parameters

Parameter Type Required Description
data array true A collection of data records including value (required) and optionally including: lat, lon, ele (latitude, longitude, and elevation values), and created_at (a date/time string).

Feeds

Feeds are the core of the Adafruit IO system. The feed holds metadata about the data you push to Adafruit IO. This includes settings for whether the data is public or private, what license the stored data falls under, and a general description of the data. The feed also contains the sensor data values that get pushed to Adafruit IO from your device.

You will need to create one feed for each unique source of data you send to Adafruit IO.

You can create, read, update, or delete feeds. Every CREATE, UPDATE, or DELETE action on a feed record counts against your rate limit.

There are also endpoints for submitting multiple data points to a feed, or multiple feed values to a group, see feeds/{feed_key}/batch and groups/{groupname}/data endpoints.

All Feeds

HTTP Request

GET/api/v2/{username}/feeds

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/

# Adafruit IO Python
feeds = aio.feeds()

# Not implemented in Adafruit IO CircuitPython

Response Sample:

[
  {
    "id": 0,
    "name": "string",
    "key": "string",
    "group": {
      "id": 0,
      "name": "string",
      "description": "string",
      "created_at": "string",
      "updated_at": "string"
    },
    "groups": [
      {
        "id": 0,
        "name": "string",
        "description": "string",
        "created_at": "string",
        "updated_at": "string"
      }
    ],
    "description": "string",
    "details": {
      "shared_with": null,
      "data": {
        "first": {
          "id": "string",
          "value": "string",
          "feed_id": 0,
          "group_id": 0,
          "expiration": "string",
          "lat": 0,
          "lon": 0,
          "ele": 0,
          "completed_at": "string",
          "created_at": "string",
          "updated_at": "string",
          "created_epoch": 0
        },
        "last": {
          "id": "string",
          "value": "string",
          "feed_id": 0,
          "group_id": 0,
          "expiration": "string",
          "lat": 0,
          "lon": 0,
          "ele": 0,
          "completed_at": "string",
          "created_at": "string",
          "updated_at": "string",
          "created_epoch": 0
        },
        "count": 0
      }
    },
    "unit_type": "string",
    "unit_symbol": "string",
    "history": true,
    "visibility": "string",
    "license": "string",
    "enabled": true,
    "last_value": "string",
    "status": "string",
    "status_notify": true,
    "status_timeout": 0,
    "created_at": "string",
    "updated_at": "string"
  }
]

An array of feeds

Path Parameters

Parameter Type Required Description
username string true a valid username string

Create Feed

HTTP Request

POST/api/v2/{username}/feeds

$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
    --data '{"feed": {"name": "New Feed"}}' \
    /{username}/feeds

AdafruitIO_Feed *newFeed = io.feed("newfeed");

# Adafruit IO Python
new_feed = Feed(name="newfeed")
aio.create_feed(new_feed)

# Adafruit IO CircuitPython
new_feed = io.create_new_feed('newfeed')

puts "create"
Feed = api.create_feed(name: "Feed #{SecureRandom.hex(4)}")

Response Sample:

{
  "id": 0,
  "name": "string",
  "key": "string",
  "group": {
    "id": 0,
    "name": "string",
    "description": "string",
    "created_at": "string",
    "updated_at": "string"
  },
  "groups": [
    {
      "id": 0,
      "name": "string",
      "description": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "description": "string",
  "details": {
    "shared_with": null,
    "data": {
      "first": {
        "id": "string",
        "value": "string",
        "feed_id": 0,
        "group_id": 0,
        "expiration": "string",
        "lat": 0,
        "lon": 0,
        "ele": 0,
        "completed_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "created_epoch": 0
      },
      "last": {
        "id": "string",
        "value": "string",
        "feed_id": 0,
        "group_id": 0,
        "expiration": "string",
        "lat": 0,
        "lon": 0,
        "ele": 0,
        "completed_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "created_epoch": 0
      },
      "count": 0
    }
  },
  "unit_type": "string",
  "unit_symbol": "string",
  "history": true,
  "visibility": "string",
  "license": "string",
  "enabled": true,
  "last_value": "string",
  "status": "string",
  "status_notify": true,
  "status_timeout": 0,
  "created_at": "string",
  "updated_at": "string"
}

New feed

Path Parameters

Parameter Type Required Description
username string true a valid username string

Query Parameters

Parameter Type Required Description
group_key string false

Body Parameters

Parameter Type Required Description
feed object true

Get Feed

HTTP Request

GET/api/v2/{username}/feeds/{feed_key}

$ curl -H "X-AIO-Key: {io_key}" /{username}/feeds/{feed_key}

# Adafruit IO Python
new_feed = aio.feeds('feedkey')

# Adafruit IO CircuitPython
new_feed = io.get_feed('feedkey')

puts "read?"
# ... get 404
begin
  api.feed(feedname['key'])
rescue => ex
  if ex.response.status === 404
    puts "expected error #{ex.response.status}: #{ex.message}"
  else
    puts "unexpected error! #{ex.message}"
  end
end

Response Sample:

{
  "id": 0,
  "name": "string",
  "key": "string",
  "group": {
    "id": 0,
    "name": "string",
    "description": "string",
    "created_at": "string",
    "updated_at": "string"
  },
  "groups": [
    {
      "id": 0,
      "name": "string",
      "description": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "description": "string",
  "details": {
    "shared_with": null,
    "data": {
      "first": {
        "id": "string",
        "value": "string",
        "feed_id": 0,
        "group_id": 0,
        "expiration": "string",
        "lat": 0,
        "lon": 0,
        "ele": 0,
        "completed_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "created_epoch": 0
      },
      "last": {
        "id": "string",
        "value": "string",
        "feed_id": 0,
        "group_id": 0,
        "expiration": "string",
        "lat": 0,
        "lon": 0,
        "ele": 0,
        "completed_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "created_epoch": 0
      },
      "count": 0
    }
  },
  "unit_type": "string",
  "unit_symbol": "string",
  "history": true,
  "visibility": "string",
  "license": "string",
  "enabled": true,
  "last_value": "string",
  "status": "string",
  "status_notify": true,
  "status_timeout": 0,
  "created_at": "string",
  "updated_at": "string"
}

Feed response

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Update Feed

HTTP Request

PUT/api/v2/{username}/feeds/{feed_key}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}

// Not implemented in Adafruit IO Arduino

# Not implemented in Adafruit IO Python

# Not implemented in Adafruit IO CircuitPython

Response Sample:

{
  "id": 0,
  "name": "string",
  "key": "string",
  "group": {
    "id": 0,
    "name": "string",
    "description": "string",
    "created_at": "string",
    "updated_at": "string"
  },
  "groups": [
    {
      "id": 0,
      "name": "string",
      "description": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "description": "string",
  "details": {
    "shared_with": null,
    "data": {
      "first": {
        "id": "string",
        "value": "string",
        "feed_id": 0,
        "group_id": 0,
        "expiration": "string",
        "lat": 0,
        "lon": 0,
        "ele": 0,
        "completed_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "created_epoch": 0
      },
      "last": {
        "id": "string",
        "value": "string",
        "feed_id": 0,
        "group_id": 0,
        "expiration": "string",
        "lat": 0,
        "lon": 0,
        "ele": 0,
        "completed_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "created_epoch": 0
      },
      "count": 0
    }
  },
  "unit_type": "string",
  "unit_symbol": "string",
  "history": true,
  "visibility": "string",
  "license": "string",
  "enabled": true,
  "last_value": "string",
  "status": "string",
  "status_notify": true,
  "status_timeout": 0,
  "created_at": "string",
  "updated_at": "string"
}

Updated feed

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Body Parameters

Parameter Type Required Description
feed object true

Delete Feed

HTTP Request

DELETE/api/v2/{username}/feeds/{feed_key}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}

# Adafruit IO Python
io.delete_feed(feed_name.key)

# Adafruit IO CircuitPython
io.delete_feed(feed_name['key'])

puts "delete"
api.delete_feed(feed)

Response Sample:

Deleted feed successfully

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Get Feed

HTTP Request

GET/api/v2/{username}/feeds/{feed_key}/details

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/details

// Not implemented in Adafruit IO Arduino

# Not implemented in Adafruit IO Python

# Not implemented in Adafruit IO CircuitPython

puts "read"
puts JSON.pretty_generate(api.feed_details(feed))

Response Sample:

{
  "id": 0,
  "name": "string",
  "key": "string",
  "group": {
    "id": 0,
    "name": "string",
    "description": "string",
    "created_at": "string",
    "updated_at": "string"
  },
  "groups": [
    {
      "id": 0,
      "name": "string",
      "description": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "description": "string",
  "details": {
    "shared_with": null,
    "data": {
      "first": {
        "id": "string",
        "value": "string",
        "feed_id": 0,
        "group_id": 0,
        "expiration": "string",
        "lat": 0,
        "lon": 0,
        "ele": 0,
        "completed_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "created_epoch": 0
      },
      "last": {
        "id": "string",
        "value": "string",
        "feed_id": 0,
        "group_id": 0,
        "expiration": "string",
        "lat": 0,
        "lon": 0,
        "ele": 0,
        "completed_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "created_epoch": 0
      },
      "count": 0
    }
  },
  "unit_type": "string",
  "unit_symbol": "string",
  "history": true,
  "visibility": "string",
  "license": "string",
  "enabled": true,
  "last_value": "string",
  "status": "string",
  "status_notify": true,
  "status_timeout": 0,
  "created_at": "string",
  "updated_at": "string"
}

Feed response

Path Parameters

Parameter Type Required Description
username string true a valid username string
feed_key string true a valid feed key

Groups

A Group Record

{
  "id": 0,
  "name": "string",
  "description": "string",
  "feeds": [
    {
      "id": 0,
      "name": "string",
      "key": "string",
      "group": {
        "id": 0,
        "name": "string",
        "description": "string",
        "created_at": "string",
        "updated_at": "string"
      },
      "groups": [
        {
          "id": 0,
          "name": "string",
          "description": "string",
          "created_at": "string",
          "updated_at": "string"
        }
      ],
      "description": "string",
      "unit_type": "string",
      "unit_symbol": "string",
      "history": true,
      "visibility": "string",
      "license": "string",
      "enabled": true,
      "last_value": "string",
      "status": "string",
      "status_notify": true,
      "status_timeout": 0,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "created_at": "string",
  "updated_at": "string"
}

Groups are a set of Feeds. They're used for publishing and reading to multiple feeds at a time. For example, if you are building a weather station, you would add feeds for humidity and temperature to a new weatherstation group.

You can create, read, update, or delete group records. Every CREATE, UPDATE, or DELETE action on a group record counts against your rate limit.

There is also an endpoint for submitting multiple feed values to a group, see the groups/{groupname}/data endpoint.

Get All Groups

HTTP Request

GET/api/v2/{username}/groups

$ curl -H "X-AIO-Key: {your_aio_key}" http://io.adafruit.com/api/v2/{your_username}/groups

Response Sample:

[
  {
    "id": 0,
    "name": "string",
    "description": "string",
    "feeds": [
      {
        "id": 0,
        "name": "string",
        "key": "string",
        "group": {
          "id": 0,
          "name": "string",
          "description": "string",
          "created_at": "string",
          "updated_at": "string"
        },
        "groups": [
          {
            "id": 0,
            "name": "string",
            "description": "string",
            "created_at": "string",
            "updated_at": "string"
          }
        ],
        "description": "string",
        "details": {
          "shared_with": null,
          "data": {
            "first": {
              "id": "string",
              "value": "string",
              "feed_id": 0,
              "group_id": 0,
              "expiration": "string",
              "lat": 0,
              "lon": 0,
              "ele": 0,
              "completed_at": "string",
              "created_at": "string",
              "updated_at": "string",
              "created_epoch": 0
            },
            "last": {
              "id": "string",
              "value": "string",
              "feed_id": 0,
              "group_id": 0,
              "expiration": "string",
              "lat": 0,
              "lon": 0,
              "ele": 0,
              "completed_at": "string",
              "created_at": "string",
              "updated_at": "string",
              "created_epoch": 0
            },
            "count": 0
          }
        },
        "unit_type": "string",
        "unit_symbol": "string",
        "history": true,
        "visibility": "string",
        "license": "string",
        "enabled": true,
        "last_value": "string",
        "status": "string",
        "status_notify": true,
        "status_timeout": 0,
        "created_at": "string",
        "updated_at": "string"
      }
    ],
    "created_at": "string",
    "updated_at": "string"
  }
]

An array of groups with their respective feeds .

Path Parameters

Parameter Type Required Description
username string true a valid username string

Create Group

HTTP Request

POST/api/v2/{username}/groups

$ curl -F 'name=New Group' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/

AdafruitIO_Group *group = io.group("example");

Response Sample:

{
  "id": 0,
  "name": "string",
  "description": "string",
  "feeds": [
    {
      "id": 0,
      "name": "string",
      "key": "string",
      "group": {
        "id": 0,
        "name": "string",
        "description": "string",
        "created_at": "string",
        "updated_at": "string"
      },
      "groups": [
        {
          "id": 0,
          "name": "string",
          "description": "string",
          "created_at": "string",
          "updated_at": "string"
        }
      ],
      "description": "string",
      "details": {
        "shared_with": null,
        "data": {
          "first": {
            "id": "string",
            "value": "string",
            "feed_id": 0,
            "group_id": 0,
            "expiration": "string",
            "lat": 0,
            "lon": 0,
            "ele": 0,
            "completed_at": "string",
            "created_at": "string",
            "updated_at": "string",
            "created_epoch": 0
          },
          "last": {
            "id": "string",
            "value": "string",
            "feed_id": 0,
            "group_id": 0,
            "expiration": "string",
            "lat": 0,
            "lon": 0,
            "ele": 0,
            "completed_at": "string",
            "created_at": "string",
            "updated_at": "string",
            "created_epoch": 0
          },
          "count": 0
        }
      },
      "unit_type": "string",
      "unit_symbol": "string",
      "history": true,
      "visibility": "string",
      "license": "string",
      "enabled": true,
      "last_value": "string",
      "status": "string",
      "status_notify": true,
      "status_timeout": 0,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "created_at": "string",
  "updated_at": "string"
}

New Group

Path Parameters

Parameter Type Required Description
username string true a valid username string

Body Parameters

Parameter Type Required Description
group object true

Get Group

HTTP Request

GET/api/v2/{username}/groups/{group_key}

curl -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}

Response Sample:

{
  "id": 0,
  "name": "string",
  "description": "string",
  "feeds": [
    {
      "id": 0,
      "name": "string",
      "key": "string",
      "group": {
        "id": 0,
        "name": "string",
        "description": "string",
        "created_at": "string",
        "updated_at": "string"
      },
      "groups": [
        {
          "id": 0,
          "name": "string",
          "description": "string",
          "created_at": "string",
          "updated_at": "string"
        }
      ],
      "description": "string",
      "details": {
        "shared_with": null,
        "data": {
          "first": {
            "id": "string",
            "value": "string",
            "feed_id": 0,
            "group_id": 0,
            "expiration": "string",
            "lat": 0,
            "lon": 0,
            "ele": 0,
            "completed_at": "string",
            "created_at": "string",
            "updated_at": "string",
            "created_epoch": 0
          },
          "last": {
            "id": "string",
            "value": "string",
            "feed_id": 0,
            "group_id": 0,
            "expiration": "string",
            "lat": 0,
            "lon": 0,
            "ele": 0,
            "completed_at": "string",
            "created_at": "string",
            "updated_at": "string",
            "created_epoch": 0
          },
          "count": 0
        }
      },
      "unit_type": "string",
      "unit_symbol": "string",
      "history": true,
      "visibility": "string",
      "license": "string",
      "enabled": true,
      "last_value": "string",
      "status": "string",
      "status_notify": true,
      "status_timeout": 0,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "created_at": "string",
  "updated_at": "string"
}

Group response

Path Parameters

Parameter Type Required Description
username string true a valid username string
group_key string true

Update Group

HTTP Request

PUT/api/v2/{username}/groups/{group_key}

$ curl -F 'name=Group' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}

Response Sample:

{
  "id": 0,
  "name": "string",
  "description": "string",
  "feeds": [
    {
      "id": 0,
      "name": "string",
      "key": "string",
      "group": {
        "id": 0,
        "name": "string",
        "description": "string",
        "created_at": "string",
        "updated_at": "string"
      },
      "groups": [
        {
          "id": 0,
          "name": "string",
          "description": "string",
          "created_at": "string",
          "updated_at": "string"
        }
      ],
      "description": "string",
      "details": {
        "shared_with": null,
        "data": {
          "first": {
            "id": "string",
            "value": "string",
            "feed_id": 0,
            "group_id": 0,
            "expiration": "string",
            "lat": 0,
            "lon": 0,
            "ele": 0,
            "completed_at": "string",
            "created_at": "string",
            "updated_at": "string",
            "created_epoch": 0
          },
          "last": {
            "id": "string",
            "value": "string",
            "feed_id": 0,
            "group_id": 0,
            "expiration": "string",
            "lat": 0,
            "lon": 0,
            "ele": 0,
            "completed_at": "string",
            "created_at": "string",
            "updated_at": "string",
            "created_epoch": 0
          },
          "count": 0
        }
      },
      "unit_type": "string",
      "unit_symbol": "string",
      "history": true,
      "visibility": "string",
      "license": "string",
      "enabled": true,
      "last_value": "string",
      "status": "string",
      "status_notify": true,
      "status_timeout": 0,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "created_at": "string",
  "updated_at": "string"
}

Updated group

Path Parameters

Parameter Type Required Description
username string true a valid username string
group_key string true

Body Parameters

Parameter Type Required Description
group object true

Delete Group

HTTP Request

DELETE/api/v2/{username}/groups/{group_key}

$ curl -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}

Response Sample:

"string"

Deleted Group successfully

Path Parameters

Parameter Type Required Description
username string true a valid username string
group_key string true

Create Feed in a Group

HTTP Request

POST/api/v2/{username}/groups/{group_key}/feeds

$ curl --data '{"feed": {"name": "Feed Name"}}' \
  -H "Content-Type: application/json" \
  -H "X-AIO-Key: {io_key}" \
  https://io.adafruit.com/api/v2/{username}/groups/{group_key}/feeds

// Not implemented in Adafruit IO Arduino

# Not implemented in Adafruit IO Python

# Not implemented in Adafruit IO CircuitPython

Response Sample:

{
  "id": 0,
  "name": "string",
  "key": "string",
  "group": {
    "id": 0,
    "name": "string",
    "description": "string",
    "created_at": "string",
    "updated_at": "string"
  },
  "groups": [
    {
      "id": 0,
      "name": "string",
      "description": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "description": "string",
  "details": {
    "shared_with": null,
    "data": {
      "first": {
        "id": "string",
        "value": "string",
        "feed_id": 0,
        "group_id": 0,
        "expiration": "string",
        "lat": 0,
        "lon": 0,
        "ele": 0,
        "completed_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "created_epoch": 0
      },
      "last": {
        "id": "string",
        "value": "string",
        "feed_id": 0,
        "group_id": 0,
        "expiration": "string",
        "lat": 0,
        "lon": 0,
        "ele": 0,
        "completed_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "created_epoch": 0
      },
      "count": 0
    }
  },
  "unit_type": "string",
  "unit_symbol": "string",
  "history": true,
  "visibility": "string",
  "license": "string",
  "enabled": true,
  "last_value": "string",
  "status": "string",
  "status_notify": true,
  "status_timeout": 0,
  "created_at": "string",
  "updated_at": "string"
}

New feed

Path Parameters

Parameter Type Required Description
username string true a valid username string
group_key string true

Body Parameters

Parameter Type Required Description
feed object true

Add Feed to Group

HTTP Request

POST/api/v2/{username}/groups/{group_key}/add

$ curl -F 'feed_key={feed_key}' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/add

Response Sample:

{
  "id": 0,
  "name": "string",
  "description": "string",
  "feeds": [
    {
      "id": 0,
      "name": "string",
      "key": "string",
      "group": {
        "id": 0,
        "name": "string",
        "description": "string",
        "created_at": "string",
        "updated_at": "string"
      },
      "groups": [
        {
          "id": 0,
          "name": "string",
          "description": "string",
          "created_at": "string",
          "updated_at": "string"
        }
      ],
      "description": "string",
      "details": {
        "shared_with": null,
        "data": {
          "first": {
            "id": "string",
            "value": "string",
            "feed_id": 0,
            "group_id": 0,
            "expiration": "string",
            "lat": 0,
            "lon": 0,
            "ele": 0,
            "completed_at": "string",
            "created_at": "string",
            "updated_at": "string",
            "created_epoch": 0
          },
          "last": {
            "id": "string",
            "value": "string",
            "feed_id": 0,
            "group_id": 0,
            "expiration": "string",
            "lat": 0,
            "lon": 0,
            "ele": 0,
            "completed_at": "string",
            "created_at": "string",
            "updated_at": "string",
            "created_epoch": 0
          },
          "count": 0
        }
      },
      "unit_type": "string",
      "unit_symbol": "string",
      "history": true,
      "visibility": "string",
      "license": "string",
      "enabled": true,
      "last_value": "string",
      "status": "string",
      "status_notify": true,
      "status_timeout": 0,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "created_at": "string",
  "updated_at": "string"
}

Returns updated group.

Path Parameters

Parameter Type Required Description
group_key string true
username string true a valid username string

Query Parameters

Parameter Type Required Description
feed_key string false

Remove Feed from Group

HTTP Request

POST/api/v2/{username}/groups/{group_key}/remove

$ curl -F 'feed_key={feed_key}' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/remove

Response Sample:

{
  "id": 0,
  "name": "string",
  "description": "string",
  "feeds": [
    {
      "id": 0,
      "name": "string",
      "key": "string",
      "group": {
        "id": 0,
        "name": "string",
        "description": "string",
        "created_at": "string",
        "updated_at": "string"
      },
      "groups": [
        {
          "id": 0,
          "name": "string",
          "description": "string",
          "created_at": "string",
          "updated_at": "string"
        }
      ],
      "description": "string",
      "details": {
        "shared_with": null,
        "data": {
          "first": {
            "id": "string",
            "value": "string",
            "feed_id": 0,
            "group_id": 0,
            "expiration": "string",
            "lat": 0,
            "lon": 0,
            "ele": 0,
            "completed_at": "string",
            "created_at": "string",
            "updated_at": "string",
            "created_epoch": 0
          },
          "last": {
            "id": "string",
            "value": "string",
            "feed_id": 0,
            "group_id": 0,
            "expiration": "string",
            "lat": 0,
            "lon": 0,
            "ele": 0,
            "completed_at": "string",
            "created_at": "string",
            "updated_at": "string",
            "created_epoch": 0
          },
          "count": 0
        }
      },
      "unit_type": "string",
      "unit_symbol": "string",
      "history": true,
      "visibility": "string",
      "license": "string",
      "enabled": true,
      "last_value": "string",
      "status": "string",
      "status_notify": true,
      "status_timeout": 0,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "created_at": "string",
  "updated_at": "string"
}

Updated group

Path Parameters

Parameter Type Required Description
group_key string true
username string true a valid username string

Query Parameters

Parameter Type Required Description
feed_key string false

Get Group Feeds

HTTP Request

GET/api/v2/{username}/groups/{group_key}/feeds

$ curl -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/feeds

Response Sample:

[
  {
    "id": 0,
    "name": "string",
    "key": "string",
    "group": {
      "id": 0,
      "name": "string",
      "description": "string",
      "created_at": "string",
      "updated_at": "string"
    },
    "groups": [
      {
        "id": 0,
        "name": "string",
        "description": "string",
        "created_at": "string",
        "updated_at": "string"
      }
    ],
    "description": "string",
    "details": {
      "shared_with": null,
      "data": {
        "first": {
          "id": "string",
          "value": "string",
          "feed_id": 0,
          "group_id": 0,
          "expiration": "string",
          "lat": 0,
          "lon": 0,
          "ele": 0,
          "completed_at": "string",
          "created_at": "string",
          "updated_at": "string",
          "created_epoch": 0
        },
        "last": {
          "id": "string",
          "value": "string",
          "feed_id": 0,
          "group_id": 0,
          "expiration": "string",
          "lat": 0,
          "lon": 0,
          "ele": 0,
          "completed_at": "string",
          "created_at": "string",
          "updated_at": "string",
          "created_epoch": 0
        },
        "count": 0
      }
    },
    "unit_type": "string",
    "unit_symbol": "string",
    "history": true,
    "visibility": "string",
    "license": "string",
    "enabled": true,
    "last_value": "string",
    "status": "string",
    "status_notify": true,
    "status_timeout": 0,
    "created_at": "string",
    "updated_at": "string"
  }
]

An array of feeds

Path Parameters

Parameter Type Required Description
group_key string true
username string true a valid username string

Webhooks

Webhooks are one way disconnected web services can share data with each other, automatically. For example, say you wanted to get a user’s latest Twitter message. Instead of constantly connecting to the twitter API every minute to check if a new message has been posted, you can ask Twitter to update a webhook URL on each post. That means Twitter will contact you when there’s new data. But, as you can imagine, you need a webserver to listen for that posting. In this case, Adafruit IO can act as that webhook destination.

Adafruit IO only supports receiving data at this time.

You can create new feed webhook receivers by visiting a feed page and using the "Webhooks" link.

Send Data via Webhook

Create a data value. The request body should include a value parameter named either value or payload and may optionally include lat, lon, and ele parameters if you want to tag the data with a location.

HTTP Request

POST/api/v2/webhooks/feed/:token

# publish as form data
curl -F "value=42" https://io.adafruit.com/api/v2/webhooks/feed/:token

# publish as JSON
curl -F '{"value":"42"}' -H 'Content-Type: application/json' \
    https://io.adafruit.com/api/v2/webhooks/feed/:token

Response Sample:

{
  "id": "string",
  "value": "42",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

Path Parameters

Parameter Type Required Description
token string true the webhook token

Body Parameters

Parameter Type Required Description
value string true Data value
lat float false latitude value for location
lon float false longitude value for location
ele float false elevation value for location

Send Arbitrary Data via Webhook

New feed data record whose value is the raw contents of the webhook request body.

Use this path if the web service you're connecting to can't be configured to match the webhook Send Data API body format.

HTTP Request

POST/api/v2/webhooks/feed/:token/raw

curl -H "Content-Type: text/plain" \
    --data "this is raw data, { 'not properly formatted json' }" \
    https://io.adafruit.com/api/v2/webhooks/feed/:token/raw

Response Sample:

{
  "id": "string",
  "value": "this is raw data, { 'not properly formatted json' }",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

Path Parameters

Parameter Type Required Description
token string true the webhook token

Send Notification via Webhook

HTTP Request

POST/api/v2/webhooks/feed/:token/notify

$ curl -X POST https://io.adafruit.com/api/v2/webhooks/feed/:token/notify

Response Sample:

{
  "id": "string",
  "value": "ping",
  "feed_id": 0,
  "feed_key": "string",
  "created_at": "datetime",
  "location": {},
  "lat": 0.0,
  "lon": 0.0,
  "ele": 0.0,
  "created_epoch": 0,
  "expiration": "datetime"
}

Creates a new feed data record with the value "ping", regardless of what was posted.

This path is helpful if you're using a low-memory MQTT client that can't handle the large webhook payloads that a service like GitHub publishes and all you care about is that something happened, not precisely what happened.

Actions

Actions are a way to do something when a certain situation occurs. There are two kinds of actions supported at this time: Scheduled and Reactive.

Scheduled actions repeatedly perform an action after a scheduled interval.

Reactive actions are much more advanced, and can integrate basic logic. At a basic level, they check if a feed value is somehow comparable to a value or to even another feed. If so, you’ll be able to send an email notification, post a webhook or even publish a message to another feed. For example, you can set up a reactive action to notify you when the temperature falls below a certain value. When paired with Feed Notification you can easily keep track of the health of your feed and also when something’s gone wrong.

Get All Actions

HTTP Request

GET/api/v2/{username}/actions

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/actions

Response Sample:

[
  {
    "name": "string"
  }
]

An array of actions

Path Parameters

Parameter Type Required Description
username string true a valid username string

Create Action

HTTP Request

POST/api/v2/{username}/actions

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/actions

Response Sample:

{
  "name": "string"
}

New Action

Path Parameters

Parameter Type Required Description
username string true a valid username string

Body Parameters

Parameter Type Required Description
trigger object true

Return Action

HTTP Request

GET/api/v2/{username}/actions/{id}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/actions/{id}

Response Sample:

{
  "name": "string"
}

Action response

Path Parameters

Parameter Type Required Description
username string true a valid username string
id string true

Replace Action

HTTP Request

PUT/api/v2/{username}/actions/{id}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/actions/{id}

Response Sample:

{
  "name": "string"
}

Updated action

Path Parameters

Parameter Type Required Description
username string true a valid username string
id string true

Body Parameters

Parameter Type Required Description
trigger object true

Delete Action

HTTP Request

DELETE/api/v2/{username}/actions/{id}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/actions/{id}

Response Sample:

"string"

Deleted Action successfully

Path Parameters

Parameter Type Required Description
username string true a valid username string
id string true

Activities

Activities are Adafruit IO's list of actions you've taken to create, update, or delete objects in your Adafruit IO account. We store the last 1000 actions taken for:

All Activities

HTTP Request

GET /api/v2/{username}/activities

curl -H "X-AIO-Key: {io_key}" \
  https://io.adafruit.com/api/v2/{username}/activities

Response Sample

[
  {
    "id": 0,
    "action": "string",
    "model": "string",
    "data": {
    },
    "user_id": 0,
    "created_at": "string",
    "updated_at": "string"
  }
]

Path Parameters

Parameter Type Required Description
username string true a valid username string

Query Parameters

Parameter Type Required Description
start_time string false Start time for filtering, returns records created after given time.
end_time string false End time for filtering, returns records created before give time.
limit integer false Limit the number of records returned.

Get Activities by Type

HTTP Request

GET/api/v2/{username}/activities/{type}

# Returns two records
$ curl -F 'limit=2' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/activities/{type}

Response Sample:

[
  {
    "id": 0,
    "action": "string",
    "model": "string",
    "data": {
    },
    "user_id": 0,
    "created_at": "string",
    "updated_at": "string"
  }
]

An array of activities

Path Parameters

Parameter Type Required Description
username string true a valid username string
type string true

Query Parameters

Parameter Type Required Description
start_time string false Start time for filtering, returns records created after given time.
end_time string false End time for filtering, returns records created before give time.
limit integer false Limit the number of records returned.

Blocks

Blocks are objects which can be placed on an Adafruit IO Dasboard for a user. Blocks IO range from input blocks (sliders and buttons) to output blocks (such as maps or other visual displays).

The dashboard_key can be obtained by either the response of a dashboard API call, or via the UI within IO at https://io.adafruit.com/{username}/dashboards.

All blocks

HTTP Request

GET/api/v2/{username}/dashboards/{dashboard_key}/blocks

Response Sample:

[
  {
    "name": "string",
    "description": "string",
    "key": "string",
    "visual_type": "string",
    "column": 0,
    "row": 0,
    "size_x": 0,
    "size_y": 0,
    "block_feeds": [
      {
        "id": "string",
        "feed": null,
        "group": null
      }
    ]
  }
]

An array of blocks

Path Parameters

Parameter Type Required Description
username string true a valid username string
dashboard_key string true

Create a Block

HTTP Request

POST/api/v2/{username}/dashboards/{dashboard_key}/blocks

Response Sample:

{
  "name": "string",
  "description": "string",
  "key": "string",
  "visual_type": "string",
  "column": 0,
  "row": 0,
  "size_x": 0,
  "size_y": 0,
  "block_feeds": [
    {
      "id": "string",
      "feed": null,
      "group": null
    }
  ]
}

New Block

Path Parameters

Parameter Type Required Description
username string true a valid username string
dashboard_key string true

Body Parameters

Parameter Type Required Description
block object true

Returns Block

HTTP Request

GET/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}

Response Sample:

{
  "name": "string",
  "description": "string",
  "key": "string",
  "visual_type": "string",
  "column": 0,
  "row": 0,
  "size_x": 0,
  "size_y": 0,
  "block_feeds": [
    {
      "id": "string",
      "feed": null,
      "group": null
    }
  ]
}

Block response

Path Parameters

Parameter Type Required Description
username string true a valid username string
dashboard_key string true
id string true

Replace A Block

HTTP Request

PUT/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}

Response Sample:

{
  "name": "string",
  "description": "string",
  "key": "string",
  "visual_type": "string",
  "column": 0,
  "row": 0,
  "size_x": 0,
  "size_y": 0,
  "block_feeds": [
    {
      "id": "string",
      "feed": null,
      "group": null
    }
  ]
}

Updated block

Path Parameters

Parameter Type Required Description
username string true a valid username string
dashboard_key string true
id string true

Body Parameters

Parameter Type Required Description
block object true

Delete a Block

HTTP Request

DELETE/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}

Response Sample:

"string"

Deleted Block successfully

Path Parameters

Parameter Type Required Description
username string true a valid username string
dashboard_key string true
id string true

Dashboards

Dashboards allow you to visualize data and control Adafruit IO connected projects from any modern web browser. Blocks such as charts, sliders, and buttons are available to help you quickly get your IoT project up and running without the need for any custom code.

All dashboards

HTTP Request

GET/api/v2/{username}/dashboards

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/dashboards

Response Sample:

[
  {
    "name": "string",
    "description": "string",
    "key": "string",
    "blocks": [
      {
        "name": "string",
        "description": "string",
        "key": "string",
        "visual_type": "string",
        "column": 0,
        "row": 0,
        "size_x": 0,
        "size_y": 0,
        "block_feeds": [
          {
            "id": "string",
            "feed": null,
            "group": null
          }
        ]
      }
    ]
  }
]

An array of dashboards

Path Parameters

Parameter Type Required Description
username string true a valid username string

Create a Dashboard

HTTP Request

POST/api/v2/{username}/dashboards

$ curl -F 'name=newdash' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/dashboards

Response Sample:

{
  "name": "string",
  "description": "string",
  "key": "string",
  "blocks": [
    {
      "name": "string",
      "description": "string",
      "key": "string",
      "visual_type": "string",
      "column": 0,
      "row": 0,
      "size_x": 0,
      "size_y": 0,
      "block_feeds": [
        {
          "id": "string",
          "feed": null,
          "group": null
        }
      ]
    }
  ]
}

New Dashboard

Path Parameters

Parameter Type Required Description
username string true a valid username string

Body Parameters

Parameter Type Required Description
dashboard object true

Return Dashboard

HTTP Request

GET/api/v2/{username}/dashboards/{id}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/dashboards/{id}

Response Sample:

{
  "name": "string",
  "description": "string",
  "key": "string",
  "blocks": [
    {
      "name": "string",
      "description": "string",
      "key": "string",
      "visual_type": "string",
      "column": 0,
      "row": 0,
      "size_x": 0,
      "size_y": 0,
      "block_feeds": [
        {
          "id": "string",
          "feed": null,
          "group": null
        }
      ]
    }
  ]
}

Dashboard response

Path Parameters

Parameter Type Required Description
username string true a valid username string
id string true

Replace a Dashboard

HTTP Request

PUT/api/v2/{username}/dashboards/{id}

$ curl -F 'name=newdash' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/dashboards/{id}

Response Sample:

{
  "name": "string",
  "description": "string",
  "key": "string",
  "blocks": [
    {
      "name": "string",
      "description": "string",
      "key": "string",
      "visual_type": "string",
      "column": 0,
      "row": 0,
      "size_x": 0,
      "size_y": 0,
      "block_feeds": [
        {
          "id": "string",
          "feed": null,
          "group": null
        }
      ]
    }
  ]
}

Updated dashboard

Path Parameters

Parameter Type Required Description
username string true a valid username string
id string true

Body Parameters

Parameter Type Required Description
dashboard object true

Delete a Dashboard

HTTP Request

DELETE/api/v2/{username}/dashboards/{id}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/dashboards/{id}

Response Sample:

"string"

Deleted Dashboard successfully

Path Parameters

Parameter Type Required Description
username string true a valid username string
id string true

Permissions

Each Adafruit IO user contains permissions which can be set and modified.

Get All Permissions

HTTP Request

GET/api/v2/{username}/{type}/{type_id}/acl

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/{type}/{type_id}/acl

Response Sample:

[
  {
    "id": 0,
    "user_id": 0,
    "scope": "string",
    "scope_value": "string",
    "model": "string",
    "object_id": 0,
    "created_at": "string",
    "updated_at": "string"
  }
]

An array of permissions

Path Parameters

Parameter Type Required Description
username string true a valid username string
type string true
type_id string true

Create Permission

HTTP Request

POST/api/v2/{username}/{type}/{type_id}/acl

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/{type}/{type_id}/acl

Response Sample:

{
  "id": 0,
  "user_id": 0,
  "scope": "string",
  "scope_value": "string",
  "model": "string",
  "object_id": 0,
  "created_at": "string",
  "updated_at": "string"
}

New Permission

Path Parameters

Parameter Type Required Description
username string true a valid username string
type string true
type_id string true

Body Parameters

Parameter Type Required Description
permission object true

Returns Permission

HTTP Request

GET/api/v2/{username}/{type}/{type_id}/acl/{id}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/{type}/{type_id}/acl{id}

Response Sample:

{
  "id": 0,
  "user_id": 0,
  "scope": "string",
  "scope_value": "string",
  "model": "string",
  "object_id": 0,
  "created_at": "string",
  "updated_at": "string"
}

Permission response

Path Parameters

Parameter Type Required Description
username string true a valid username string
type string true
type_id string true
id string true

Replace Permission

HTTP Request

PUT/api/v2/{username}/{type}/{type_id}/acl/{id}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/{type}/{type_id}/acl{id}

Response Sample:

{
  "id": 0,
  "user_id": 0,
  "scope": "string",
  "scope_value": "string",
  "model": "string",
  "object_id": 0,
  "created_at": "string",
  "updated_at": "string"
}

Updated permission

Path Parameters

Parameter Type Required Description
username string true a valid username string
type string true
type_id string true
id string true

Body Parameters

Parameter Type Required Description
permission object true

Delete Permission

HTTP Request

DELETE/api/v2/{username}/{type}/{type_id}/acl/{id}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/{type}/{type_id}/acl{id}

Response Sample:

"string"

Deleted Permission successfully

Path Parameters

Parameter Type Required Description
username string true a valid username string
type string true
type_id string true
id string true

Users

Adafruit IO can return information about your username, activity-level, rate-limit and current actions.

Get User Info

HTTP Request

GET/api/v2/user

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/user

Response Sample:

{
  "id": 0,
  "name": "string",
  "color": "string",
  "username": "string",
  "time_zone": "string",
  "created_at": "string",
  "updated_at": "string"
}

A User record

Get Detailed User Info

HTTP Request

GET/api/v2/{username}/throttle

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/throttle

Response Sample:

{
  "data_rate_limit": 0,
  "active_data_rate": 0
}

Data rate limit and current actions.

Path Parameters

Parameter Type Required Description
username string true a valid username string

Tokens

Tokens are used for authenticating an Adafruit IO user. See the Authentication page for more information about this.

Get All Tokens

HTTP Request

GET/api/v2/{username}/tokens

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/tokens

Response Sample:

[
  {
    "token": "string"
  }
]

An array of tokens

Path Parameters

Parameter Type Required Description
username string true a valid username string

Create Token

HTTP Request

POST/api/v2/{username}/tokens

$ curl -F 'token=uniqueToken' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/tokens

Response Sample:

{
  "token": "string"
}

New Token

Path Parameters

Parameter Type Required Description
username string true a valid username string

Body Parameters

Parameter Type Required Description
token object true

Returns Token

HTTP Request

GET/api/v2/{username}/tokens/{id}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/tokens/{id}

Response Sample:

{
  "token": "string"
}

Token response

Path Parameters

Parameter Type Required Description
username string true a valid username string
id string true

Delete Token

HTTP Request

DELETE/api/v2/{username}/tokens/{id}

$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/tokens/{id}

Response Sample:

"string"

Deleted Token successfully

Path Parameters

Parameter Type Required Description
username string true a valid username string
id string true

Services

Adafruit IO provides access to several connected services. The current services offered are IFTTT, Zapier, Weather, Randomizer and Time.

Each of these services is unique in that you may need to do some setup at the links above prior to utilizing the service via the Adafruit IO HTTP API.

Time

The Adafruit IO time service does not replace a time-synchronization service like NTP, but it can help you figure out your local time on an Internet of Things device that doesn't have a built in clock.

Detailed documentation on the usage of the time API is found within Adafruit IO on the time services page.

Randomizer

Create random data streams that can generate colors, words, numbers, or pick a value from a custom data set and send it directly to your devices.

The four available data types are:

Detailed documentation on the usage and setup of the randomizer API is found within Adafruit IO on the randomizer services page.

Weather

With access to weather data powered by Dark Sky, you can get hyper-local forecasts sent directly to your devices. Weather data is updated at most once every 20 minutes.

When you have an IO Plus account, you can track the weather through our HTTP or MQTT APIs for up to 5 locations at a time.

Detailed documentation on the usage and setup of the weather API is found within Adafruit IO on the weather services page.

Errors

The Adafruit IO API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid or was in the wrong format.
401 Unauthorized -- Your API key is wrong or you're trying to view a resource you don't own.
403 Forbidden -- This action is not permitted.
404 Not Found -- The specified record could not be found.
406 Not Acceptable -- You requested a format that we don't serve.
429 Too Many Requests -- You're sending or requesting data too quickly! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
CURL Arduino Python Circuitpython Ruby