Adafruit IO REST API
The Internet of Things for Everyone The Adafruit IO HTTP API provides access to your Adafruit IO data from any programming language or hardware environment…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
The Internet of Things for Everyone
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 IO learn guide and a simple Internet of Things capable device like the Feather Huzzah.
This API documentation is hosted on GitHub Pages and is available at https://github.com/adafruit/io-api. For questions or comments visit the Adafruit IO Forums or the adafruit-io channel on the Adafruit Discord server.
Authentication
Authentication for every API request happens through the X-AIO-Key header or query parameter and your IO API key. A simple cURL request to get all available feeds for a user with the username "io_username" and the key "io_key_12345" could look like this:
$ curl -H "X-AIO-Key: io_key_12345" https://io.adafruit.com/api/v2/io_username/feeds
Or like this:
$ curl "https://io.adafruit.com/api/v2/io_username/feeds?X-AIO-Key=io_key_12345
Using the node.js request library, IO HTTP requests are as easy as:
var request = require('request');
var options = {
url: 'https://io.adafruit.com/api/v2/io_username/feeds',
headers: {
'X-AIO-Key': 'io_key_12345',
'Content-Type': 'application/json'
}
};
function callback(error, response, body) {
if (!error && response.statusCode == 200) {
var feeds = JSON.parse(body);
console.log(feeds.length + " FEEDS AVAILABLE");
feeds.forEach(function (feed) {
console.log(feed.name, feed.key);
})
}
}
request(options, callback);Using the ESP8266 Arduino HTTPClient library, an HTTPS GET request would look like this (replacing --- with your own values in the appropriate locations):
/// based on
/// https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266HTTPClient/examples/Authorization/Authorization.ino
#include
#include
#include
#include
ESP8266WiFiMulti WiFiMulti;
const char* ssid = "---";
const char* password = "---";
const char* host = "io.adafruit.com";
const char* io_key = "---";
const char* path_with_username = "/api/v2/---/dashboards";
// Use web browser to view and copy
// SHA1 fingerprint of the certificate
const char* fingerprint = "77 00 54 2D DA E7 D8 03 27 31 23 99 EB 27 DB CB A5 4C 57 18";
void setup() {
Serial.begin(115200);
for(uint8_t t = 4; t > 0; t--) {
Serial.printf("[SETUP] WAIT %d...\n", t);
Serial.flush();
delay(1000);
}
WiFi.mode(WIFI_STA);
WiFiMulti.addAP(ssid, password);
// wait for WiFi connection
while(WiFiMulti.run() != WL_CONNECTED) {
Serial.print('.');
delay(1000);
}
Serial.println("[WIFI] connected!");
HTTPClient http;
// start request with URL and TLS cert fingerprint for verification
http.begin("https://" + String(host) + String(path_with_username), fingerprint);
// IO API authentication
http.addHeader("X-AIO-Key", io_key);
// start connection and send HTTP header
int httpCode = http.GET();
// httpCode will be negative on error
if(httpCode > 0) {
// HTTP header has been send and Server response header has been handled
Serial.printf("[HTTP] GET response: %d\n", httpCode);
// HTTP 200 OK
if(httpCode == HTTP_CODE_OK) {
String payload = http.getString();
Serial.println(payload);
}
http.end();
}
}
void loop() {}Client Libraries
We have client libraries to help you get started with your project: Python, Ruby, Arduino C++, Javascript, and Go are available. They're all open source, so if they don't already do what you want, you can fork and add any feature you'd like.
Endpoints 71
Users
- GETGet information about the current user
/user - GETGet the user's data rate limit and current activity level.
/:username/throttle
Webhooks
- POSTSend data to a feed via webhook URL.
/webhooks/feed/:token - POSTSend arbitrary data to a feed via webhook URL.
/webhooks/feed/:token/rawThe raw data webhook receiver accepts POST requests and stores the raw request body on your feed. This is useful when you don't have control of the webhook…
Activities
- GETAll activities for current user
/:username/activities?start_time=2024-01-01T00:00:00Z&end_time=2024-01-01T00:00:00Z&limit=0The Activities endpoint returns information about the user's activities. - DELETEAll activities for current user
/:username/activitiesDelete all your activities. - GETGet activities by type for current user
/:username/activities/:type?start_time=2024-01-01T00:00:00Z&end_time=2024-01-01T00:00:00Z&limit=0The Activities endpoint returns information about the user's activities.
Dashboards
- GETAll dashboards for current user
/:username/dashboardsThe Dashboards endpoint returns information about the user's dashboards. - POSTCreate a new Dashboard
/:username/dashboards - GETReturns Dashboard based on ID
/:username/dashboards/:id - PUTReplace an existing Dashboard
/:username/dashboards/:id - DELETEDelete an existing Dashboard
/:username/dashboards/:id - PATCHUpdate properties of an existing Dashboard
/:username/dashboards/:id
Blocks
- GETAll blocks for current user
/:username/dashboards/:dashboard_id/blocksThe Blocks endpoint returns information about the user's blocks. - POSTCreate a new Block
/:username/dashboards/:dashboard_id/blocks - GETReturns Block based on ID
/:username/dashboards/:dashboard_id/blocks/:id - PUTReplace an existing Block
/:username/dashboards/:dashboard_id/blocks/:id - DELETEDelete an existing Block
/:username/dashboards/:dashboard_id/blocks/:id - PATCHUpdate properties of an existing Block
/:username/dashboards/:dashboard_id/blocks/:id
Feeds
- GETAll feeds for current user
/:username/feedsThe Feeds endpoint returns information about the user's feeds. The response includes the latest value of each feed, and other metadata about each feed. - POSTCreate a new Feed
/:username/feeds?group_key=string - GETGet feed by feed key
/:username/feeds/:feed_keyReturns feed based on the feed key - PUTReplace an existing Feed
/:username/feeds/:feed_key - DELETEDelete an existing Feed
/:username/feeds/:feed_key - PATCHUpdate properties of an existing Feed
/:username/feeds/:feed_key - GETGet detailed feed by feed key
/:username/feeds/:feed_key/detailsReturns more detailed feed record based on the feed key - POSTCreate a new Feed in a Group
/:username/groups/:group_key/feeds
Data
- GETGet all data for the given feed
/:username/feeds/:feed_key/data?start_time=2024-01-01T00:00:00Z&end_time=2024-01-01T00:00:00Z&limit=0&include=string - POSTCreate new Data
/:username/feeds/:feed_key/dataCreate new data records on the given feed. NOTE: when feed history is on, data value size is limited to 1KB, when feed history is turned off data value size… - POSTCreate multiple new Data records
/:username/feeds/:feed_key/data/batch - GETChart data for current feed
/:username/feeds/:feed_key/data/chart?start_time=2024-01-01T00:00:00Z&end_time=2024-01-01T00:00:00Z&resolution=0&hours=0The Chart API is what we use on io.adafruit.com to populate charts over varying timespans with a consistent number of data points. The maximum number of… - GETFirst Data in Queue
/:username/feeds/:feed_key/data/first?include=stringGet the oldest data point in the feed. This request sets the queue pointer to the beginning of the feed. - GETLast Data in Queue
/:username/feeds/:feed_key/data/last?include=stringGet the most recent data point in the feed. This request sets the queue pointer to the end of the feed. - GETNext Data in Queue
/:username/feeds/:feed_key/data/next?include=stringGet the next newest data point in the feed. If queue processing hasn't been started, the first data point in the feed will be returned. - GETPrevious Data in Queue
/:username/feeds/:feed_key/data/previous?include=stringGet the previously processed data point in the feed. NOTE: this method doesn't move the processing queue pointer. - GETLast Data in MQTT CSV format
/:username/feeds/:feed_key/data/retainGet the most recent data point in the feed in an MQTT compatible CSV format: value,lat,lon,ele - GETReturns data based on feed key
/:username/feeds/:feed_key/data/:id?include=string - PUTReplace existing Data
/:username/feeds/:feed_key/data/:id - DELETEDelete existing Data
/:username/feeds/:feed_key/data/:id - PATCHUpdate properties of existing Data
/:username/feeds/:feed_key/data/:id - POSTCreate new data for multiple feeds in a group
/:username/groups/:group_key/data - GETAll data for current feed in a specific group
/:username/groups/:group_key/feeds/:feed_key/data?start_time=2024-01-01T00:00:00Z&end_time=2024-01-01T00:00:00Z&limit=0 - POSTCreate new Data in a feed belonging to a particular group
/:username/groups/:group_key/feeds/:feed_key/data - POSTCreate multiple new Data records in a feed belonging to a particular group
/:username/groups/:group_key/feeds/:feed_key/data/batch
Groups
- GETAll groups for current user
/:username/groupsThe Groups endpoint returns information about the user's groups. The response includes the latest value of each feed in the group, and other metadata about… - POSTCreate a new Group
/:username/groups - GETReturns Group based on ID
/:username/groups/:group_key - PUTReplace an existing Group
/:username/groups/:group_key - DELETEDelete an existing Group
/:username/groups/:group_key - PATCHUpdate properties of an existing Group
/:username/groups/:group_key - POSTAdd an existing Feed to a Group
/:username/groups/:group_key/add?feed_key=string - GETAll feeds for current user in a given group
/:username/groups/:group_key/feedsThe Group Feeds endpoint returns information about the user's feeds. The response includes the latest value of each feed, and other metadata about each feed,… - POSTRemove a Feed from a Group
/:username/groups/:group_key/remove?feed_key=string
Tokens
- GETAll tokens for current user
/:username/tokensThe Tokens endpoint returns information about the user's tokens. - POSTCreate a new Token
/:username/tokens - GETReturns Token based on ID
/:username/tokens/:id - PUTReplace an existing Token
/:username/tokens/:id - DELETEDelete an existing Token
/:username/tokens/:id - PATCHUpdate properties of an existing Token
/:username/tokens/:id
Triggers
- GETAll triggers for current user
/:username/triggersThe Triggers endpoint returns information about the user's triggers. - POSTCreate a new Trigger
/:username/triggers - GETReturns Trigger based on ID
/:username/triggers/:id - PUTReplace an existing Trigger
/:username/triggers/:id - DELETEDelete an existing Trigger
/:username/triggers/:id - PATCHUpdate properties of an existing Trigger
/:username/triggers/:id
Permissions
- GETAll permissions for current user and type
/:username/:type/:type_id/aclThe Permissions endpoint returns information about the user's permissions. - POSTCreate a new Permission
/:username/:type/:type_id/acl - GETReturns Permission based on ID
/:username/:type/:type_id/acl/:id - PUTReplace an existing Permission
/:username/:type/:type_id/acl/:id - DELETEDelete an existing Permission
/:username/:type/:type_id/acl/:id - PATCHUpdate properties of an existing Permission
/:username/:type/:type_id/acl/:id
API details
- Base URL
https://io.adafruit.com/api/v2- Authentication
- An API key in the X-AIO-Key header
An API key in the X-AIO-Signature header
An API key in the X-AIO-Key query parameter - Operations
- 71 operations on 36 pathsGET 29POST 17DELETE 9PUT 8PATCH 8
- Main resources
- Data 19Feeds 11Groups 9Blocks 6Dashboards 6Permissions 6Tokens 6Triggers 6Activities 3Users 2
- Response formats
application/jsontext/csv- Description format
- Swagger 2.0, API version
2.0.0 - Links
- OpenAPI document
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the Adafruit IO REST API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Adafruit IO REST API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the X-AIO-Key header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get information about the current user” (GET /user), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Adafruit IO REST API?
The Internet of Things for Everyone The Adafruit IO HTTP API provides access to your Adafruit IO data from any programming language or hardware environment… It is listed under IoT & devices and has 71 endpoints.
Who publishes the Adafruit IO REST API?
It is listed from Adafruit's public API description (an OpenAPI document), not published by Adafruit on Swastik Codes. Anyone who controls adafruit.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Adafruit IO REST API?
Requests go to https://io.adafruit.com/api/v2. Endpoint paths are added to this base URL.
How do I authenticate with the Adafruit IO REST API?
It accepts 3 methods: an API key in the X-AIO-Key header; an API key in the X-AIO-Signature header; an API key in the X-AIO-Key query parameter.
How many endpoints does the Adafruit IO REST API have?
71 operations on 36 paths (29 GET, 17 POST, 9 DELETE, 8 PUT, 8 PATCH). The largest groups are Data, Feeds, Groups, Blocks.
Is forking the Adafruit IO REST API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.