openapi: 3.0.0 info: title: Adafruit IO REST Activities Feeds 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 \n#include \n#include \n#include \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: Feeds paths: /{username}/feeds: get: x-swagger-router-controller: Feeds x-swagger-router-action: all operationId: allFeeds summary: All feeds for current user description: The Feeds endpoint returns information about the user's feeds. The response includes the latest value of each feed, and other metadata about each feed. tags: - Feeds parameters: - $ref: '#/components/parameters/UsernamePath' responses: '200': description: An array of feeds content: application/json: schema: type: array items: $ref: '#/components/schemas/Feed' text/csv: schema: type: array items: $ref: '#/components/schemas/Feed' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Server Error post: summary: Create a new Feed description: '' x-swagger-router-controller: Feeds x-swagger-router-action: create operationId: createFeed parameters: - $ref: '#/components/parameters/UsernamePath' - $ref: '#/components/parameters/GroupParam' requestBody: $ref: '#/components/requestBodies/createFeedFeed' tags: - Feeds responses: '200': description: New feed content: application/json: schema: $ref: '#/components/schemas/Feed' text/csv: schema: $ref: '#/components/schemas/Feed' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Server Error /{username}/feeds/{feed_key}: get: description: Returns feed based on the feed key summary: Get feed by feed key x-swagger-router-controller: Feeds x-swagger-router-action: get operationId: getFeed tags: - Feeds responses: '200': description: Feed response content: application/json: schema: $ref: '#/components/schemas/Feed' text/csv: schema: $ref: '#/components/schemas/Feed' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Server Error parameters: - $ref: '#/components/parameters/UsernamePath' - $ref: '#/components/parameters/FeedPath' put: summary: Replace an existing Feed x-swagger-router-controller: Feeds x-swagger-router-action: replace operationId: replaceFeed description: '' parameters: - $ref: '#/components/parameters/UsernamePath' - $ref: '#/components/parameters/FeedPath' requestBody: $ref: '#/components/requestBodies/createFeedFeed' tags: - Feeds responses: '200': description: Updated feed content: application/json: schema: $ref: '#/components/schemas/Feed' text/csv: schema: $ref: '#/components/schemas/Feed' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Server Error patch: summary: Update properties of an existing Feed description: '' x-swagger-router-controller: Feeds x-swagger-router-action: update operationId: updateFeed parameters: - $ref: '#/components/parameters/UsernamePath' - $ref: '#/components/parameters/FeedPath' requestBody: $ref: '#/components/requestBodies/createFeedFeed' tags: - Feeds responses: '200': description: Updated feed content: application/json: schema: $ref: '#/components/schemas/Feed' text/csv: schema: $ref: '#/components/schemas/Feed' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Server Error delete: summary: Delete an existing Feed description: '' x-swagger-router-controller: Feeds x-swagger-router-action: destroy operationId: destroyFeed parameters: - $ref: '#/components/parameters/UsernamePath' - $ref: '#/components/parameters/FeedPath' tags: - Feeds responses: '200': description: Deleted feed successfully '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Server Error /{username}/feeds/{feed_key}/details: get: description: Returns more detailed feed record based on the feed key summary: Get detailed feed by feed key x-swagger-router-controller: Feeds x-swagger-router-action: details operationId: getFeedDetails tags: - Feeds responses: '200': description: Feed response content: application/json: schema: $ref: '#/components/schemas/Feed' text/csv: schema: $ref: '#/components/schemas/Feed' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Server Error parameters: - $ref: '#/components/parameters/UsernamePath' - $ref: '#/components/parameters/FeedPath' /{username}/groups/{group_key}/add: post: summary: Add an existing Feed to a Group description: '' x-swagger-router-controller: Groups x-swagger-router-action: add_feed operationId: addFeedToGroup tags: - Feeds parameters: - $ref: '#/components/parameters/GroupPath' - $ref: '#/components/parameters/UsernamePath' - $ref: '#/components/parameters/FeedParam' responses: '200': description: Updated group content: application/json: schema: $ref: '#/components/schemas/Group' text/csv: schema: $ref: '#/components/schemas/Group' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Server Error /{username}/groups/{group_key}/remove: post: summary: Remove a Feed from a Group description: '' x-swagger-router-controller: Groups x-swagger-router-action: remove_feed operationId: removeFeedFromGroup tags: - Feeds parameters: - $ref: '#/components/parameters/GroupPath' - $ref: '#/components/parameters/UsernamePath' - $ref: '#/components/parameters/FeedParam' responses: '200': description: Updated group content: application/json: schema: $ref: '#/components/schemas/Group' text/csv: schema: $ref: '#/components/schemas/Group' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Server Error /{username}/groups/{group_key}/feeds: get: x-swagger-router-controller: GroupFeeds x-swagger-router-action: group_all operationId: allGroupFeeds summary: All feeds for current user in a given group description: The 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, but only for feeds within the given group. tags: - Feeds parameters: - $ref: '#/components/parameters/GroupPath' - $ref: '#/components/parameters/UsernamePath' responses: '200': description: An array of feeds content: application/json: schema: type: array items: $ref: '#/components/schemas/Feed' text/csv: schema: type: array items: $ref: '#/components/schemas/Feed' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Server Error post: summary: Create a new Feed in a Group description: '' x-swagger-router-controller: GroupFeeds x-swagger-router-action: group_create operationId: createGroupFeed parameters: - $ref: '#/components/parameters/UsernamePath' - $ref: '#/components/parameters/GroupPath' requestBody: $ref: '#/components/requestBodies/createFeedFeed' tags: - Feeds responses: '200': description: New feed content: application/json: schema: $ref: '#/components/schemas/Feed' text/csv: schema: $ref: '#/components/schemas/Feed' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Server Error components: requestBodies: createFeedFeed: content: application/json: schema: type: object properties: name: type: string key: type: string description: type: string license: type: string application/x-www-form-urlencoded: schema: type: object properties: name: type: string key: type: string description: type: string license: type: string required: true parameters: UsernamePath: name: username in: path required: true description: a valid username string schema: type: string GroupPath: name: group_key in: path required: true schema: type: string GroupParam: name: group_key in: query schema: type: string FeedParam: name: feed_key in: query schema: type: string FeedPath: name: feed_key description: a valid feed key in: path required: true schema: type: string schemas: ShallowGroup: type: object properties: id: type: number readOnly: true name: type: string description: type: string created_at: type: string readOnly: true updated_at: readOnly: true type: string Feed: type: object properties: id: type: number readOnly: true name: type: string key: type: string group: type: object readOnly: true additionalProperties: $ref: '#/components/schemas/ShallowGroup' groups: type: array readOnly: true items: $ref: '#/components/schemas/ShallowGroup' description: type: string details: type: object description: Additional details about this feed. readOnly: true properties: shared_with: type: array description: Access control list for this feed items: type: object data: type: object properties: first: type: object additionalProperties: $ref: '#/components/schemas/Data' last: type: object additionalProperties: $ref: '#/components/schemas/Data' count: type: integer description: Number of data points stored by this feed. unit_type: type: string unit_symbol: type: string history: type: boolean visibility: type: string default: private enum: - private - public license: type: string enabled: type: boolean readOnly: true last_value: type: string readOnly: true status: type: string readOnly: true status_notify: type: boolean description: Is status notification active? status_timeout: type: integer description: Status notification timeout in minutes. created_at: type: string readOnly: true updated_at: type: string readOnly: true Group: type: object properties: id: type: number readOnly: true name: type: string description: type: string feeds: type: array readOnly: true items: $ref: '#/components/schemas/Feed' created_at: type: string readOnly: true updated_at: readOnly: true type: string Data: type: object properties: id: type: string readOnly: true value: type: string feed_id: type: number group_id: readOnly: true type: number expiration: type: string lat: type: number lon: type: number ele: type: number completed_at: readOnly: true type: string created_at: readOnly: true type: string updated_at: readOnly: true type: string created_epoch: readOnly: true type: number securitySchemes: HeaderKey: description: The AIO Key is used to restrict or grant access to your data. The key is unique, and you can generate a key per feed, and control it in many different ways. The easiest process is to just use your automatically generated master key. You can access this key right from the right-hand side of your dashboard or from an individual feed page. type: apiKey in: header name: X-AIO-Key QueryKey: description: The AIO Key is used to restrict or grant access to your data. The key is unique, and you can generate a key per feed, and control it in many different ways. The easiest process is to just use your automatically generated master key. You can access this key right from the right-hand side of your dashboard or from an individual feed page. type: apiKey in: query name: X-AIO-Key HeaderSignature: description: The AIO Signature is an AWS inspired request signature. type: apiKey in: header name: X-AIO-Signature