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>
- Count (
X-Pagination-Count) is the number of data points in the current request. - Limit (
X-Pagination-Limit) is either the requested limit if it was included as a parameter or 1000, whichever is less. - Total (
X-Pagination-Total) is the total number of data points in the feed for the givenstart_timeandend_time. Note, this value may be up to 5 minutes behind real time. - Start (
X-Pagination-Start) is an ISO-8601 formatted date value based on thestart_timeparameter in the original request, if one was given. - End (
X-Pagination-End) is an ISO-8601 formatted date value based either on theend_timeparameter from the original request or the time when the original request was made. - Link is a set of one or more URLs that point you to related resources.
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.
The Link Header
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 (note: using single quotes instead prevents variable expansion etc in bash)
$ 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
# Get data from the given Feed in the given Group
$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/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"
}
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:
- Dashboards
- Blocks
- Feeds
- Groups
- Actions
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 the visual components placed on an Adafruit IO Dashboard. They range from input blocks (sliders, buttons, and color pickers) to output blocks (gauges, charts, and maps).
Each block connects to one or more feeds via block_feeds, and its appearance is controlled by a properties object whose allowed keys depend on the visual_type.
The dashboard_key can be obtained from the response of a dashboard API call, or from the URL in the IO web app at https://io.adafruit.com/{username}/dashboards.
All blocks
HTTP Request
GET/api/v2/{username}/dashboards/{dashboard_key}/blocks
$ curl -H "X-AIO-Key: {io_key}" \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}/blocks
# pip install adafruit-io
from Adafruit_IO import Client
aio = Client('YOUR_USERNAME', 'YOUR_AIO_KEY')
blocks = aio.blocks('dashboard-key')
// Arduino - blocks are managed via the dashboard object.
// The Arduino library does not have a "list all blocks" method.
// Use the REST API (curl) to retrieve existing blocks.
# gem install adafruit-io
api = Adafruit::IO::Client.new key: 'YOUR_AIO_KEY',
username: 'YOUR_USERNAME'
blocks = api.blocks(dashboard_key: 'dashboard-key')
puts JSON.pretty_generate(blocks)
Response Sample:
[
{
"id": "1234",
"name": "Temperature",
"visual_type": "gauge",
"column": 0,
"row": 0,
"size_x": 4,
"size_y": 4,
"properties": {
"minValue": "0",
"maxValue": "100",
"label": "Temp"
},
"block_feeds": [
{
"id": "5678",
"feed": {
"id": 827982,
"name": "Temperature",
"key": "temperature"
},
"group": {
"id": 493,
"name": "Default",
"key": "default"
}
}
],
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
]
Returns an array of all blocks on the specified dashboard.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | true | a valid username string |
| dashboard_key | string | true | the key of the dashboard |
Create a Block
HTTP Request
POST/api/v2/{username}/dashboards/{dashboard_key}/blocks
$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"block": {"visual_type": "gauge", "block_feeds": [{"feed_id": "{feed_id}", "group_id": "{group_id}"}], "properties": {"minValue": "0", "maxValue": "100", "ringWidth": "25", "label": "Value", "decimalPlaces": "2", "showIcon": false}, "size_x": 4, "size_y": 4}}' \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}/blocks
from Adafruit_IO import Client, Block
aio = Client('YOUR_USERNAME', 'YOUR_AIO_KEY')
block = aio.create_block('dashboard-key', Block(
visual_type='gauge',
block_feeds=[{
'feed_id': 'temperature',
'group_id': 'default'
}],
properties={
'minValue': '0',
'maxValue': '100',
'ringWidth': '25',
'label': 'Value',
'decimalPlaces': '2',
'showIcon': False
}
))
// Arduino (adafruit_io_arduino library)
#include "AdafruitIO_WiFi.h"
AdafruitIO_WiFi io("YOUR_USERNAME", "YOUR_AIO_KEY", "SSID", "PASS");
AdafruitIO_Dashboard *dashboard = io.dashboard("dashboard-key");
AdafruitIO_Feed *temperature = io.feed("temperature");
// Create a gauge block on the dashboard
GaugeBlock *gauge = dashboard->addGaugeBlock(temperature);
gauge->min = 0;
gauge->max = 100;
gauge->label = "Value";
gauge->width = 4;
gauge->height = 4;
gauge->save();
block = api.create_block(
dashboard_key: 'dashboard-key',
block: {
visual_type: 'gauge',
block_feeds: [
{ feed_id: 'temperature', group_id: 'default' }
],
properties: {
minValue: '0',
maxValue: '100',
ringWidth: '25',
label: 'Value',
decimalPlaces: '2',
showIcon: false
},
size_x: 4,
size_y: 4
}
)
Response Sample:
{
"id": "1234",
"name": null,
"visual_type": "gauge",
"column": null,
"row": null,
"size_x": 4,
"size_y": 4,
"source_key": null,
"source": null,
"properties": {
"minValue": "0",
"maxValue": "100",
"ringWidth": "25",
"label": "Value",
"decimalPlaces": "2",
"showIcon": false
},
"block_feeds": [
{
"id": "5678",
"feed": {
"id": 827982,
"name": "Temperature",
"key": "temperature"
},
"group": {
"id": 493,
"name": "Default",
"key": "default"
}
}
],
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
Creates a new block on the specified dashboard. The visual_type field is required. Most blocks also need at least one entry in block_feeds to connect the block to a data feed.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | true | a valid username string |
| dashboard_key | string | true | the key of the dashboard |
Body Parameters
The request body must contain a block object with the following fields:
| Parameter | Type | Required | Description |
|---|---|---|---|
| visual_type | string | true | the type of block (see Visual Types below) |
| name | string | false | a display name for the block |
| description | string | false | a description of the block |
| block_feeds | array | false | array of feed connections (see Block Feeds below) |
| properties | object | false | visual configuration (see Properties below) |
| column | integer | false | grid column position |
| row | integer | false | grid row position |
| size_x | integer | false | width in grid units (default: 4) |
| size_y | integer | false | height in grid units (default: 4) |
Visual Types
The visual_type field must be one of the following values:
| Type | Description |
|---|---|
| toggle_button | binary on/off toggle control |
| slider | adjustable numerical slider |
| momentary_button | press-and-release button |
| gauge | circular gauge display |
| line_chart | line chart for historical data |
| text | single-line text display |
| color_picker | color selection wheel |
| map | geographic map with markers |
| stream | scrolling data stream |
| image | image display |
| remote_control | directional pad remote control |
| multiline_text | multi-line text display |
| rich_text | rich formatted text (static content) |
| icon | icon indicator display |
| indicator | status indicator (on/off with colors) |
| number_pad | numeric keypad input |
| selector | dropdown or radio button selector |
| dashboard_link | link to another dashboard |
| battery | battery level indicator |
| divider | visual separator |
| line_gauge | horizontal line gauge |
Block Feeds
Each entry in the block_feeds array connects the block to a feed:
| Parameter | Type | Required | Description |
|---|---|---|---|
| feed_id | string or integer | true | the feed to connect — accepts a numeric feed ID (827982), a feed key string ("temperature"), or a group-qualified key ("group-key.feed-key") |
| group_id | integer | false | the numeric ID of the feed's group (defaults to the user's default group) |
Properties
The properties object controls the visual appearance and behavior of the block. Available keys vary by visual_type. All property values are strings unless otherwise noted.
Common Properties:
| Property | Type | Description |
|---|---|---|
| label | string | display label for the block |
| showName | boolean | show the block name |
| showGroupName | boolean | show the group name |
| showTimestamp | boolean | show the last updated timestamp |
| decimalPlaces | string | number of decimal places to display |
| fontSize | string | font size for text display |
| fontColor | string | font color |
Gauge Properties:
| Property | Type | Description |
|---|---|---|
| minValue | string | minimum gauge value |
| maxValue | string | maximum gauge value |
| ringWidth | string | width of the gauge ring |
| minWarning | string | value at which to show a low warning |
| maxWarning | string | value at which to show a high warning |
| showIcon | boolean | show an icon on the gauge |
Chart Properties:
Line Chart Block Example
$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"block": {"visual_type": "line_chart", "block_feeds": [{"feed_id": "{feed_id}", "group_id": "{group_id}"}], "properties": {"xAxisLabel": "Time", "yAxisLabel": "Value", "yAxisMin": "0", "yAxisMax": "100", "historyHours": "24", "decimalPlaces": "2"}, "size_x": 12, "size_y": 5}}' \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}/blocks
chart = aio.create_block('dashboard-key', Block(
visual_type='line_chart',
block_feeds=[{
'feed_id': 'temperature',
'group_id': 'default'
}],
properties={
'xAxisLabel': 'Time',
'yAxisLabel': 'Value',
'yAxisMin': '0',
'yAxisMax': '100',
'historyHours': '24',
'decimalPlaces': '2'
}
))
// Arduino
ChartBlock *chart = dashboard->addChartBlock(temperature);
chart->xAxisLabel = "Time";
chart->yAxisLabel = "Value";
chart->yAxisMin = 0;
chart->yAxisMax = 100;
chart->historyHours = 24;
chart->width = 6;
chart->height = 4;
chart->save();
chart = api.create_block(
dashboard_key: 'dashboard-key',
block: {
visual_type: 'line_chart',
block_feeds: [
{ feed_id: 'temperature', group_id: 'default' }
],
properties: {
xAxisLabel: 'Time',
yAxisLabel: 'Value',
yAxisMin: '0',
yAxisMax: '100',
historyHours: '24',
decimalPlaces: '2'
},
size_x: 12,
size_y: 5
}
)
| Property | Type | Description |
|---|---|---|
| xAxisLabel | string | label for the x-axis |
| yAxisLabel | string | label for the y-axis |
| yAxisMin | string | minimum y-axis value |
| yAxisMax | string | maximum y-axis value |
| yAxisScale | string | y-axis scale type |
| historyHours | string | number of hours of data to display |
| rawDataOnly | string | show raw data without smoothing |
| steppedLine | string | use stepped line style |
| gridLines | string | show grid lines |
| lineWidth | string | width of chart lines |
| feedKeyLegend | boolean | use the feed key (e.g. group.feed) as the chart legend label instead of the feed name |
Toggle & Button Properties:
Toggle Button Block Example
$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"block": {"visual_type": "toggle_button", "block_feeds": [{"feed_id": "{feed_id}", "group_id": "{group_id}"}], "properties": {"onText": "ON", "offText": "OFF"}, "size_x": 4, "size_y": 2}}' \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}/blocks
toggle = aio.create_block('dashboard-key', Block(
visual_type='toggle_button',
block_feeds=[{
'feed_id': 'onoff',
'group_id': 'default'
}],
properties={
'onText': 'ON',
'offText': 'OFF'
}
))
// Arduino
AdafruitIO_Feed *onoff = io.feed("onoff");
ToggleBlock *toggle = dashboard->addToggleBlock(onoff);
toggle->onText = "ON";
toggle->offText = "OFF";
toggle->width = 4;
toggle->height = 2;
toggle->save();
toggle = api.create_block(
dashboard_key: 'dashboard-key',
block: {
visual_type: 'toggle_button',
block_feeds: [
{ feed_id: 'onoff', group_id: 'default' }
],
properties: {
onText: 'ON',
offText: 'OFF'
},
size_x: 4,
size_y: 2
}
)
| Property | Type | Description |
|---|---|---|
| onText | string | label text for the ON state |
| offText | string | label text for the OFF state |
| onValue | string | value to send when turned on |
| offValue | string | value to send when turned off |
| onColor | string | color when on |
| offColor | string | color when off |
| release | string | value to send when a momentary button is released (momentary_button only, leave blank to send nothing on release) |
Slider Properties:
Slider Block Example
$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"block": {"visual_type": "slider", "block_feeds": [{"feed_id": "{feed_id}", "group_id": "{group_id}"}], "properties": {"min": "0", "max": "255", "step": "1", "label": "Brightness"}, "size_x": 6, "size_y": 2}}' \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}/blocks
slider = aio.create_block('dashboard-key', Block(
visual_type='slider',
block_feeds=[{
'feed_id': 'brightness',
'group_id': 'default'
}],
properties={
'min': '0',
'max': '255',
'step': '1',
'label': 'Brightness'
}
))
// Arduino
AdafruitIO_Feed *brightness = io.feed("brightness");
SliderBlock *slider = dashboard->addSliderBlock(brightness);
slider->min = 0;
slider->max = 255;
slider->step = 1;
slider->label = "Brightness";
slider->width = 4;
slider->height = 2;
slider->save();
slider = api.create_block(
dashboard_key: 'dashboard-key',
block: {
visual_type: 'slider',
block_feeds: [
{ feed_id: 'brightness', group_id: 'default' }
],
properties: {
min: '0',
max: '255',
step: '1',
label: 'Brightness'
},
size_x: 6,
size_y: 2
}
)
| Property | Type | Description |
|---|---|---|
| min | string | minimum slider value |
| max | string | maximum slider value |
| step | string | increment step size |
| orientation | string | slider orientation |
| handle | string | handle style |
Indicator & Icon Properties:
| Property | Type | Description |
|---|---|---|
| icon | string | icon name |
| lowIcon | string | icon for low state |
| highIcon | string | icon for high state |
| conditions | string | conditions for state changes |
| lowConditions | string | conditions for low state |
| mediumConditions | string | conditions for medium state |
| highColor | string | color for high state |
| mediumColor | string | color for medium state |
| lowColor | string | color for low state |
Display Properties:
| Property | Type | Description |
|---|---|---|
| text | string | static text content |
| value | string | static value |
| static | boolean | when true, display a fixed value instead of the latest feed value (used by text, multiline_text, and icon blocks) |
| preformatted | string | use preformatted text |
| backgroundColor | string | background color (dark theme) |
| backgroundColorLight | string | background color (light theme) |
| fillColor | string | fill color |
| tile | string | tile image (dark theme) |
| tileLight | string | tile image (light theme) |
Map Properties:
| Property | Type | Description |
|---|---|---|
| showLocation | string | show location information |
| showNumbers | string | show numerical values on map |
| historyHours | string | hours of location history to display |
Stream Properties:
| Property | Type | Description |
|---|---|---|
| errors | string | show system errors and throttle messages in the stream ("yes" or "no", default: "yes") |
Dashboard Link Properties:
| Property | Type | Description |
|---|---|---|
| dashboards | string | JSON array of dashboard objects to display as links |
Returns Block
HTTP Request
GET/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}
$ curl -H "X-AIO-Key: {io_key}" \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}
block = aio.blocks('dashboard-key', '{id}')
// Arduino - retrieving a single block by ID is not supported.
// The Arduino library creates and saves blocks directly.
// Use the REST API (curl) to retrieve block details.
block = api.block(dashboard_key: 'dashboard-key', key: '{id}')
puts JSON.pretty_generate(block)
Response Sample:
{
"id": "1234",
"name": "Temperature",
"visual_type": "gauge",
"column": 0,
"row": 0,
"size_x": 4,
"size_y": 4,
"source_key": null,
"source": null,
"properties": {
"minValue": "0",
"maxValue": "100",
"label": "Temp"
},
"block_feeds": [
{
"id": "5678",
"feed": {
"id": 827982,
"name": "Temperature",
"key": "temperature"
},
"group": {
"id": 493,
"name": "Default",
"key": "default"
}
}
],
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
Returns a single block by its ID.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | true | a valid username string |
| dashboard_key | string | true | the key of the dashboard |
| id | string | true | the ID of the block |
Replace A Block
HTTP Request
PUT/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}
$ curl -X PUT -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"block": {"properties": {"minValue": "0", "maxValue": "200", "label": "Updated Label"}}}' \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}
# Not yet available in the Python client library.
# Use the REST API directly or delete and recreate the block.
// Arduino - updating a block by ID is not supported.
// The Arduino library creates blocks with save().
// Use the REST API (curl) to update existing blocks.
updated = api.update_block(
dashboard_key: 'dashboard-key',
key: '{id}',
block: {
properties: {
minValue: '0',
maxValue: '200',
label: 'Updated Label'
}
}
)
Response Sample:
{
"id": "1234",
"name": "Temperature",
"visual_type": "gauge",
"column": 0,
"row": 0,
"size_x": 4,
"size_y": 4,
"source_key": null,
"source": null,
"properties": {
"minValue": "0",
"maxValue": "200",
"label": "Updated Label"
},
"block_feeds": [
{
"id": "5678",
"feed": {
"id": 827982,
"name": "Temperature",
"key": "temperature"
},
"group": {
"id": 493,
"name": "Default",
"key": "default"
}
}
],
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
Updates an existing block. Any fields you include will be updated; fields you omit remain unchanged.
Note: If you include block_feeds in an update, the existing feed connections are replaced entirely with the new values.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | true | a valid username string |
| dashboard_key | string | true | the key of the dashboard |
| id | string | true | the ID of the block |
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| block | object | true | a block object (same fields as Create, all optional) |
Delete a Block
HTTP Request
DELETE/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}
$ curl -X DELETE -H "X-AIO-Key: {io_key}" \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}
aio.delete_block('dashboard-key', '{id}')
// Arduino - deleting a block by ID is not supported.
// Use the REST API (curl) to delete blocks.
api.delete_block(dashboard_key: 'dashboard-key', key: '{id}')
Response Sample:
"OK"
Deletes the specified block from the dashboard.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | true | a valid username string |
| dashboard_key | string | true | the key of the dashboard |
| id | string | true | the ID of the block |
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
# pip install adafruit-io
from Adafruit_IO import Client
aio = Client('YOUR_USERNAME', 'YOUR_AIO_KEY')
dashboards = aio.dashboards()
// Arduino (adafruit_io_arduino library)
#include "AdafruitIO_WiFi.h"
AdafruitIO_WiFi io("YOUR_USERNAME", "YOUR_AIO_KEY", "SSID", "PASS");
// Arduino - listing all dashboards is not supported.
// The Arduino library works with a single dashboard at a time.
// Use the REST API (curl) to list dashboards.
# gem install adafruit-io
api = Adafruit::IO::Client.new key: 'YOUR_AIO_KEY',
username: 'YOUR_USERNAME'
dashboards = api.dashboards
Response Sample:
[
{
"id": 12345,
"name": "Weather Station",
"key": "weather-station",
"description": "Outdoor sensor data",
"visibility": "private",
"show_header": false,
"color_mode": "dark",
"block_borders": true,
"allow_overlap": false,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"blocks": [
{
"id": "1234",
"name": "Temperature",
"visual_type": "gauge",
"column": 0,
"row": 0,
"size_x": 4,
"size_y": 4,
"block_feeds": [
{
"id": "5678",
"feed": {
"id": 827982,
"name": "Temperature",
"key": "temperature"
},
"group": {
"id": 493,
"name": "Default",
"key": "default"
}
}
]
}
]
}
]
Returns an array of all dashboards for the specified user.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | true | a valid username string |
Create a Dashboard
HTTP Request
POST/api/v2/{username}/dashboards
$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"dashboard": {"name": "Weather Station", "description": "Outdoor sensor data"}}' \
https://io.adafruit.com/api/v2/{username}/dashboards
from Adafruit_IO import Client, Dashboard
aio = Client('YOUR_USERNAME', 'YOUR_AIO_KEY')
dashboard = aio.create_dashboard(Dashboard(
name='Weather Station',
description='Outdoor sensor data'
))
print(dashboard.key)
// Arduino
AdafruitIO_Dashboard *dashboard = io.dashboard("weather-station");
if (!dashboard->exists()) {
dashboard->create();
}
dashboard = api.create_dashboard(
name: 'Weather Station',
description: 'Outdoor sensor data'
)
puts dashboard['key']
Response Sample:
{
"id": 12345,
"name": "Weather Station",
"key": "weather-station",
"description": "Outdoor sensor data",
"visibility": "private",
"show_header": false,
"color_mode": "dark",
"block_borders": true,
"allow_overlap": false,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"blocks": []
}
Creates a new empty dashboard. To add blocks, use the Create a Block endpoint after creating the dashboard.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | true | a valid username string |
Body Parameters
The request body must contain a dashboard object with the following fields:
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | true | display name for the dashboard (max 128 characters) |
| description | string | false | a description of the dashboard |
| key | string | false | URL-safe key (auto-generated from name if omitted) |
| visibility | string | false | "private" (default) or "public" |
| show_header | boolean | false | show a header image on the dashboard (default: false) |
| color_mode | string | false | "dark" (default) or "light" |
| block_borders | boolean | false | show borders around blocks (default: true) |
| allow_overlap | boolean | false | allow blocks to overlap on the grid (default: false) |
Return Dashboard
HTTP Request
GET/api/v2/{username}/dashboards/{dashboard_key}
$ curl -H "X-AIO-Key: {io_key}" \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}
dashboard = aio.dashboards('dashboard-key')
// Arduino - retrieving dashboard details is not supported.
// Use exists() to check if a dashboard is available.
AdafruitIO_Dashboard *dashboard = io.dashboard("dashboard-key");
if (dashboard->exists()) {
Serial.println("Dashboard found");
}
dashboard = api.dashboard('dashboard-key')
Response Sample:
{
"id": 12345,
"name": "Weather Station",
"key": "weather-station",
"description": "Outdoor sensor data",
"visibility": "private",
"show_header": false,
"color_mode": "dark",
"block_borders": true,
"allow_overlap": false,
"layouts": {
"xl": [
{"x": 0, "y": 0, "w": 4, "h": 4, "i": "1234"},
{"x": 4, "y": 0, "w": 8, "h": 4, "i": "1235"}
],
"lg": [
{"x": 0, "y": 0, "w": 4, "h": 4, "i": "1234"},
{"x": 4, "y": 0, "w": 8, "h": 4, "i": "1235"}
],
"md": [
{"x": 0, "y": 0, "w": 4, "h": 4, "i": "1234"},
{"x": 0, "y": 4, "w": 8, "h": 4, "i": "1235"}
],
"sm": [
{"x": 0, "y": 0, "w": 4, "h": 4, "i": "1234"},
{"x": 0, "y": 4, "w": 8, "h": 4, "i": "1235"}
],
"xs": [
{"x": 0, "y": 0, "w": 4, "h": 4, "i": "1234"},
{"x": 0, "y": 4, "w": 8, "h": 4, "i": "1235"}
]
},
"blocks": [
{
"id": "1234",
"name": "Temperature",
"visual_type": "gauge",
"block_feeds": [
{
"id": "5678",
"feed": {
"id": 827982,
"name": "Temperature",
"key": "temperature"
},
"group": {
"id": 493,
"name": "Default",
"key": "default"
}
}
]
}
],
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
Returns a single dashboard with its blocks and layout data. The layouts object is only included in single-dashboard responses (not in the list endpoint).
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | true | a valid username string |
| dashboard_key | string | true | the key of the dashboard |
Replace a Dashboard
HTTP Request
PUT/api/v2/{username}/dashboards/{dashboard_key}
$ curl -X PUT -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"dashboard": {"name": "Updated Name", "color_mode": "light"}}' \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}
# Not yet available in the Python client library.
# Use the REST API directly.
// Arduino - updating dashboard settings is not supported.
// Use the REST API (curl) to update dashboard properties.
updated = api.update_dashboard(
key: 'dashboard-key',
name: 'Updated Name'
)
Response Sample:
{
"id": 12345,
"name": "Updated Name",
"key": "weather-station",
"description": "Outdoor sensor data",
"visibility": "private",
"show_header": false,
"color_mode": "light",
"block_borders": true,
"allow_overlap": false,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-02T00:00:00Z",
"blocks": []
}
Updates an existing dashboard. Only fields you include will be changed.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | true | a valid username string |
| dashboard_key | string | true | the key of the dashboard |
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| dashboard | object | true | a dashboard object (same fields as Create, all optional) |
Delete a Dashboard
HTTP Request
DELETE/api/v2/{username}/dashboards/{dashboard_key}
$ curl -X DELETE -H "X-AIO-Key: {io_key}" \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}
aio.delete_dashboard('dashboard-key')
// Arduino - deleting a dashboard is not supported.
// Use the REST API (curl) to delete dashboards.
api.delete_dashboard(key: 'dashboard-key')
Response Sample:
"OK"
Deletes the specified dashboard and all of its blocks.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | true | a valid username string |
| dashboard_key | string | true | the key of the dashboard |
Update Layouts
HTTP Request
POST/api/v2/{username}/dashboards/{dashboard_key}/update_layouts
$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"layouts": {"lg": [{"x": 0, "y": 0, "w": 4, "h": 4, "i": "1234"}, {"x": 4, "y": 0, "w": 8, "h": 4, "i": "1235"}]}}' \
https://io.adafruit.com/api/v2/{username}/dashboards/{dashboard_key}/update_layouts
from Adafruit_IO import Client, Layout
aio = Client('YOUR_USERNAME', 'YOUR_AIO_KEY')
layout = Layout(lg=[
{'x': 0, 'y': 0, 'w': 4, 'h': 4, 'i': '1234'},
{'x': 4, 'y': 0, 'w': 8, 'h': 4, 'i': '1235'}
])
aio.update_layout('dashboard-key', layout)
// Arduino - layout positions are set per-block using row, column, width, height
// properties before calling save(). The library does not use the
// update_layouts endpoint directly. See the Create a Block examples.
api.update_dashboard_layouts(
key: 'dashboard-key',
layouts: {
lg: [
{ x: 0, y: 0, w: 4, h: 4, i: '1234' },
{ x: 4, y: 0, w: 8, h: 4, i: '1235' }
]
}
)
Response Sample:
{
"id": 12345,
"name": "Weather Station",
"key": "weather-station",
"layouts": {
"xl": [
{"x": 0, "y": 0, "w": 4, "h": 4, "i": "1234"},
{"x": 4, "y": 0, "w": 8, "h": 4, "i": "1235"}
],
"lg": [
{"x": 0, "y": 0, "w": 4, "h": 4, "i": "1234"},
{"x": 4, "y": 0, "w": 8, "h": 4, "i": "1235"}
],
"md": [
{"x": 0, "y": 0, "w": 4, "h": 4, "i": "1234"},
{"x": 4, "y": 0, "w": 8, "h": 4, "i": "1235"}
],
"sm": [
{"x": 0, "y": 0, "w": 4, "h": 4, "i": "1234"},
{"x": 4, "y": 0, "w": 8, "h": 4, "i": "1235"}
],
"xs": [
{"x": 0, "y": 0, "w": 4, "h": 4, "i": "1234"},
{"x": 4, "y": 0, "w": 8, "h": 4, "i": "1235"}
]
},
"blocks": []
}
Updates the block positions and sizes across all responsive breakpoints. The response returns the full dashboard object with the updated layouts.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | true | a valid username string |
| dashboard_key | string | true | the key of the dashboard |
Body Parameters
The request body must contain a layouts object. Each key is a responsive breakpoint with an array of block positions:
| Parameter | Type | Required | Description |
|---|---|---|---|
| layouts | object | true | an object with breakpoint keys (xl, lg, md, sm, xs) |
Breakpoints
| Breakpoint | Description |
|---|---|
| xl | extra large screens |
| lg | large screens (desktop) |
| md | medium screens (tablet landscape) |
| sm | small screens (tablet portrait) |
| xs | extra small screens (phone) |
Block Position Fields
Each entry in a breakpoint array positions one block on the grid:
| Field | Type | Required | Description |
|---|---|---|---|
| i | string | true | the block ID (as a string) |
| x | integer | true | column position (0-based) |
| y | integer | true | row position (0-based) |
| w | integer | true | width in grid units (minimum: 2) |
| h | integer | true | height in grid units (minimum: 2) |
| z | integer | false | z-index for overlapping blocks |
Building a Dashboard via API
Step 1: Create the dashboard
$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"dashboard": {"name": "Weather Station"}}' \
https://io.adafruit.com/api/v2/{username}/dashboards
from Adafruit_IO import Client, Dashboard, Block, Layout
aio = Client('YOUR_USERNAME', 'YOUR_AIO_KEY')
# Step 1: Create the dashboard
dashboard = aio.create_dashboard(Dashboard(name='Weather Station'))
// Arduino (adafruit_io_arduino library)
#include "AdafruitIO_WiFi.h"
AdafruitIO_WiFi io("YOUR_USERNAME", "YOUR_AIO_KEY", "SSID", "PASS");
// Step 1: Create the dashboard
AdafruitIO_Dashboard *dashboard = io.dashboard("weather-station");
if (!dashboard->exists()) {
dashboard->create();
}
AdafruitIO_Feed *temperature = io.feed("temperature");
api = Adafruit::IO::Client.new key: 'YOUR_AIO_KEY',
username: 'YOUR_USERNAME'
# Step 1: Create the dashboard
dashboard = api.create_dashboard(name: 'Weather Station')
Step 2: Create blocks on the dashboard
# Create a gauge block
$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"block": {"visual_type": "gauge", "block_feeds": [{"feed_id": "temperature"}], "properties": {"minValue": "0", "maxValue": "100", "label": "Temp"}}}' \
https://io.adafruit.com/api/v2/{username}/dashboards/weather-station/blocks
# Create a line chart block
$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"block": {"visual_type": "line_chart", "block_feeds": [{"feed_id": "temperature"}], "properties": {"historyHours": "24", "yAxisLabel": "Temp"}}}' \
https://io.adafruit.com/api/v2/{username}/dashboards/weather-station/blocks
# Step 2: Create blocks (note the block IDs from responses)
gauge = aio.create_block(dashboard.key, Block(
visual_type='gauge',
block_feeds=[{'feed_id': 'temperature'}],
properties={'minValue': '0', 'maxValue': '100', 'label': 'Temp'}
))
chart = aio.create_block(dashboard.key, Block(
visual_type='line_chart',
block_feeds=[{'feed_id': 'temperature'}],
properties={'historyHours': '24', 'yAxisLabel': 'Temp'}
))
// Step 2: Create blocks with position and size
GaugeBlock *gauge = dashboard->addGaugeBlock(temperature);
gauge->min = 0;
gauge->max = 100;
gauge->label = "Temp";
gauge->row = 0;
gauge->column = 0;
gauge->width = 4;
gauge->height = 4;
gauge->save();
ChartBlock *chart = dashboard->addChartBlock(temperature);
chart->historyHours = 24;
chart->yAxisLabel = "Temp";
chart->row = 0;
chart->column = 4;
chart->width = 6;
chart->height = 4;
chart->save();
# Step 2: Create blocks (note the block IDs from responses)
gauge = api.create_block(
dashboard_key: dashboard['key'],
block: {
visual_type: 'gauge',
block_feeds: [{ feed_id: 'temperature' }],
properties: { minValue: '0', maxValue: '100', label: 'Temp' }
}
)
chart = api.create_block(
dashboard_key: dashboard['key'],
block: {
visual_type: 'line_chart',
block_feeds: [{ feed_id: 'temperature' }],
properties: { historyHours: '24', yAxisLabel: 'Temp' }
}
)
Step 3: Arrange blocks on the grid
$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \
--data '{"layouts": {"lg": [{"x": 0, "y": 0, "w": 4, "h": 4, "i": "{gauge_id}"}, {"x": 4, "y": 0, "w": 12, "h": 4, "i": "{chart_id}"}], "sm": [{"x": 0, "y": 0, "w": 4, "h": 4, "i": "{gauge_id}"}, {"x": 0, "y": 4, "w": 8, "h": 4, "i": "{chart_id}"}]}}' \
https://io.adafruit.com/api/v2/{username}/dashboards/weather-station/update_layouts
# Step 3: Arrange blocks on the grid using their IDs
layout = Layout(lg=[
{'x': 0, 'y': 0, 'w': 4, 'h': 4, 'i': str(gauge.id)},
{'x': 4, 'y': 0, 'w': 12, 'h': 4, 'i': str(chart.id)}
])
aio.update_layout(dashboard.key, layout)
// Step 3: Block positions were already set via row, column, width, and
// height properties in Step 2 before calling save(). No separate
// layout update step is needed with the Arduino library.
# Step 3: Arrange blocks on the grid using their IDs
api.update_dashboard_layouts(
key: dashboard['key'],
layouts: {
lg: [
{ x: 0, y: 0, w: 4, h: 4, i: gauge['id'].to_s },
{ x: 4, y: 0, w: 12, h: 4, i: chart['id'].to_s }
]
}
)
Building a dashboard entirely via the API requires three separate steps:
Step 1: Create the dashboard using POST /dashboards. This returns an empty dashboard with a key you'll use in the next steps.
Step 2: Create blocks using POST /dashboards/{dashboard_key}/blocks for each block you need. Each response includes the block's id, which you'll need for the layout step.
Step 3: Arrange blocks using POST /dashboards/{dashboard_key}/update_layouts to position blocks on the grid. Use the block id values from Step 2 as the i field in each layout entry.
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, Air Quality, 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:
- Pronounceable nonsense words
- Colors (RGB values, HSL values, CSS hex, or CSS color name)
- Numbers
- Preset (sample from a given set of values)
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 Apple WeatherKit, 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.
Air Quality
Get real-time air quality measurements and forecasts sent directly to your devices. Air quality data is updated at most once every 20 minutes.
When you have an IO Plus account, you can track air quality through our HTTP or MQTT APIs for up to 5 locations at a time.
Detailed documentation on the usage and setup of the air quality API is found within Adafruit IO on the air quality services page.
Get all air quality integration records without their current forecast values.
GET /api/v2/{username}/integrations/air_quality
Create a new air quality integration record.
{
"location": "latitude, longitude",
"name": "Unique friendly name",
"provider": "open_meteo"
}
POST /api/v2/{username}/integrations/air_quality
Request body should be a JSON record in the form shown, where provider is either open_meteo (global coverage) or airnow (US only, official EPA data).
Get the specified air quality record with current air quality conditions and hourly forecast data including PM2.5, PM10, ozone, nitrogen dioxide, and other pollutants.
GET /api/v2/{username}/integrations/air_quality/{id}
Permanently delete the specified air quality integration.
DELETE /api/v2/{username}/integrations/air_quality/{id}
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. |
| 422 | Unprocessable Entity -- You've sent data we can't accept/understand. Is the value field (string/number) missing? |
| 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. |