openapi: 3.0.0
info:
title: Adafruit IO REST Activities Data API
description: "### The Internet of Things for Everyone\n\nThe 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](https://learn.adafruit.com/series/adafruit-io-basics) and [a simple Internet of Things capable device like the Feather Huzzah](https://www.adafruit.com/product/2821).\n\nThis API documentation is hosted on GitHub Pages and is available at [https://github.com/adafruit/io-api](https://github.com/adafruit/io-api). For questions or comments visit the [Adafruit IO Forums](https://forums.adafruit.com/viewforum.php?f=56) or the [adafruit-io channel on the Adafruit Discord server](https://discord.gg/adafruit).\n\n#### Authentication\n\nAuthentication 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:\n\n $ curl -H \"X-AIO-Key: io_key_12345\" https://io.adafruit.com/api/v2/io_username/feeds\n\nOr like this:\n\n $ curl \"https://io.adafruit.com/api/v2/io_username/feeds?X-AIO-Key=io_key_12345\n\nUsing the node.js [request](https://github.com/request/request) library, IO HTTP requests are as easy as:\n\n```js\nvar request = require('request');\n\nvar options = {\n url: 'https://io.adafruit.com/api/v2/io_username/feeds',\n headers: {\n 'X-AIO-Key': 'io_key_12345',\n 'Content-Type': 'application/json'\n }\n};\n\nfunction callback(error, response, body) {\n if (!error && response.statusCode == 200) {\n var feeds = JSON.parse(body);\n console.log(feeds.length + \" FEEDS AVAILABLE\");\n\n feeds.forEach(function (feed) {\n console.log(feed.name, feed.key);\n })\n }\n}\n\nrequest(options, callback);\n```\n\nUsing the ESP8266 Arduino HTTPClient library, an HTTPS GET request would look like this (replacing `---` with your own values in the appropriate locations):\n\n```arduino\n/// based on\n/// https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266HTTPClient/examples/Authorization/Authorization.ino\n\n#include <Arduino.h>\n#include <ESP8266WiFi.h>\n#include <ESP8266WiFiMulti.h>\n#include <ESP8266HTTPClient.h>\n\nESP8266WiFiMulti WiFiMulti;\n\nconst char* ssid = \"---\";\nconst char* password = \"---\";\n\nconst char* host = \"io.adafruit.com\";\n\nconst char* io_key = \"---\";\nconst char* path_with_username = \"/api/v2/---/dashboards\";\n\n// Use web browser to view and copy\n// SHA1 fingerprint of the certificate\nconst char* fingerprint = \"77 00 54 2D DA E7 D8 03 27 31 23 99 EB 27 DB CB A5 4C 57 18\";\n\nvoid setup() {\n Serial.begin(115200);\n\n for(uint8_t t = 4; t > 0; t--) {\n Serial.printf(\"[SETUP] WAIT %d...\\n\", t);\n Serial.flush();\n delay(1000);\n }\n\n WiFi.mode(WIFI_STA);\n WiFiMulti.addAP(ssid, password);\n\n // wait for WiFi connection\n while(WiFiMulti.run() != WL_CONNECTED) {\n Serial.print('.');\n delay(1000);\n }\n\n Serial.println(\"[WIFI] connected!\");\n\n HTTPClient http;\n\n // start request with URL and TLS cert fingerprint for verification\n http.begin(\"https://\" + String(host) + String(path_with_username), fingerprint);\n\n // IO API authentication\n http.addHeader(\"X-AIO-Key\", io_key);\n\n // start connection and send HTTP header\n int httpCode = http.GET();\n\n // httpCode will be negative on error\n if(httpCode > 0) {\n // HTTP header has been send and Server response header has been handled\n Serial.printf(\"[HTTP] GET response: %d\\n\", httpCode);\n\n // HTTP 200 OK\n if(httpCode == HTTP_CODE_OK) {\n String payload = http.getString();\n Serial.println(payload);\n }\n\n http.end();\n }\n}\n\nvoid loop() {}\n```\n\n#### Client Libraries\n\nWe have client libraries to help you get started with your project: [Python](https://github.com/adafruit/io-client-python), [Ruby](https://github.com/adafruit/io-client-ruby), [Arduino C++](https://github.com/adafruit/Adafruit_IO_Arduino), [Javascript](https://github.com/adafruit/adafruit-io-node), and [Go](https://github.com/adafruit/io-client-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.\n\n"
version: 2.0.0
x-logo:
url: https://io.adafruit.com/api/docs/adafruit-flower-left.png
servers:
- url: https://io.adafruit.com/api/v2
- url: http://io.adafruit.com/api/v2
security:
- HeaderKey: []
- HeaderSignature: []
- QueryKey: []
tags:
- name: Data
paths:
/{username}/feeds/{feed_key}/data:
get:
x-swagger-router-controller: Data
x-swagger-router-action: all
operationId: allData
summary: Get all data for the given feed
description: ''
tags:
- Data
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
- $ref: '#/components/parameters/StartTime'
- $ref: '#/components/parameters/EndTime'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/DataInclude'
responses:
'200':
description: An array of data
headers:
X-Pagination-Limit:
description: The limit this request is using, either your given value or the default (1000).
schema:
type: integer
X-Pagination-Count:
description: The number of records returned.
schema:
type: integer
X-Pagination-Start:
description: The created_at value for the oldest record returned.
schema:
type: string
X-Pagination-End:
description: The created_at value for the newest record returned.
schema:
type: string
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
type: array
items:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
post:
summary: Create new Data
operationId: createData
description: 'Create 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 is limited to 100KB.'
x-swagger-router-controller: Data
x-swagger-router-action: create
x-code-samples:
- lang: curl
source: "curl -F 'value=65.5' -H 'X-AIO-Key: io_key_12345' \\\n https://io.adafruit.com/api/v2/io_username/feeds/io-feed-key/data"
- lang: Ruby
source: "api = Adafruit::IO::Client.new(\n key: ENV['IO_KEY'],\n username: ENV['IO_USERNAME']\n)\napi.send_data('io-feed-key', 65.5)"
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
requestBody:
$ref: '#/components/requestBodies/createDataDatum'
tags:
- Data
responses:
'200':
description: New data
content:
application/json:
schema:
$ref: '#/components/schemas/Data'
text/csv:
schema:
$ref: '#/components/schemas/Data'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/{username}/feeds/{feed_key}/data/chart:
get:
x-swagger-router-controller: Data
x-swagger-router-action: chart
operationId: chartData
summary: Chart data for current feed
description: 'The 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 points returned is 480. This API works by aggregating slices of time into a single value by averaging.
All time-based parameters are optional, if none are given it will default to 1 hour at the finest-grained resolution possible.'
tags:
- Data
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
- $ref: '#/components/parameters/StartTime'
- $ref: '#/components/parameters/EndTime'
- name: resolution
in: query
description: 'A resolution size in minutes. By giving a resolution value you will get back grouped data points aggregated over resolution-sized intervals. NOTE: time span is preferred over resolution, so if you request a span of time that includes more than max limit points you may get a larger resolution than you requested. Valid resolutions are 1, 5, 10, 30, 60, and 120.'
schema:
type: integer
format: int32
- name: hours
in: query
description: The number of hours the chart should cover.
schema:
type: integer
format: int32
responses:
'200':
description: A JSON record containing chart data and the parameters used to generate it.
content:
application/json:
schema:
type: object
properties:
feed:
type: object
properties:
id:
type: integer
key:
type: string
name:
type: string
parameters:
type: object
properties: {}
columns:
type: array
description: The names of the columns returned as data.
items:
type: string
data:
type: array
description: The actual chart data.
items:
type: array
items:
type: string
text/csv:
schema:
type: object
properties:
feed:
type: object
properties:
id:
type: integer
key:
type: string
name:
type: string
parameters:
type: object
properties: {}
columns:
type: array
description: The names of the columns returned as data.
items:
type: string
data:
type: array
description: The actual chart data.
items:
type: array
items:
type: string
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/{username}/feeds/{feed_key}/data/batch:
post:
summary: Create multiple new Data records
x-swagger-router-controller: Data
x-swagger-router-action: batch
operationId: batchCreateData
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
requestBody:
$ref: '#/components/requestBodies/batchCreateDataData'
tags:
- Data
responses:
'200':
description: New data
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
type: array
items:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/{username}/feeds/{feed_key}/data/previous:
get:
summary: Previous Data in Queue
description: 'Get the previously processed data point in the feed. NOTE: this method doesn''t move the processing queue pointer.'
x-swagger-router-controller: Data
x-swagger-router-action: previous
operationId: previousData
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
- $ref: '#/components/parameters/DataInclude'
tags:
- Data
responses:
'200':
description: Data response
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/{username}/feeds/{feed_key}/data/next:
get:
summary: Next Data in Queue
description: Get 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.
x-swagger-router-controller: Data
x-swagger-router-action: next
operationId: nextData
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
- $ref: '#/components/parameters/DataInclude'
tags:
- Data
responses:
'200':
description: Data response
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/{username}/feeds/{feed_key}/data/last:
get:
summary: Last Data in Queue
description: Get the most recent data point in the feed. This request sets the queue pointer to the end of the feed.
x-swagger-router-controller: Data
x-swagger-router-action: last
operationId: lastData
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
- $ref: '#/components/parameters/DataInclude'
tags:
- Data
responses:
'200':
description: Data response
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/{username}/feeds/{feed_key}/data/first:
get:
summary: First Data in Queue
description: Get the oldest data point in the feed. This request sets the queue pointer to the beginning of the feed.
x-swagger-router-controller: Data
x-swagger-router-action: last
operationId: firstData
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
- $ref: '#/components/parameters/DataInclude'
tags:
- Data
responses:
'200':
description: Data response
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/{username}/feeds/{feed_key}/data/retain:
get:
summary: Last Data in MQTT CSV format
description: 'Get the most recent data point in the feed in an MQTT compatible CSV format: `value,lat,lon,ele`'
x-swagger-router-controller: Data
x-swagger-router-action: retain
operationId: retainData
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
tags:
- Data
responses:
'200':
description: CSV string in `value,lat,lon,ele` format. The lat, lon, and ele values are left blank if they are not set.
content:
text/csv:
schema:
type: string
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/{username}/feeds/{feed_key}/data/{id}:
get:
summary: Returns data based on feed key
description: ''
x-swagger-router-controller: Data
x-swagger-router-action: get
operationId: getData
tags:
- Data
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
- $ref: '#/components/parameters/IDPath'
- $ref: '#/components/parameters/DataInclude'
responses:
'200':
description: Data response
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
put:
summary: Replace existing Data
x-swagger-router-controller: Data
x-swagger-router-action: replace
operationId: replaceData
description: ''
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
- $ref: '#/components/parameters/IDPath'
requestBody:
$ref: '#/components/requestBodies/createDataDatum'
tags:
- Data
responses:
'200':
description: Updated Data
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
patch:
summary: Update properties of existing Data
description: ''
x-swagger-router-controller: Data
x-swagger-router-action: update
operationId: updateData
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
- $ref: '#/components/parameters/IDPath'
requestBody:
$ref: '#/components/requestBodies/createDataDatum'
tags:
- Data
responses:
'200':
description: Updated Data
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
delete:
summary: Delete existing Data
description: ''
x-swagger-router-controller: Data
x-swagger-router-action: destroy
operationId: destroyData
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/FeedPath'
- $ref: '#/components/parameters/IDPath'
tags:
- Data
responses:
'200':
description: Deleted Group successfully
content:
application/json:
schema:
type: string
text/csv:
schema:
type: string
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/{username}/groups/{group_key}/data:
post:
summary: Create new data for multiple feeds in a group
x-swagger-router-controller: Data
x-swagger-router-action: group_create
operationId: createGroupData
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/GroupPath'
requestBody:
content:
application/json:
schema:
type: object
required:
- feeds
properties:
location:
type: object
description: A location record with `lat`, `lon`, and [optional] `ele` properties.
required:
- lat
- lon
properties:
lat:
type: number
lon:
type: number
ele:
type: number
feeds:
description: An array of feed data records with `key` and `value` properties.
type: array
items:
type: object
required:
- key
- value
properties:
key:
type: string
value:
type: string
created_at:
type: string
description: Optional created_at timestamp which will be applied to all feed values created.
application/x-www-form-urlencoded:
schema:
type: object
required:
- feeds
properties:
location:
type: object
description: A location record with `lat`, `lon`, and [optional] `ele` properties.
required:
- lat
- lon
properties:
lat:
type: number
lon:
type: number
ele:
type: number
feeds:
description: An array of feed data records with `key` and `value` properties.
type: array
items:
type: object
required:
- key
- value
properties:
key:
type: string
value:
type: string
created_at:
type: string
description: Optional created_at timestamp which will be applied to all feed values created.
required: true
tags:
- Data
responses:
'200':
description: New data
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
type: array
items:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/{username}/groups/{group_key}/feeds/{feed_key}/data:
get:
x-swagger-router-controller: Data
x-swagger-router-action: group_all
operationId: allGroupFeedData
summary: All data for current feed in a specific group
description: ''
tags:
- Data
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/GroupPath'
- $ref: '#/components/parameters/FeedPath'
- name: start_time
in: query
description: Start time for filtering data. Returns data created after given time.
schema:
type: string
format: date-time
- name: end_time
in: query
description: End time for filtering data. Returns data created before give time.
schema:
type: string
format: date-time
- name: limit
in: query
description: Limit the number of records returned.
schema:
type: integer
responses:
'200':
description: An array of data
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
type: array
items:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
post:
summary: Create new Data in a feed belonging to a particular group
x-swagger-router-controller: Data
x-swagger-router-action: group_feed_create
operationId: createGroupFeedData
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/GroupPath'
- $ref: '#/components/parameters/FeedPath'
requestBody:
$ref: '#/components/requestBodies/createDataDatum'
tags:
- Data
responses:
'200':
description: New data
content:
application/json:
schema:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/{username}/groups/{group_key}/feeds/{feed_key}/data/batch:
post:
summary: Create multiple new Data records in a feed belonging to a particular group
x-swagger-router-controller: Data
x-swagger-router-action: group_feed_batch
operationId: batchCreateGroupFeedData
parameters:
- $ref: '#/components/parameters/UsernamePath'
- $ref: '#/components/parameters/GroupPath'
- $ref: '#/components/parameters/FeedPath'
requestBody:
$ref: '#/components/requestBodies/batchCreateDataData'
tags:
- Data
responses:
'200':
description: New data
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataResponse'
text/csv:
schema:
type: array
items:
$ref: '#/components/schemas/DataResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/webhooks/feed/:token:
post:
summary: Send data to a feed via webhook URL.
description: ''
x-swagger-router-controller: WebhookReceivers
x-swagger-router-action: create
x-code-samples:
- lang: curl
source: curl -F 'value=65.5' https://io.adafruit.com/api/v2/webhooks/feed/12345thistoken
operationId: createWebhookFeedData
requestBody:
content:
application/json:
schema:
type: object
properties:
value:
type: string
application/x-www-form-urlencoded:
schema:
type: object
properties:
value:
type: string
description: Webhook payload containing data `value` parameter.
required: true
tags:
- Data
responses:
'200':
description: New feed data record
content:
application/json:
schema:
$ref: '#/components/schemas/Data'
text/csv:
schema:
$ref: '#/components/schemas/Data'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
/webhooks/feed/:token/raw:
post:
summary: Send arbitrary data to a feed via webhook URL.
description: The 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 sender. If feed history is turned on, payloads will be truncated at 1024 bytes. If feed history is turned off, payloads will be truncated at 100KB.
x-swagger-router-controller: WebhookReceivers
x-swagger-router-action: createRaw
x-code-samples:
- lang: curl
source: "curl --header 'Content-Type: application/json' \\\n --request POST \\\n --data '{\"some json\": \"goes here\", \"id\": 12345}' \\\n https://io.adafruit.com/api/v2/webhooks/feed/12345thistoken/raw"
operationId: createRawWebhookFeedData
tags:
- Data
responses:
'200':
description: New feed data record
content:
application/json:
schema:
$ref: '#/components/schemas/Data'
text/csv:
schema:
$ref: '#/components/schemas/Data'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Server Error
components:
requestBodies:
batchCreateDataData:
content:
application/json:
schema:
type: array
items:
type: object
properties:
value:
type: string
created_at:
type: string
format: dateTime
lat:
type: string
lon:
type: string
ele:
type: string
epoch:
type: number
application/x-www-form-urlencoded:
schema:
type: array
items:
type: object
properties:
value:
type: string
created_at:
type: string
format: dateTime
lat:
type: string
lon:
type: string
ele:
type: string
epoch:
type: number
description: '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).'
required: true
createDataDatum:
content:
application/json:
schema:
type: object
properties:
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adafruit-io/refs/heads/main/openapi/adafruit-io-data-api-openapi.yml